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.

Command:

find . -path ./node_modules -prune -o -name '*-CPC-andyz-*' -print

4. Superseded-but-not-deleted files

Files whose header docstring says "supersedes X" where X still exists. Currently catches:

• lib/crash-recovery.sh (superseded by lib/resilience.sh:3)

Command (case-insensitive Supersedes / supersedes):

for f in lib/*.sh; do
  sup=$(grep -oiE 'supersedes lib/[a-z_-]+\.sh' "$f" 2>/dev/null | head -1 | awk '{print $NF}')
  [ -n "$sup" ] && [ -f "$sup" ] && echo "DEAD: $sup (superseded by $f)"
done

5. Stale branches

• worktree-agent-* branches that are no longer referenced by any live worktree.
• ql/* and fix/* branches whose tip commits are strict ancestors of master OR have been inactive > 90 days.

Command:

git branch -a --format='%(refname:short) %(committerdate:short) %(upstream:track)' \
  | awk '$1 ~ /^(ql|fix|worktree-agent)/' \
  | sort -k2

6. Plugin version / CHANGELOG drift

.claude-plugin/plugin.json.version must match .claude-plugin/marketplace.json.version and must have a corresponding entry in CHANGELOG.md.

Command:

plugin_v=$(jq -r .version .claude-plugin/plugin.json 2>/dev/null)
market_v=$(jq -r '.plugins[0].version // .version' .claude-plugin/marketplace.json 2>/dev/null)
[ "$plugin_v" = "$market_v" ] || echo "version mismatch: plugin=$plugin_v market=$market_v"
grep -q "^## \[$plugin_v\]" CHANGELOG.md 2>/dev/null || echo "CHANGELOG missing entry for v$plugin_v"

7. Stale quantum.json

quantum.json.updatedAt older than 30 days with the project in active development suggests the team isn't dogfooding.

Command (cross-platform: GNU date, macOS date, Git Bash):

last=$(jq -r '.updatedAt // empty' quantum.json 2>/dev/null)
if [ -n "$last" ]; then
  # Portable ISO-8601 → epoch via python3 (GNU date -d is not on macOS/BSD)
  age_days=$(python3 -c "
import datetime,sys
t = datetime.datetime.fromisoformat('$last'.replace('Z', '+00:00'))
now = datetime.datetime.now(datetime.timezone.utc)
print(int((now - t).total_seconds() // 86400))
" 2>/dev/null)
  [ -n "$age_days" ] && [ "$age_days" -gt 30 ] && echo "quantum.json not updated in $age_days days"
fi

Fallback when python3 is unavailable: compare $last lexicographically against a pre-computed $threshold = "$(TZ=UTC date -u +%Y-%m-%d)" minus 30 days (date-string compare works because ISO-8601 is lexicographic-sortable); implementer should prefer python3.

8. Duplicate test files (same logical test in two files)

Pattern: two test files whose paths differ only by a suffix that indicates a fork (-CPC-*, .bak, .old, copy).

Command:

find tests -type f -name '*.sh' \
  | sed -E 's/(-CPC-[^/]+|\.bak|\.old| copy)?\.sh$//' \
  | sort | uniq -d

Anti-rationalization guards

The agent says…	The truth is…
"These orphan worktrees must be live runs"	Live worktrees appear in git worktree list. If they don't, they're orphans.
"Deleting the CPC-variant could lose work"	That's why this skill does NOT delete. It REPORTS. Promotion is a separate user-confirmed action (see docs/plans/2026-04-21-p0-consolidation-design.md).
"The merge-conflict markers are inside a docstring example"	Then they wouldn't pass lint or test. The code is not doing conditional-skip.
"The supersedes comment is ambiguous"	Read the file, confirm, then report. Never silently swallow detection.
"CHANGELOG is a nice-to-have"	Users rely on CHANGELOG to know what changed between versions. An empty CHANGELOG means the team has abandoned the compact with downstream.

How to run

The skill produces a structured report to stdout. No flags required.

# In Claude Code:
/quantum-loop:ql-housekeep

The skill will:

1. Run each detector in turn.
2. Emit a section per category with findings.
3. Summarize as a findings[] JSON block at the end.
4. Return an exit code: 0 = clean, 1 = findings present.

What it does NOT do

• Delete files.
• Rename files.
• Prune branches.
• Remove worktrees.
• Modify CHANGELOG or plugin manifests.
• Commit anything.

Fixes are the user's job, potentially driven by the consolidation design in docs/plans/2026-04-21-p0-consolidation-design.md.

Output format

{
  "timestamp": "<ISO 8601>",
  "branch": "<current branch>",
  "summary": {
    "conflict_markers": 0,
    "orphan_worktrees": 0,
    "cpc_variants": 0,
    "superseded_files": 0,
    "stale_branches": 0,
    "version_drift": false,
    "stale_quantum_json": false,
    "duplicate_test_files": 0
  },
  "findings": [
    {
      "category": "conflict_markers",
      "severity": "high",
      "file": "README.md",
      "lines": [368, 372, 399],
      "detail": "<content snippet>"
    }
  ],
  "recommended_next_steps": [
    "Review idea-stage/AUDIT_QL.md before taking action",
    "Do not delete anything without user confirmation",
    "See docs/plans/2026-04-21-p0-consolidation-design.md for a full consolidation protocol"
  ]
}

Integration with other skills

• ql-brainstorm: Reads prior ql-housekeep output to warn about hygiene before inviting new design work.
• ql-execute: Between waves, runs ql-housekeep as a lightweight check; warns user but does not auto-fix.
• ql-review: Post-merge review phase inspects whether the merge introduced any of categories 1, 3, 4, 8.

Known limitations

• Detection patterns are intentionally conservative — false negatives preferred over false positives because this drives user action.
• Category 5 (stale branches) uses simple heuristics; borderline cases should be manually classified.
• The skill does not detect content-level duplicate code across stories; that is the job of agents/duplication-detector.md.