@ikon85/agent-workflow-kit 0.10.0

package/.claude/hooks/sync-board-status.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""
+Sync GitHub Project status to the in-progress status when the current branch is
+feat/<#>- or fix/<#>-.
+
+Wired as SessionStart hook. Idempotent + scoped:
+  - only the project + status field named in the board profile
+  - only transitions {idea, triaged, spec} roles -> inProgress role (whitelist,
+    names resolved via the profile's fields.status.roles map —)
+  - silent on every failure (never blocks session start)
+
+Board-specific values (project ids, status option ids, repo slug) are NOT
+inlined — they are read from the board profile (docs/agents/board-sync.md, parsed
+by scripts/board_config.py, /setup-workflow-seeded per repo). So this hook works
+unchanged in this repo and in a consumer install alike.
+
+Lookup is TARGETED: it queries ONLY the active issue's project items (GraphQL
+issue.projectItems), not the whole board. So it has no pagination cap (the old
+`item-list --limit 500` silently dropped the newest issues on large boards) and
+ignores every Done/closed/archived item elsewhere — those are never a transition
+source, so reading them was pure noise.
+
+Audit log: .claude/logs/board-sync.log
+"""
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent / "scripts"))
+from _hook_utils import log, run_with_status as run  # noqa: E402
+from board_config import load_board_config, status_roles, ConfigError  # noqa: E402
+
+# The transition is derived from the profile's semantic role map — the hook
+# carries role KEYS (schema), never status-name vocabulary.
+_FROM_ROLES = ("idea", "triaged", "spec")
+_TARGET_ROLE = "inProgress"
+BRANCH_RE = re.compile(r"^(?:feat|fix)/([0-9]+)-")
+HOOK_NAME = "board-sync"
+
+
+def derive_transition(roles):
+    """(allowed_from_names, target_name) derived from the profile's
+    `fields.status.roles` map, or (None, reason) when the inProgress role is
+    unconfigured (old profile without the map → visible skip, never a crash).
+    Missing from-roles are tolerated — a board without an idea-like stage
+    simply has a smaller whitelist."""
+    target = roles.get(_TARGET_ROLE)
+    if not target:
+        return None, ("status role 'inProgress' not configured — add "
+                      "fields.status.roles to the board profile (see "
+                      "docs/agents/board-sync.md)")
+    allowed = {roles[r] for r in _FROM_ROLES if roles.get(r)}
+    return allowed, target
+
+# Fetch one issue's project items + their single-select field values. Matching
+# the status by FIELD ID (not the display name "Status") keeps it profile-driven.
+_ITEM_QUERY = (
+    "query($owner:String!,$repo:String!,$number:Int!){"
+    "repository(owner:$owner,name:$repo){issue(number:$number){"
+    "projectItems(first:20){nodes{id project{number} "
+    "fieldValues(first:20){nodes{"
+    "... on ProjectV2ItemFieldSingleSelectValue{name "
+    "field{... on ProjectV2SingleSelectField{id}}}"
+    "}}}}}}}"
+)
+
+
+def resolve_status_from_items(issue, proj_number, field_id):
+    """Pure decision core: given the already-parsed `data.repository.issue`
+    node from the board-item GraphQL response, disambiguate this issue's item
+    in `proj_number` and extract its value for `field_id`.
+
+    No subprocess/network — parsed dict in, decision out. Returns
+    (item_id, current_status) on a clean single-item match (current is ""
+    when the field has never been set), or (None, reason) on any miss:
+    issue not found, 0/2+ project items in the target project (incl. items
+    that belong to a *different* project number), or a malformed item id.
+    """
+    if not issue:
+        return None, "issue not found"
+
+    nodes = (issue.get("projectItems") or {}).get("nodes") or []
+    ours = [n for n in nodes if str((n.get("project") or {}).get("number")) == proj_number]
+    if len(ours) != 1:
+        return None, f"{len(ours)} project items in project {proj_number}"
+
+    item_id = ours[0].get("id")
+    if not isinstance(item_id, str) or not item_id.startswith("PVTI_"):
+        return None, "item id missing or malformed"
+
+    current = ""
+    for fv in (ours[0].get("fieldValues") or {}).get("nodes") or []:
+        if (fv.get("field") or {}).get("id") == field_id:
+            current = fv.get("name", "")
+            break
+    return item_id, current
+
+
+def fetch_board_item(repo_owner, repo_name, proj_number, field_id, issue_num):
+    """(item_id, current_status) for issue_num's item in the project, or
+    (None, reason) on any miss. Reads only this issue's items — no board-wide
+    list, no pagination cap, blind to Done/archived items elsewhere."""
+    rc, out = run([
+        "gh", "api", "graphql",
+        "-f", f"query={_ITEM_QUERY}",
+        "-F", f"owner={repo_owner}",
+        "-F", f"repo={repo_name}",
+        "-F", f"number={issue_num}",
+    ])
+    if rc != 0 or not out:
+        return None, "gh graphql failed"
+    try:
+        issue = json.loads(out)["data"]["repository"]["issue"]
+    except (json.JSONDecodeError, KeyError, TypeError):
+        return None, "invalid graphql response"
+    return resolve_status_from_items(issue, proj_number, field_id)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--dry-run", action="store_true", help="Log intended action without writing")
+    parser.add_argument("--issue", help="Override issue # (else parsed from current branch)")
+    args = parser.parse_args()
+
+    try:
+        cfg = load_board_config()
+    except ConfigError as e:
+        log(HOOK_NAME, f"skip: board profile unavailable ({e})")
+        return 0
+    repo_owner, repo_name = cfg["repo"].split("/", 1)
+    proj_number = str(cfg["project"]["number"])
+    node_id = cfg["project"]["nodeId"]
+    field_id = cfg["fields"]["status"]["id"]
+    allowed_from, target_status = derive_transition(status_roles(cfg))
+    if allowed_from is None:
+        log(HOOK_NAME, f"skip: {target_status}")
+        return 0
+    target_id = cfg["fields"]["status"]["options"].get(target_status)
+    if not target_id:
+        log(HOOK_NAME, f"skip: status {target_status!r} (role 'inProgress') not in board profile options")
+        return 0
+
+    if args.issue:
+        issue_num = args.issue
+        branch = f"(override --issue {issue_num})"
+    else:
+        rc, branch_out = run(["git", "branch", "--show-current"])
+        branch = branch_out.strip()
+        if rc != 0 or not branch:
+            return 0
+        m = BRANCH_RE.match(branch)
+        if not m:
+            return 0
+        issue_num = m.group(1)
+
+    item_id, current = fetch_board_item(repo_owner, repo_name, proj_number, field_id, issue_num)
+    if item_id is None:
+        log(HOOK_NAME, f"branch={branch} issue={issue_num} skip: {current}")
+        return 0
+
+    if current not in allowed_from:
+        log(HOOK_NAME, f"branch={branch} issue={issue_num} item={item_id} status={current} skip: not in whitelist")
+        return 0
+
+    if args.dry_run:
+        log(HOOK_NAME, f"branch={branch} issue={issue_num} item={item_id} before={current} DRY-RUN would set {target_status!r}")
+        return 0
+
+    rc, _ = run([
+        "gh", "project", "item-edit",
+        "--id", item_id,
+        "--project-id", node_id,
+        "--field-id", field_id,
+        "--single-select-option-id", target_id,
+    ])
+    if rc == 0:
+        log(HOOK_NAME, f"branch={branch} issue={issue_num} item={item_id} before={current} after={target_status}")
+    else:
+        log(HOOK_NAME, f"branch={branch} issue={issue_num} item={item_id} before={current} ERROR: item-edit failed")
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception as e:
+        log(HOOK_NAME, f"unexpected error: {e}")
+        sys.exit(0)

package/.claude/skills/ask-matt/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: ask-matt
+description: Ask which skill or flow fits your situation. A router over the skills in this repo.
+disable-model-invocation: true
+---
+
+# Ask Matt
+
+> **Homage + Router.** Adopted from Matt Pocock's `ask-matt` (MIT, github.com/mattpocock/skills @ `7a83a3a`) — the name stays as a nod to upstream, the content is adapted to *this* repo's skill set (the plan→execute→land→learn line plus our gates, cross-model review, and land/learn skills). Provenance: `docs/agents/provenance.md`. Folder↔upstream-name note: `/diagnose` = upstream `diagnosing-bugs`, `/write-a-skill` = upstream `writing-great-skills` (renamed upstream, local names kept).
+
+You don't remember every skill, so ask.
+
+A **flow** is a path through the skills. Most paths run along one **main flow**; on-ramps and gates merge onto it. Everything else is standalone, or a vocabulary layer that runs underneath.
+
+## The main flow: idea → ship
+
+The route most work travels. You have an idea and want it built.
+
+0. **Size unclear? `/scale-check` first.** A new undertaking without a clear
+   size — a new app, a big cross-cutting change, a genuine "where do I even
+   start?" — runs `/scale-check` before anything else: a short plain-language
+   dialog that routes it to a Program, a Feature, a Direct-Slice, or a Bug,
+   and hands back a paste-ready start prompt for the chosen route. **Rule: a
+   new build without a clear size runs `scale-check` first** — never guess
+   the altitude and jump straight into step 1. Skip this step outright when
+   the size is already obvious (a one-line fix, a known bug) — go straight to
+   the entry that fits.
+<!-- mirror-xform:start codex-escalation -->
+1. **`/grill-with-docs`** — sharpen the idea by relentless interview. Start here when you **have a codebase**: it's stateful, retaining what it learns in `CONTEXT.md` and ADRs. (No codebase? Use `/grill-me` — see Standalone.) For high-stakes/hard-to-reverse work, add the cross-model variant **`/grill-with-docs-codex`** (see Cross-model review).
+<!-- mirror-xform:end -->
+2. **Branch — can you settle every question in conversation?** If a question needs a runnable answer (state, business logic, a UI you have to see), detour through a prototype, bridged by **`/handoff`** in both directions (see Crossing sessions): `/handoff` out → fresh session → **`/prototype`** to answer with throwaway code → `/handoff` back what you learned.
+3. **Gate — does a slice hinge on an unknown?** Clear it *before* building (see Gate-before-build): a binary fact → **`/verify-spike`**; a bounded "which option" trade-off → **`/decision-gate`**.
+4. **Branch — is this a multi-session build?**
+   - **Yes** → **`/to-prd`** (turn the thread into a PRD) → **`/to-issues`** (split into independently-grabbable issues / a wave anchor). Clear context between issues: fresh session per issue, kick off **`/implement`** with the PRD + the single issue.
+   - **No** → **`/implement`** right here, same context window.
+
+   Either way, **`/implement`** builds each issue by driving **`/tdd`** internally — one red-green slice at a time — then closes out with **`/code-review`** (the two-axis Standards×Spec review; project layer at `docs/agents/code-review.md`, seeded by `/setup-workflow`) before committing. Reach for **`/tdd`** on its own to build a concrete behaviour test-first without a full spec, and **`/code-review`** on its own to review any branch/PR against a fixed point.
+5. **Land** → **`/wrapup`** (see Land). **Learn** → **`/retro`** (see Learn).
+
+### Context hygiene
+
+Keep steps 1–4 in **one unbroken context window** — don't compact or clear until after `/to-issues` — so grilling, PRD, and issues build on the same thinking. Each `/implement` then starts fresh from the issue. If a session gets large before `/to-issues`, don't push on degraded — `/handoff` and continue fresh.
+
+## Depth Ladder
+
+Prefer the smallest depth that produces a clear next action.
+
+- **Program:** the size is genuinely unclear — a new app, a big cross-cutting
+  undertaking, several independently-shippable stages. Run `/scale-check`
+  first (it owns the altitude criteria catalog — this router only names it);
+  two or more criteria tripped routes to a program grill → `/to-prd` →
+  `/to-waves`.
+- **Deep:** `/grill-with-docs` followed by `/to-prd` and `/to-issues` when
+  terminology, contracts, rollout order, or ownership are still uncertain.
+- **Medium:** `/to-issues` for a ready artefact that needs slicing.
+- **Light:** direct `/tdd` for a small, well-understood change.
+- **Gate:** insert `/verify-spike` or `/decision-gate` before any depth level
+  when a slice hinges on an unresolved fact or trade-off.
+
+## Gate-before-build
+
+When `/to-issues` cuts a slice that hinges on an unknown, it tags the slice instead of guessing. The gate is its own slice, sequenced *before* the build slice it blocks.
+
+- **`/verify-spike`** — a single yes/no fact against the real lib/runtime/DB/platform, answered by a throwaway read-only harness with output-proof.
+- **`/decision-gate`** — a bounded trade-off ("which option") or a targeted research gap: options × criteria table + reasoned pick, sunk to an ADR/issue.
+<!-- mirror-xform:start codex-escalation -->
+- **`/grill-with-docs-codex` / `/grill-me-codex`** — for genuinely hard-to-reverse calls, escalate to a cross-model grill (see Cross-model review).
+<!-- mirror-xform:end -->
+
+## On-ramps
+
+A starting situation that generates work, then merges onto the main flow.
+
+- **Bugs and requests piling up** → **`/triage`**. Moves issues through triage and produces agent-ready issues that `/implement` later picks up. Only for issues **you didn't create** — `/to-issues` output is already agent-ready, don't triage it.
+- **Something's broken** → **`/diagnose`**. For the hard ones: the bug that resists a first glance, the intermittent flake, the regression between two known-good states. Refuses to theorise until it has a **tight feedback loop** — one command that already goes red on *this* bug — then fixes with a regression test. Its post-mortem hands off to **`/improve-codebase-architecture`** when the finding is that there's no good seam.
+- **A huge, foggy effort too big for one agent session** — a greenfield build or a sprawling feature where the way from here to the destination isn't yet visible, and it's still **pre-spec** (before any grill or PRD) → **`/wayfinder`** (user-invoked). It charts a **shared map** of investigation slices on the tracker and resolves them one at a time — producing **decisions, not deliverables** — until the fog lifts and the route is clear, then merges onto the main flow at **`/to-prd`** (or, if the effort turned out small enough, straight to **`/implement`**). Where `/grill-with-docs` sharpens an idea you can hold in one session, wayfinder is for the one you can't. Once an undertaking has already resolved into several independently-shippable waves, `/scale-check` → `/to-waves` stays the primary route.
+- **A backlog to cluster** → **`/board-to-waves`**. Groups an existing board into themed waves when you need to *find* the next wave rather than start fresh.
+- **A whole wave to LAND** → **`/orchestrate-wave`**. When a wave anchor (file-disjoint slices, specs already locked) is ready to build, verify and land end-to-end — often AFK: it dispatches an implementer per slice in its own worktree, integrates serially, verifies centrally, and lands the wave. The execute-and-land node of the wave ladder (`scale-check` → `to-waves`/`board-to-waves` → `orchestrate-wave`). A single slice just goes to `/tdd`.
+
+## Cross-model review (Codex)
+
+An independent second model catches what one model rationalises. Read-only, bounded.
+
+<!-- mirror-xform:start codex-escalation -->
+- **`/grill-me-codex` / `/grill-with-docs-codex`** — run the grill (Act 1), then a *different* model (Codex) adversarially reviews the locked plan (Act 2) before any code.
+<!-- mirror-xform:end -->
+- **`/codex-review`** (Claude Code only) — standalone: you already have a plan, just want the cross-model stress-test.
+
+## Codebase health
+
+Not feature work — upkeep.
+
+- **`/improve-codebase-architecture`** — run in spare moments to keep the codebase good for agents. Surfaces **deepening opportunities**; picking one _generates an idea_ for the main flow at `/grill-with-docs`.
+- **`/zoom-out`** — step back from the diff to the structure when a change is fighting the codebase; recon that becomes a planned slice or guides a refactor in place.
+- **`/security-audit`** — a whole-app, application-layer security audit run as an independent two-model pass (two models audit the same code separately, then the remediation plan is hardened before any fix). Run before a release or after the attack surface changes (new endpoint, new input source, auth change, dependency bump). Infra hardening (ports/TLS/SSH/backups) is audited separately.
+
+## Vocabulary underneath
+
+Model-invoked references that run *beneath* the other skills — each the single source of truth for its vocabulary. Reach for them when the **words**, not the process, are the problem.
+
+- **`/domain-modeling`** — sharpen the project's *domain* language: challenge a fuzzy term, resolve an overloaded word, record a hard-to-reverse decision as an ADR. The active discipline `/grill-with-docs` drives to keep `CONTEXT.md` a clean glossary. (ADR conventions: `docs/adr/README.md`.)
+- **`/codebase-design`** — the deep-module vocabulary (module, interface, depth, seam, adapter, leverage, locality) for designing a module's *shape*. `/tdd` and `/improve-codebase-architecture` both speak it.
+- **`/write-a-skill`** (Claude Code only) — reference for writing and editing skills well (invocation, information hierarchy, progressive disclosure, leading words, pruning, failure modes). *This router is itself an instance of its "router skill" pattern.*
+
+## Land
+
+- **`/wrapup`** — the land-and-clean closeout: make the branch landable, enforce the PR-body contract, merge, reconcile the board, sweep merged branches, surface what's still open. Does not replace live verification — verify the user outcome first.
+- **`/local-ci`** — the pre-PR gate: run the repo's local CI (fast static guards + the full gate) before opening a PR. When your host can't enforce a required status check at merge (a Free-plan private repo has no branch protection), the gate has to be local — this is it.
+- The **pre-commit / pre-push gate** fires automatically (installed once via `/git-guardrails-claude-code` / `/setup-pre-commit`, both Claude Code only), blocking a broken commit/push.
+
+## Learn
+
+- **`/retro`** — in-session post-mortem that proposes concrete changes to rules, skills, or hooks, each with per-patch approval.
+- **`/audit-skills`** — the anti-drift audit: check the repo's own skills against code/doc reality and fix the rot (dead paths, stale line numbers, broken cross-refs). Run it periodically or when a SessionStart drift-hint flags a skill whose declared source moved.
+- **`/write-a-skill`** (Claude Code only) — turn a move you keep repeating into a reusable skill (see Vocabulary).
+
+## Crossing sessions
+
+- **`/handoff`** — compacts the conversation into a markdown file when a thread is full or you need to branch (e.g. into a `/prototype` session). You don't continue in place — open a new session and reference that file. `/handoff` forks; `/compact` continues.
+- **`/compact`** (built-in) — stay in the same conversation, letting earlier turns be summarized. Use at intentional breaks between phases, not mid-phase.
+
+## Standalone
+
+Off the main flow entirely.
+
+- **`/grill-me`** — the same relentless interview as `/grill-with-docs`, but for when you have **no codebase**. Stateless — saves nothing locally.
+- **`/prototype`** — a small throwaway program that answers one design question (does this state model feel right; what should this UI look like). Keep the answer, delete the code.
+- **`/research`** — delegate reading/docs legwork to a **background agent**: it investigates a question against **primary sources** and leaves a cited Markdown note in the repo. Keep working while it reads. Model-invoked (also triggerable by name); the note it produces is something to carry *into* the main flow at `/grill-with-docs` — research feeds the thinking, it doesn't replace it.
+- **`/resolving-merge-conflicts`** — a disciplined loop for an in-progress merge/rebase conflict: understand each side's intent, preserve both where possible, always resolve (never `--abort`).
+- **`/git-worktree-recover`** — reflog recovery for a branch mix-up: a commit landed on the wrong branch, the branch switched unexpectedly, or work looks lost. Finds the misplaced commit, moves it to the right branch, and sets up a clean worktree.
+- **`/spec-self-critique`** — red-team your own spec before committing to build it.
+
+## Precondition
+
+- **`/setup-workflow`** — run before your first engineering flow to configure the issue tracker, triage labels, board profile, and doc layout the other skills assume.
+
+## Repo-specific skills
+
+This repo also carries **project-private domain/tooling skills** (data layer, migrations, forecast/risk logic, brand, blast-radius census, …) that don't ship in the kit. For those, see the **project-skill table in `CLAUDE.md`** — they're model-invoked and fire on their own triggers.

package/.claude/skills/ask-matt/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,29 @@
+# Third-Party Notices
+
+This skill is adapted from **Matt Pocock's skills**
+(https://github.com/mattpocock/skills), `skills/engineering/ask-matt` @ d574778, Copyright (c) 2026 Matt Pocock,
+used under the MIT License. Locally adapted (fork-and-own); see PROVENANCE.md.
+
+```
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/.claude/skills/audit-skills/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: audit-skills
+disable-model-invocation: true
+description: Audit the project's own skills for drift from code/doc reality and fix it — the anti-drift "learn" step of the plan → execute → land → learn line. Run it at retro, periodically, or when a SessionStart drift-hint warns that a skill's declared source moved since its last touch. Fans out one read-only research subagent per skill over every concrete claim in the SKILL.md, re-verifies each reported drift empirically before editing (the auditor produces false positives), then fixes by content type. Triggers — "audit the skills", "skill drift", "stale skill", "this skill points at a dead path / renamed symbol", "skill-freshness warning". NOT for rewriting a domain skill's content on demand (that is the skill itself) and NOT for auditing application code (that is a code review or a diagnosis).
+---
+
+# audit-skills — Skill freshness audit (anti-drift)
+
+A reusable recipe for checking the project's own skills against code/doc reality
+and keeping them fresh. Skills rot in every repo: a refactor moves a file, a
+symbol is renamed, a line number shifts — and the SKILL.md that named it now
+lies. This is the **learn** step of the plan → execute → land → learn line: the
+skills the other steps rely on drift, and nothing fixes them unless a recipe does.
+
+## When to run
+
+- At `/retro` (a periodic hygiene point).
+- When the SessionStart drift-hint hook (`.claude/hooks/skill-drift-hint.py`)
+  warns that a declared source moved in git since the skill's last touch.
+- Ad-hoc, when a skill you just reached for points at a dead path or a renamed
+  symbol.
+
+Not for: rewriting a domain skill's content on demand (that is the skill itself),
+or auditing application code (a code review or a diagnosis does that).
+
+## Standing guards (run without this audit)
+
+Two automatic nets catch the most common drift classes before an audit — this
+recipe complements them, it does not replace them:
+
+1. **A skill-sync test** — for any un-guessable enumeration a skill documents (a
+   status→bucket map, a design-token list), a test parses the value out of the
+   SKILL.md and asserts equality with the code constant. Drift breaks the build.
+   Your project layer names the concrete tests.
+2. **The drift-hint hook** (`.claude/hooks/skill-drift-hint.py`) + a per-skill
+   `SOURCES.txt`: at SessionStart it flags any skill whose declared source file
+   is newer in git than its SKILL.md.
+
+**Core insight:** test-covered values do NOT drift silently — only un-tested
+prose refs (paths, line numbers, cross-refs, memory keys) rot. So: test-cover the
+high-value un-guessable enumerations (guard 1); audit everything else
+periodically (this recipe).
+
+## The SOURCES.txt convention
+
+Each drift-prone skill declares its code/doc anchors in a co-located
+`SOURCES.txt` next to its `SKILL.md`:
+
+- one repo-relative source path per line;
+- `#` comments and blank lines are ignored;
+- the drift-hint hook compares each source's last-commit time against the
+  SKILL.md's — a source committed *after* the skill means the skill may be stale;
+- committing (touching) the SKILL.md resets the signal — that is how you
+  acknowledge that you re-checked it.
+
+When a confirmed fix introduces a new source file or replaces an old one, update
+that skill's `SOURCES.txt` in the same change — otherwise the hook keeps pointing
+at dead anchors, or misses the new source.
+
+## Recipe
+
+### 1. Enumerate the skills — three audit classes
+
+Do NOT hardcode a skill list (it rots on every new skill; a newly added skill
+stays blind). Derive it from the skill manifest (`.claude/skills/skill-manifest.json`)
+plus the `SOURCES.txt` files. Sort every skill into one of three classes:
+
+1. **Code-drift — subagent-audited, drift-hook-netted.** Every skill with a
+   `SOURCES.txt`. The hook already watches these; run a full step-2 subagent
+   audit over each file/symbol/line claim.
+   ```bash
+   ls .claude/skills/*/SOURCES.txt   # → the drift-netted skills
+   ```
+2. **Project-layer drift — against docs, not code.** Published/genericized skills
+   carry their project crust in a project-layer doc, not in code. Lighter check:
+   do the inline pointers still resolve to existing project-layer files, and do
+   the cited field/status names still match the profile.
+3. **Script-coupled, un-netted — checked by hand every audit.** Skills coupled to
+   scripts or hooks with no `SOURCES.txt` and no hook net. No hook warns, so
+   re-check them manually each audit.
+
+Your project layer assigns each concrete skill to a class — a completeness gate
+catches the next new skill that would otherwise stay invisible.
+
+### 2. Audit in parallel — one subagent per skill
+
+Run **one read-only research subagent per skill** — several in parallel in a
+SINGLE message (they are independent and read-only, so they don't contend for the
+git index). Per subagent prompt:
+
+- name the repo root, insist **read-only**, "propose no fixes";
+- list **each concrete SKILL.md claim** separately: file path, symbol name, line
+  number, code example, cross-ref, memory key;
+- ask for a verdict table back — `TRUE / FALSE / PARTIAL` + the CURRENT real
+  path/symbol/signature — in compact `file:line` form (far fewer tokens than
+  inline reads).
+
+### 3. Re-verify before every edit — mandatory
+
+**The auditor produces false positives.** Treat every reported drift as a
+hypothesis, not a fact: re-verify it at the edit itself (`grep` / read the file)
+before changing anything. Never take the auditor's list blind — and an empty
+`grep` result is not proof either, so anchor the search frame (path from the repo
+root, grep the import line, try a second pattern variant). On low-confidence
+findings, re-audit the whole skill rather than trusting the list. This
+false-positive discipline is the single most important rule of the recipe.
+
+### 4. Fix only what's confirmed — by content type
+
+- **Line number** → reference the symbol (function / constant); keep a line only
+  when unavoidable.
+- **Dead path** → the correct path, OR a pointer to the single source of truth.
+- **Cross-ref** → a stable name (verify the target still exists first).
+- **Stale "must still fix" state-claim** → move it into a "historical" block
+  (keep the lesson, don't present it as current) or delete it.
+- **Real code finding** (the skill is right, the code drifted) → a **separate
+  issue**, NOT fixed inside the docs change.
+- **Test-covered values** → leave untouched (guard 1 already secures them).
+
+### 5. Catch up the SOURCES.txt
+
+If a confirmed fix introduced a new source file or replaced an old one, update
+the affected skill's `SOURCES.txt` in the same change (see the convention above).
+
+### 5b. Sync any second surface
+
+If your skills are published to more than one surface (for example a Codex mirror
+alongside the Claude source), sync the mirror in the **same** change — otherwise
+the second surface rots silently. Mirror the body, but preserve each surface's
+own frontmatter: a mirror's `description` may be deliberately condensed, so never
+blind-copy the whole file over it. A `SOURCES.txt` is a plain anchor list and can
+be mirrored verbatim. Your project layer names the surfaces and the exact
+transform.
+
+## Done
+
+- **Enumeration completeness:** every skill from the manifest is assigned to one
+  of the three §1 classes — this catches the next new skill that would otherwise
+  stay invisible to the audit.
+- Every reported drift is either fixed (with re-verify proof) or dismissed as a
+  false positive (with proof the skill was right).
+- Real code findings filed as their own issues, not folded into the docs change.
+- Any second surface synced (body-parity; each surface's frontmatter preserved).
+- The skill-sync guard and the drift-hint smoke test pass.
+- A pure docs / test / hook change needs no application live-verify.