ql-housekeep

ql-housekeep — repo hygiene detector

Purpose

ql-housekeep surfaces the hygiene failures that accumulate when an autonomous development pipeline runs for weeks without human sweep. It is a detector, not an actuator. Auto-fix is explicitly out of scope.

This skill exists because idea-stage/AUDIT_QL.md catalogued eight categories of hygiene failure on master. The first job of the next pipeline iteration is to not produce that state again.

When to use

• Before starting a new /ql-brainstorm cycle on a repo that has been running parallel execution for weeks.
• As a gate in ql-execute between waves if you suspect accumulated drift.
• Manually, when you want a structured view of "what is wrong with the repo right now that the runtime cannot see".

What it detects

1. Merge-conflict markers in tracked files

Pattern: ^<<<<<<< or ^=======$ or ^>>>>>>>. These are the signature of an abandoned git merge that was committed without resolution.

Note: the ^=======$ pattern can theoretically false-positive on Markdown setext-heading underlines (e.g., a heading followed by exactly seven = chars at column 1). In practice this is rare, and the <<<<<<< + >>>>>>> siblings are required for a real conflict block, so false positives are self-limiting.

Command:

grep -rn --include='*.md' --include='*.sh' --include='*.ts' --include='*.js' \
  --include='*.py' --include='*.json' --include='*.yml' --include='*.yaml' \
  -E '^<<<<<<<|^=======$|^>>>>>>>' .

2. Orphan git worktrees

Directories under .claude/worktrees/agent-* or .ql-wt/<story-id>/ that git no longer tracks.

Command:

for d in .claude/worktrees/agent-* .ql-wt/*; do
  [ -d "$d" ] || continue
  git worktree list | grep -q "$d" || echo "$d"
done

3. CPC-variant duplicate files

Pattern: files matching *-CPC-andyz-ZH84K.*. These are OneDrive-renamed copies that indicate a parallel-hardening fork. If detected, the project likely has two pipelines coexisting — see idea-stage/AUDIT_QL.md for promotion protocol.