{"id":"d055a448-fb5a-49ef-8ecb-26c641695fbd","shortId":"WP4prD","kind":"skill","title":"ql-housekeep","tagline":"Detect repo-hygiene issues that accumulate during long-running autonomous development (merge-conflict markers, orphan worktrees, CPC-variant duplicates, stale branches, version-manifest drift). Detection-only by default — reports findings, never deletes or modifies without explic","description":"# ql-housekeep — repo hygiene detector\n\n## Purpose\n\n`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.\n\nThis 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.\n\n## When to use\n\n- Before starting a new `/ql-brainstorm` cycle on a repo that has been running parallel execution for weeks.\n- As a gate in `ql-execute` between waves if you suspect accumulated drift.\n- Manually, when you want a structured view of \"what is wrong with the repo right now that the runtime cannot see\".\n\n## What it detects\n\n### 1. Merge-conflict markers in tracked files\n\nPattern: `^<<<<<<<` or `^=======$` or `^>>>>>>>`. These are the signature of an abandoned git merge that was committed without resolution.\n\nNote: 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.\n\nCommand:\n```bash\ngrep -rn --include='*.md' --include='*.sh' --include='*.ts' --include='*.js' \\\n  --include='*.py' --include='*.json' --include='*.yml' --include='*.yaml' \\\n  -E '^<<<<<<<|^=======$|^>>>>>>>' .\n```\n\n### 2. Orphan git worktrees\n\nDirectories under `.claude/worktrees/agent-*` or `.ql-wt/<story-id>/` that git no longer tracks.\n\nCommand:\n```bash\nfor d in .claude/worktrees/agent-* .ql-wt/*; do\n  [ -d \"$d\" ] || continue\n  git worktree list | grep -q \"$d\" || echo \"$d\"\ndone\n```\n\n### 3. CPC-variant duplicate files\n\nPattern: 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.\n\nCommand:\n```bash\nfind . -path ./node_modules -prune -o -name '*-CPC-andyz-*' -print\n```\n\n### 4. Superseded-but-not-deleted files\n\nFiles whose header docstring says \"supersedes X\" where X still exists. Currently catches:\n- `lib/crash-recovery.sh` (superseded by `lib/resilience.sh:3`)\n\nCommand (case-insensitive `Supersedes` / `supersedes`):\n```bash\nfor f in lib/*.sh; do\n  sup=$(grep -oiE 'supersedes lib/[a-z_-]+\\.sh' \"$f\" 2>/dev/null | head -1 | awk '{print $NF}')\n  [ -n \"$sup\" ] && [ -f \"$sup\" ] && echo \"DEAD: $sup (superseded by $f)\"\ndone\n```\n\n### 5. Stale branches\n\n- `worktree-agent-*` branches that are no longer referenced by any live worktree.\n- `ql/*` and `fix/*` branches whose tip commits are strict ancestors of master OR have been inactive > 90 days.\n\nCommand:\n```bash\ngit branch -a --format='%(refname:short) %(committerdate:short) %(upstream:track)' \\\n  | awk '$1 ~ /^(ql|fix|worktree-agent)/' \\\n  | sort -k2\n```\n\n### 6. Plugin version / CHANGELOG drift\n\n`.claude-plugin/plugin.json.version` must match `.claude-plugin/marketplace.json.version` and must have a corresponding entry in `CHANGELOG.md`.\n\nCommand:\n```bash\nplugin_v=$(jq -r .version .claude-plugin/plugin.json 2>/dev/null)\nmarket_v=$(jq -r '.plugins[0].version // .version' .claude-plugin/marketplace.json 2>/dev/null)\n[ \"$plugin_v\" = \"$market_v\" ] || echo \"version mismatch: plugin=$plugin_v market=$market_v\"\ngrep -q \"^## \\[$plugin_v\\]\" CHANGELOG.md 2>/dev/null || echo \"CHANGELOG missing entry for v$plugin_v\"\n```\n\n### 7. Stale `quantum.json`\n\n`quantum.json.updatedAt` older than 30 days with the project in active development suggests the team isn't dogfooding.\n\nCommand (cross-platform: GNU `date`, macOS `date`, Git Bash):\n```bash\nlast=$(jq -r '.updatedAt // empty' quantum.json 2>/dev/null)\nif [ -n \"$last\" ]; then\n  # Portable ISO-8601 → epoch via python3 (GNU date -d is not on macOS/BSD)\n  age_days=$(python3 -c \"\nimport datetime,sys\nt = datetime.datetime.fromisoformat('$last'.replace('Z', '+00:00'))\nnow = datetime.datetime.now(datetime.timezone.utc)\nprint(int((now - t).total_seconds() // 86400))\n\" 2>/dev/null)\n  [ -n \"$age_days\" ] && [ \"$age_days\" -gt 30 ] && echo \"quantum.json not updated in $age_days days\"\nfi\n```\nFallback 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.\n\n### 8. Duplicate test files (same logical test in two files)\n\nPattern: two test files whose paths differ only by a suffix that indicates a fork (`-CPC-*`, `.bak`, `.old`, ` copy`).\n\nCommand:\n```bash\nfind tests -type f -name '*.sh' \\\n  | sed -E 's/(-CPC-[^/]+|\\.bak|\\.old| copy)?\\.sh$//' \\\n  | sort | uniq -d\n```\n\n## Anti-rationalization guards\n\n| The agent says… | The truth is… |\n|-----------------|---------------|\n| \"These orphan worktrees must be live runs\" | Live worktrees appear in `git worktree list`. If they don't, they're orphans. |\n| \"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`). |\n| \"The merge-conflict markers are inside a docstring example\" | Then they wouldn't pass lint or test. The code is not doing conditional-skip. |\n| \"The supersedes comment is ambiguous\" | Read the file, confirm, then report. Never silently swallow detection. |\n| \"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. |\n\n## How to run\n\nThe skill produces a structured report to stdout. No flags required.\n\n```bash\n# In Claude Code:\n/quantum-loop:ql-housekeep\n```\n\nThe skill will:\n1. Run each detector in turn.\n2. Emit a section per category with findings.\n3. Summarize as a `findings[]` JSON block at the end.\n4. Return an exit code: 0 = clean, 1 = findings present.\n\n## What it does NOT do\n\n- Delete files.\n- Rename files.\n- Prune branches.\n- Remove worktrees.\n- Modify CHANGELOG or plugin manifests.\n- Commit anything.\n\nFixes are the user's job, potentially driven by the consolidation design in `docs/plans/2026-04-21-p0-consolidation-design.md`.\n\n## Output format\n\n```json\n{\n  \"timestamp\": \"<ISO 8601>\",\n  \"branch\": \"<current branch>\",\n  \"summary\": {\n    \"conflict_markers\": 0,\n    \"orphan_worktrees\": 0,\n    \"cpc_variants\": 0,\n    \"superseded_files\": 0,\n    \"stale_branches\": 0,\n    \"version_drift\": false,\n    \"stale_quantum_json\": false,\n    \"duplicate_test_files\": 0\n  },\n  \"findings\": [\n    {\n      \"category\": \"conflict_markers\",\n      \"severity\": \"high\",\n      \"file\": \"README.md\",\n      \"lines\": [368, 372, 399],\n      \"detail\": \"<content snippet>\"\n    }\n  ],\n  \"recommended_next_steps\": [\n    \"Review idea-stage/AUDIT_QL.md before taking action\",\n    \"Do not delete anything without user confirmation\",\n    \"See docs/plans/2026-04-21-p0-consolidation-design.md for a full consolidation protocol\"\n  ]\n}\n```\n\n## Integration with other skills\n\n- **`ql-brainstorm`**: Reads prior `ql-housekeep` output to warn about hygiene before inviting new design work.\n- **`ql-execute`**: Between waves, runs `ql-housekeep` as a lightweight check; warns user but does not auto-fix.\n- **`ql-review`**: Post-merge review phase inspects whether the merge introduced any of categories 1, 3, 4, 8.\n\n## Known limitations\n\n- Detection patterns are intentionally conservative — false negatives preferred over false positives because this drives user action.\n- Category 5 (stale branches) uses simple heuristics; borderline cases should be manually classified.\n- The skill does not detect content-level duplicate code across stories; that is the job of `agents/duplication-detector.md`.","tags":["housekeep","quantum","loop","andyzengmath","agent-skills","agentskills","claude-code","claude-code-plugin","claude-code-skill","skillsmp"],"capabilities":["skill","source-andyzengmath","skill-ql-housekeep","topic-agent-skills","topic-agentskills","topic-claude-code","topic-claude-code-plugin","topic-claude-code-skill","topic-skillsmp"],"categories":["quantum-loop"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/andyzengmath/quantum-loop/ql-housekeep","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add andyzengmath/quantum-loop","source_repo":"https://github.com/andyzengmath/quantum-loop","install_from":"skills.sh"}},"qualityScore":"0.461","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 22 github stars · SKILL.md body (7,873 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:05:28.254Z","embedding":null,"createdAt":"2026-04-24T01:02:06.422Z","updatedAt":"2026-05-18T19:05:28.254Z","lastSeenAt":"2026-05-18T19:05:28.254Z","tsv":"'+00':630 '-1':414 '-8601':607,691 '/audit_ql.md':95,347,1022 '/dev/null':412,519,533,553,600,643 '/marketplace.json':531 '/marketplace.json.version':498 '/node_modules':355 '/plugin.json':517 '/plugin.json.version':492 '/ql-brainstorm':126 '/quantum-loop':895 '0':525,931,978,981,984,987,990,1001 '00':631 '1':177,226,476,902,933,1099 '2':270,411,518,532,552,599,642,908 '3':308,387,916,1100 '30':568,650,682 '368':1011 '372':1012 '399':1013 '4':363,926,1101 '5':429,1122 '6':484 '7':562 '8':700,1102 '86400':641 '90':461 'a-z':406 'abandon':194,872 'accumul':10,61,151 'across':1144 'action':804,1025,1120 'activ':574 'actuat':79 'age':618,645,647,656 'agent':434,481,753 'agents/duplication-detector.md':1151 'ambigu':837 'ancestor':454 'andyz':319,361 'anti':749 'anti-ration':748 'anyth':955,1029 'appear':767 'auto':81,1081 'auto-fix':80,1080 'autonom':15,64 'awk':415,475 'bak':726,741 'bash':250,287,352,394,464,508,591,592,730,891 'block':241,922 'borderlin':1128 'brainstorm':1046 'branch':28,431,435,448,466,946,974,989,1124 'c':621 'cannot':172 'case':390,1129 'case-insensit':389 'catalogu':96 'catch':382 'categori':98,913,1003,1098,1121 'chang':862 'changelog':487,555,848,858,867,950 'changelog.md':506,551 'char':223 'check':1074 'classifi':1133 'claud':490,496,515,529,893 'claude-plugin':489,495,514,528 'claude/worktrees/agent-':276,291 'clean':932 'code':826,894,930,1143 'coexist':342 'column':225 'command':249,286,351,388,463,507,582,729 'comment':835 'commit':199,451,954 'committerd':471 'compact':874 'compar':665,687 'comput':672 'condit':831 'conditional-skip':830 'confirm':803,841,1032 'conflict':19,180,240,810,976,1004 'conserv':1109 'consolid':966,1038 'content':1140 'content-level':1139 'continu':298 'copi':326,728,743 'correspond':503 'could':784 'cpc':24,310,318,360,725,740,782,982 'cpc-andyz':359 'cpc-andyz-zh84k':317 'cpc-variant':23,309,781 'cross':584 'cross-platform':583 'current':381 'cycl':127 'd':289,296,297,304,306,613,680,747 'date':587,589,612,676,685 'date-str':684 'datetim':623 'datetime.datetime.fromisoformat':626 'datetime.datetime.now':633 'datetime.timezone.utc':634 'day':462,569,619,646,648,657,658,683 'dead':423 'default':37 'delet':41,368,779,794,941,1028 'design':967,1060 'detail':1014 'detect':4,34,176,335,847,1105,1138 'detection-on':33 'detector':51,76,905 'develop':16,65,575 'differ':716 'directori':274 'docs/plans/2026-04-21-p0-consolidation-design.md':806,969,1034 'docstr':373,815 'dogfood':581 'done':307,428 'downstream':876 'drift':32,152,488,992 'drive':1118 'driven':963 'duplic':26,312,701,998,1142 'e':269,738 'e.g':216 'echo':305,422,538,554,651 'eight':97 'emit':909 'empti':597,866 'end':925 'entri':504,557 'epoch':608 'exact':221 'exampl':816 'execut':136,145,1064 'exist':90,380 'exit':929 'explic':45 'explicit':84 'f':396,410,420,427,734 'failur':59,101 'fallback':660 'fals':208,243,993,997,1110,1114 'false-posit':207 'fi':659 'file':184,313,315,369,370,703,709,713,840,942,944,986,1000,1008 'find':39,353,731,915,920,934,1002 'first':105 'fix':82,447,478,956,1082 'flag':889 'follow':219 'fork':333,724 'format':468,971 'full':1037 'gate':141 'git':195,272,282,299,465,590,769 'gnu':586,611 'grep':251,302,402,547 'gt':649 'guard':751 'harden':332 'head':214,218,413 'header':372 'heurist':1127 'high':1007 'housekeep':3,48,55,898,1051,1070 'human':71 'hygien':7,50,58,100,1056 'idea':93,345,1020 'idea-stag':92,344,1019 'implement':696 'import':622 'inact':460 'includ':253,255,257,259,261,263,265,267 'indic':328,722 'insensit':391 'insid':813 'inspect':1091 'int':636 'integr':1040 'intent':1108 'introduc':1095 'invit':1058 'isn':579 'iso':606,690 'issu':8 'iter':111 'job':106,961,1149 'jq':511,522,594 'js':260 'json':264,921,972,996 'k2':483 'know':860 'known':1103 'last':593,603,627,666 'level':1141 'lexicograph':667,694 'lexicographic-sort':693 'lib':398,405 'lib/crash-recovery.sh':383 'lib/resilience.sh':386 'lightweight':1073 'like':338 'limit':248,1104 'line':1010 'lint':822 'list':301,771 'live':443,763,765 'logic':705 'long':13 'long-run':12 'longer':284,439 'lose':785 'm':679 'maco':588 'macos/bsd':617 'manifest':31,953 'manual':153,1132 'markdown':211 'marker':20,181,811,977,1005 'market':520,536,544,545 'master':103,456 'match':316,494 'md':254 'mean':868 'merg':18,179,196,809,1088,1094 'merge-conflict':17,178,808 'minus':681 'mismatch':540 'miss':556 'modifi':43,949 'must':493,500,761 'n':418,602,644 'name':358,735 'negat':1111 'never':40,844 'new':125,1059 'next':109,1016 'nf':417 'nice':852 'nice-to-hav':851 'note':202 'o':357 'oie':403 'old':727,742 'older':566 'onedr':324 'onedrive-renam':323 'orphan':21,271,759,778,979 'output':970,1052 'parallel':135,331 'parallel-harden':330 'pass':821 'path':354,715 'pattern':185,204,314,710,1106 'per':912 'phase':1090 'pipelin':66,110,341 'platform':585 'plugin':485,491,497,509,516,524,530,534,541,542,549,560,952 'portabl':605 'posit':209,244,1115 'post':1087 'post-merg':1086 'potenti':962 'practic':228 'pre':671 'pre-comput':670 'prefer':698,1112 'present':935 'print':362,416,635 'prior':1048 'produc':115,882 'project':337,572 'promot':349,797 'protocol':350,1039 'prune':356,945 'purpos':52 'py':262 'python3':610,620,662,699 'q':303,548 'ql':2,47,54,144,279,293,445,477,897,1045,1050,1063,1069,1084 'ql-brainstorm':1044 'ql-execut':143,1062 'ql-housekeep':1,46,53,896,1049,1068 'ql-review':1083 'ql-wt':278,292 'quantum':995 'quantum.json':564,598,652 'quantum.json.updatedat':565 'r':512,523,595 'rare':231 'ration':750 're':777 'read':838,1047 'readme.md':1009 'real':239 'recommend':1015 'referenc':440 'refnam':469 'reli':856 'remov':947 'renam':325,943 'replac':628 'repo':6,49,130,166 'repo-hygien':5 'report':38,796,843,885 'requir':236,890 'resolut':201 'return':927 'review':1018,1085,1089 'right':167 'rn':252 'run':14,67,134,764,879,903,1067 'runtim':171 'say':374,754 'scope':87 'second':640 'section':911 'sed':737 'see':173,343,805,1033 'self':247 'self-limit':246 'separ':800 'setext':213 'setext-head':212 'seven':222 'sever':1006 'sh':256,399,409,736,744 'short':470,472 'sibl':234 'signatur':191 'silent':845 'simpl':1126 'skill':89,791,881,900,1043,1135 'skill-ql-housekeep' 'skip':832 'sort':482,745 'sortabl':695 'source-andyzengmath' 'stage':94,346,1021 'stale':27,430,563,988,994,1123 'start':123 'state':117 'stdout':887 'step':1017 'still':379 'stori':1145 'strict':453 'string':686 'structur':158,884 'suffix':720 'suggest':576 'summar':917 'summari':975 'sup':401,419,421,424 'supersed':365,375,384,392,393,404,425,834,985 'superseded-but-not-delet':364 'surfac':56 'suspect':150 'swallow':846 'sweep':72 'sys':624 'take':1024 'team':578,870 'test':702,706,712,732,824,999 'theoret':206 'threshold':673 'timestamp':973 'tip':450 'topic-agent-skills' 'topic-agentskills' 'topic-claude-code' 'topic-claude-code-plugin' 'topic-claude-code-skill' 'topic-skillsmp' 'total':639 'track':183,285,474 'truth':756 'ts':258 'turn':907 'two':340,708,711 'type':733 'tz':674 'u':677 'unavail':664 'underlin':215 'uniq':746 'updat':654 'updatedat':596 'upstream':473 'use':121,1125 'user':802,855,959,1031,1076,1119 'user-confirm':801 'utc':675 'v':510,521,535,537,543,546,550,559,561 'variant':25,311,783,983 'version':30,486,513,526,527,539,864,991 'version-manifest':29 'via':609 'view':159 'want':156 'warn':1054,1075 'wave':147,1066 'week':69,138 'whether':1092 'whose':371,449,714 'without':44,70,200,1030 'work':688,786,1061 'worktre':22,273,300,433,444,480,760,766,770,948,980 'worktree-ag':432,479 'wouldn':819 'wrong':163 'wt':280,294 'x':376,378 'y':678 'yaml':268 'yml':266 'z':408,629 'zh84k':320","prices":[{"id":"4ff61279-cdcf-4663-a8ac-dbd10383c750","listingId":"d055a448-fb5a-49ef-8ecb-26c641695fbd","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"andyzengmath","category":"quantum-loop","install_from":"skills.sh"},"createdAt":"2026-04-24T01:02:06.422Z"}],"sources":[{"listingId":"d055a448-fb5a-49ef-8ecb-26c641695fbd","source":"github","sourceId":"andyzengmath/quantum-loop/ql-housekeep","sourceUrl":"https://github.com/andyzengmath/quantum-loop/tree/master/skills/ql-housekeep","isPrimary":false,"firstSeenAt":"2026-04-24T01:02:06.422Z","lastSeenAt":"2026-05-18T19:05:28.254Z"}],"details":{"listingId":"d055a448-fb5a-49ef-8ecb-26c641695fbd","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"andyzengmath","slug":"ql-housekeep","github":{"repo":"andyzengmath/quantum-loop","stars":22,"topics":["agent-skills","agentskills","claude-code","claude-code-plugin","claude-code-skill","skillsmp"],"license":"mit","html_url":"https://github.com/andyzengmath/quantum-loop","pushed_at":"2026-05-03T18:23:03Z","description":"Spec-driven autonomous development loop for Claude Code. Combines structured PRD generation, dependency DAG execution, two-stage review gates, and Iron Law verification.","skill_md_sha":"68f4bb94904b1f71a428fab38f23a183bfa6a0cc","skill_md_path":"skills/ql-housekeep/SKILL.md","default_branch":"master","skill_tree_url":"https://github.com/andyzengmath/quantum-loop/tree/master/skills/ql-housekeep"},"layout":"multi","source":"github","category":"quantum-loop","frontmatter":{"name":"ql-housekeep","description":"Detect repo-hygiene issues that accumulate during long-running autonomous development (merge-conflict markers, orphan worktrees, CPC-variant duplicates, stale branches, version-manifest drift). Detection-only by default — reports findings, never deletes or modifies without explicit user confirmation."},"skills_sh_url":"https://skills.sh/andyzengmath/quantum-loop/ql-housekeep"},"updatedAt":"2026-05-18T19:05:28.254Z"}}