@opengsd/gsd-path 1.0.0

package/skills/gsd-path/DECIDE.md

@@ -0,0 +1,115 @@
+---
+name: gsd-path-decide
+description: Decide implementation direction from approved intent and complete research evidence, recording settled choices in SYNTHESIS.md. Use only when the user explicitly invokes $gsd-path-decide or an active $gsd-path router explicitly routes to this phase.
+---
+
+# GSD Path Decide Phase
+
+Dispatch one reasoning-intensive decider and validate its decision artifact.
+
+Routing instructions below are caller handoffs under the AGENTS.md handoff
+rule; never invoke an explicit-only sibling skill yourself.
+
+Before dispatch and again before completion, apply the AGENTS.md
+pending-answer rule with the bundled `scripts/discussion_records.py`; a
+follow-up owned by decide is resolved in SYNTHESIS.md, or the phase blocks.
+
+## Preconditions
+
+Require `pipeline_state.py validate --repo <absolute root> [--project-dir
+.project/next]` to pass; otherwise return to `$gsd-path` for ownership
+checking. Legal entry is `research/done` or `decide/active|blocked`. On
+`research/done`, enter with `pipeline_state.py transition`, expected
+phase/status `research/done`, exact branch and archive values, event `decision
+synthesis started`, and set phase/status `decide/active` (plus the same
+lookahead project dir); never edit STATE directly. `decide/done` or any later phase blocks rather
+than replacing decisions beneath an existing plan. When an active router
+supplies the lookahead track root `.project/next/`, evaluate these
+preconditions against the track instead; see Lookahead mode. Require
+`.project/intent/INTENT.md`, `.project/research/RESEARCH.md`, and every
+`evidence-*.md` file named as `dispatched` there. In program flow (CHARTER.md
+exists, no milestone INTENT yet) require `.project/CHARTER.md` in INTENT.md's
+place. A standard file may be absent
+only when the handoff manifest records that dimension as skipped; a missing or
+invalid manifest or dispatched file routes to `$gsd-path-research`. Include
+every additional `evidence-*.md` file present only when the manifest names it.
+
+Output path: when `.project/CHARTER.md` exists and `.project/ROADMAP.md` does
+not, this is program scope — the required output is `.project/SYNTHESIS.md`
+at the `.project/` top level; it persists across milestones and never
+archives. Otherwise the required output is `.project/research/SYNTHESIS.md`,
+which archives with its milestone.
+
+## Lookahead mode
+
+Entered only when an active router supplies the lookahead track root
+`.project/next/` while the active STATE.md is `build/active` in program
+flow. Evaluate every state and artifact precondition against the track:
+`.project/next/STATE.md` is the state file, and INTENT.md, RESEARCH.md, and
+the evidence files are read from `.project/next/`. The output is always
+milestone scope: `.project/next/research/SYNTHESIS.md` — the program
+SYNTHESIS.md already exists at the active `.project/` top level and is
+never rewritten here, so the program-scope output-path rule above does not
+apply. Run the research hand-off validator with `--project-dir
+.project/next`. Dispatch, gates, `NEEDS-USER` handling, and completion
+rules are unchanged; never write an active-path artifact.
+
+## Process
+
+1. Read the local [synthesis template](templates/synthesis.md),
+   `.project/research/RESEARCH.md`, and the bundled `scripts/check_handoffs.py`;
+   resolve each to an absolute path. Run the research hand-off validator before
+   dispatch so decide receives a complete, intentional evidence set.
+2. Read the local [decider role](references/decider.md), then follow
+   the local [runtime dispatch contract](references/dispatch.md) with
+   deterministic logical task name `decide`. Give it absolute paths to the role,
+   `AGENTS.md`, `WORKFLOW.md`, INTENT.md (or CHARTER.md in program flow),
+   RESEARCH.md, every evidence file, the
+   template, and the required output path from the Preconditions.
+3. Validate SYNTHESIS.md with `python3 <absolute check_handoffs.py> decide
+   --repo <absolute root> [--project-dir .project/next]`. Require one decision block for every genuinely open
+   choice in INTENT.md and the evidence, including stack and architecture
+   shape plus build-vs-buy when open. A choice already settled by an intent
+   constraint or the existing codebase belongs under `## Settled` as one line
+   citing the settling source — never a full block with an invented
+   runner-up. Require Decision, Runner-up, Evidence, and
+   Confidence in every decision block. Require `## For the planner` with wave-1
+   blockers, walking skeleton, and pitfall-to-task guidance.
+4. If structural validation fails, redispatch one complete corrected brief
+   under logical task name `decide`, following the runtime dispatch
+   contract, and validate again. If it still fails, use
+   `pipeline_state.py transition` with expected `decide/active`, exact branch
+   and archive values, `--set-status blocked`, and an event naming the failed
+   synthesis gate, and
+   present **Outcome** with the failed gate, **Review** linking SYNTHESIS.md or
+   STATE.md when it is missing, and **Next** naming the one correction or user
+   decision required; then stop.
+5. Present the decision-list outcome and a Markdown link to the resolved
+   absolute SYNTHESIS.md output path before every `NEEDS-USER`
+   item. Use an interactive user-input tool when available; otherwise ask in
+   chat and wait. Present
+   each item's options with the evidence-preferred option first, marked
+   `(recommended)` and justified in one line; a pure values call with no
+   evidence either way carries no recommendation, stated as such. For each
+   answer, append the ruling under `## User rulings`, revise every affected
+   decision so it reflects the ruling, and only then remove its tag.
+6. Re-run the structural gate. When it passes with no unresolved user items,
+   use `pipeline_state.py transition` with expected `decide/active`, exact
+   branch and archive values, `--set-phase decide --set-status done`, and an
+   event naming the validated synthesis path. Include `--project-dir
+   .project/next` in lookahead and require returned `decide/done`. Confirm the
+   settled outcome, link SYNTHESIS.md again, and name
+   the next phase: the roadmap phase in program scope, planning otherwise.
+   When routed by an active `$gsd-path`, return control to
+   that router. When invoked directly, stop and tell the user to explicitly
+   invoke `$gsd-path`, which routes to that next phase; do not invoke an
+   explicit-only sibling skill yourself.
+
+## Rules
+
+- Make commitments, not option lists. Name the runner-up and why it lost
+  when a real alternative was weighed; never invent one.
+- Cite evidence by file and finding heading for every decision.
+- Route low-confidence decisions to wave 1 for verification. Reject uncited
+  decisions.
+- Resolve evidence conflicts or escalate a true values decision; never average.

package/skills/gsd-path/DEFINE.md

@@ -0,0 +1,297 @@
+---
+name: gsd-path-define
+description: Define and approve project or milestone intent through an interview or milestone confirmation, writing .project/CHARTER.md or .project/intent/INTENT.md. Use only when the user explicitly invokes $gsd-path-define or an active $gsd-path router explicitly routes to this phase.
+---
+
+# GSD Path Define Phase
+
+Turn a project idea or approved roadmap entry into an approved intent artifact.
+Run this phase in the main conversation; never delegate its interview or
+confirmation.
+
+Primary modes: **standard** (single milestone, below), **program** (a
+multi-milestone program — interview into `.project/CHARTER.md`), and
+**milestone** (derive one milestone's INTENT.md from the approved roadmap; no
+re-interview). Modifiers: **brownfield** when the track's
+`research/evidence-codebase.md` exists, and **supplied-spec** when the user
+hands in a PRD, issue, or design doc. Apply every matching modifier on top of
+the primary mode.
+
+Routing instructions below are caller handoffs under the AGENTS.md handoff
+rule; never invoke an explicit-only sibling skill yourself.
+
+Before interview work and again before approval, apply the AGENTS.md
+pending-answer rule with the bundled `scripts/discussion_records.py`; a
+follow-up owned by define is resolved in INTENT.md, or the phase blocks.
+
+## State ownership
+
+If STATE.md exists, require `pipeline_state.py validate --repo <absolute root>
+[--project-dir .project/next]` to pass; otherwise return to `$gsd-path` for
+ownership checking. Legal existing-state
+entry is `inspect/done` (transition to `define/active`; milestone mode when
+ROADMAP.md exists), `roadmap/done`
+(transition to `define/active`, milestone mode), or
+`define/active|blocked`. When ROADMAP.md exists, a later milestone or
+lookahead track at `define/active|blocked` also requires both current-track
+inspection artifacts and a Log entry proving `inspect/done` for the same
+milestone after its latest activation; otherwise route to inspect.
+`define/done` or any later phase blocks rather than overwriting approved
+intent and leaving downstream artifacts stale. When an active router supplies
+the lookahead track root `.project/next/`, require its STATE.md to be a regular
+non-symlink file and evaluate this section against that track's state and
+paths; see Lookahead mode. If STATE.md is missing, run the bundled
+`python3 <absolute-bundled-script> initialize --repo <absolute-root>
+--template <absolute-state-template>` helper (`scripts/detect_project.py`) and
+follow its returned JSON `verdict` / `route`. This is the only no-state
+boundary; do not run `classify` first or classify from a directory listing or
+conversation. If the command exits nonzero, returns `error`, or returns
+`wrote_state: false`, report the error and block without routing or claiming
+STATE.md was written.
+- `owned` — continue under the existing-state rules above.
+- `orphan` — return to `$gsd-path` for orphaned-state recovery; existing
+  evidence does not prove its pipeline version or phase and must not be reused
+  or overwritten by inference.
+- `brownfield` — the helper writes STATE.md at `inspect/active`; route to
+  `$gsd-path-inspect` from this returned verdict.
+- `greenfield` — require `wrote_state: true`, then continue with the helper's
+  STATE.md at `define/active`. Do not create STATE.md yourself.
+
+Enter from `inspect/done` or `roadmap/done` only with `pipeline_state.py
+transition`: pass the exact expected phase/status/branch/archive values, event
+`definition started`, and `--set-phase define --set-status active` (plus
+`--project-dir .project/next` for lookahead). This helper is the only ordinary
+STATE mutation; direct template writing is limited to the missing-state
+greenfield initialization above.
+
+The router's verified new-GitHub-repository transaction is the sole greenfield
+exception: STATE.md already exists at `define/active`, `branch` is the approved
+`gsd-path/M001` branch, and `.project/REPOSITORY.md` contains the
+fixed-format remote, remote-default SHA, clean default checkout, branch, and
+primary worktree. Verify that artifact and the current branch/worktree before
+interviewing. The required classifier returns `owned` before signal scanning,
+so the bootstrap README is not a brownfield signal. A missing or mismatched binding
+returns to `$gsd-path`; never infer it from STATE log prose or repair it
+inside define.
+
+## Coverage checklist
+
+Obtain a confident answer in every area before finishing:
+
+1. **Problem** — what hurts, for whom, and how badly.
+2. **Users** — who uses this, how many, how technical, and what they use now.
+3. **Success** — what observable result makes the first release complete.
+4. **Scope in** — the smallest version that achieves that result.
+5. **Scope out** — explicit vetoes that downstream phases must not include.
+6. **Constraints** — stack, deadline, budget, code, integrations, compliance.
+7. **Risks** — the assumptions and unknowns research must investigate.
+8. **Surfaces** — what a person opens, sees, or types into to get the
+   result: screens, commands, endpoints. Record them on INTENT.md
+   `Surfaces:` (`none` only when nobody touches this work directly), and
+   give every named surface at least one success criterion observable
+   there. A criterion satisfied by a passing test alone does not cover a
+   surface.
+
+## Program mode
+
+When the user frames the work as a large multi-milestone program — or the
+interview reveals scope that cannot ship as one milestone — interview against
+the charter instead of the single-milestone checklist:
+
+1. **Vision** — the program's end state and why it matters.
+2. **Full scope in** — every capability area the program will deliver.
+3. **Vetoes** — what no milestone may include.
+4. **Constraints** — program-level stack, budget, deadline, integrations.
+5. **Program success criteria** — observable when the last milestone ships.
+6. **Review panel** — optional durable default (`off` | `detected` | named
+   families). Default `off`. This value persists on CHARTER.md; later
+   milestone INTENT files copy it and may override.
+
+Read the local [charter template](templates/charter.md), write the approval
+draft to `.project/CHARTER.md` including `Review panel:` (default `off`;
+never invent `detected` or a named list), and run the same playback-approval
+loop as the standard Process. On approval, retain the reviewed
+`Review panel:` value on CHARTER.md, run `pipeline_state.py transition` with
+expected `define/active`, milestone/branch/archive all at their exact current
+values, event `program charter approved`, and `--set-phase define --set-status
+done`; require milestone to remain null. Report that research (program
+scope) is next. Research, decide, and the roadmap phase slice the program;
+per-milestone INTENT.md files come later, in milestone mode. Do not write
+INTENT.md in program mode.
+
+## Milestone mode
+
+Legal entry: `roadmap/done` only for the first milestone after initial roadmap
+approval, or `inspect/done` when `.project/ROADMAP.md` exists. Recovery from
+`define/active|blocked` follows the current inspection-evidence requirement in
+State ownership. There is no re-interview of charter or roadmap scope:
+1. Read the applicable track STATE.md, `.project/CHARTER.md`, and
+   `.project/ROADMAP.md`. Select the entry whose slug matches `STATE.milestone`.
+   Require exactly one match. In ordinary milestone mode,
+   require that entry to be `active`; in lookahead mode, require it to be
+   `pending`. A missing, duplicate, or wrong-status match blocks: record the
+   failure in the applicable STATE.md and return to the router. When
+   brownfield, also read the track's
+   `research/evidence-codebase.md` and `research/DOCS-AUDIT.md` first.
+2. Draft INTENT.md from the resolved entry: Summary from its Goal, Scope
+   in/out and Success criteria from the entry, Constraints inherited from the charter,
+   Risks and Open questions from the entry (tagged `RESEARCH`/`NEEDS-USER`),
+   `Lane: milestone`, `Surfaces:` copied verbatim from the entry, and
+   `Review panel:` copied from CHARTER.md (default
+   `off` when CHARTER omits it). The confirmation may override the copied
+   panel value; do not invent `detected` or a named list. When brownfield,
+   fill `## Current state` from the map, record doc-vs-code rulings as in
+   Brownfield mode, and add protected existing behavior under Scope out.
+   Write Ground truth paths from the track root: `.project` normally, or
+   `.project/next` in Lookahead mode — never the building milestone's
+   active `research/` paths.
+3. Present one confirmation, not an interview: playback the derivation (and
+   brownfield ground truth when present), link the resolved absolute INTENT.md
+   path, and ask approve or adjust. A requested change that contradicts the
+   charter or the resolved roadmap entry is a scope change — this phase never
+   edits the roadmap; surface it to the user for a `$gsd-path-roadmap` re-slice
+   at the next milestone boundary.
+4. On approval, finalize per the Output contract, setting `milestone` to the
+   resolved entry's slug. The router continues with milestone-scoped research
+   when the entry lists open questions, otherwise planning.
+
+## Lookahead mode
+
+Entered only when an active router supplies the lookahead track root
+`.project/next/` while the active STATE.md is `build/active` in program
+flow. Evaluate every state and artifact precondition in this contract
+against the track — `.project/next/STATE.md` is the state file and
+INTENT.md is `.project/next/intent/INTENT.md` — never against active-path
+artifacts. This is milestone mode run against the track, with two
+differences:
+
+- Read CHARTER.md and ROADMAP.md from their active `.project/` paths, but
+  resolve the milestone only from `.project/next/STATE.md` as described above;
+  never use the building milestone's `active` entry and never create or modify
+  any active-path artifact.
+- Never mark the lookahead milestone's roadmap entry `active`; the router
+  does that at promotion.
+
+All other milestone-mode rules apply unchanged. Brownfield evidence for
+this track is `.project/next/research/evidence-codebase.md`.
+
+## Supplied-spec mode
+
+When the user supplies a document at entry — a PRD, issue, or design doc —
+read it fully before the first question and map it against the coverage
+checklist. Present what the document settles per checklist area for
+correction — stated, not asked, exactly like brownfield ground truth — then
+interview only the gaps and contradictions. Note the source document path in
+INTENT.md's Summary. A supplied spec composes with brownfield mode: ground
+truth first, then the spec, then delta questions only.
+
+## Brownfield mode
+
+When the track's `research/evidence-codebase.md` exists (inspect already
+ran), read it and the matching `research/DOCS-AUDIT.md` before the first
+question. The rules change for every primary mode:
+
+- Established facts are not questions. Never ask what the stack is or what
+  the code does — the map answers that. State it and let the user correct.
+- Standard and program interviews cover only deltas: what should change, what
+  must not break, and — standard — the goal of THIS milestone against the
+  code that already exists. Program interviews still use the charter
+  checklist, but skip any area the map already settled.
+- Milestone mode still does not re-interview; it still collects the rulings
+  below before confirmation.
+- Work through the mapper's `## Open questions for define` and the
+  audit's `NEEDS-USER` remediation rows — each doc-vs-code conflict gets a
+  ruling (`fix-doc`, `fix-code`, or `accept-drift`) recorded verbatim in
+  INTENT.md and appended to DOCS-AUDIT.md's `## User rulings` table.
+  `fix-doc` and `fix-code` rows receive `planned: no`; `accept-drift` receives
+  `planned: n/a (accept-drift)`. Never leave the durable alignment queue only
+  in INTENT.md. Program mode records those rulings on CHARTER.md Constraints
+  or Corrections and still writes the DOCS-AUDIT.md table.
+- Existing behavior the user wants preserved is recorded under Scope out as
+  a veto ("do not break X"); accepted `fix-code` items become scope.
+- Fill INTENT.md's `## Current state` from the codebase map so downstream
+  phases inherit ground truth without re-scanning. Set Ground truth to the
+  track's `research/evidence-codebase.md` and `research/DOCS-AUDIT.md`
+  (`.project/next/research/` in Lookahead mode). Omit that section for
+  greenfield. Do not add it to CHARTER.md.
+
+## Process
+
+1. Open in this order, then stop for the reply:
+   - **Brownfield (any primary):** present the one-screen ground truth from
+     inspect before any question.
+   - **Standard, no brownfield:** ask for a one-paragraph idea if missing.
+   - **Program, no brownfield:** ask for the program vision if missing.
+   - **Milestone:** do not ask for an idea; continue at Milestone mode
+     (ground truth already presented when brownfield).
+   - **Supplied spec:** after the opening above, present settled coverage
+     for correction, then interview only its gaps.
+   - **Standard + brownfield:** after ground truth, ask what this milestone
+     should achieve against the code that exists.
+2. For standard and program modes, ask small rounds of questions aimed at the
+   weakest checklist areas that the opening did not already settle. Never ask
+   a fact the map, audit, or supplied spec already answered. Use an
+   interactive user-input tool when available. Otherwise ask concise numbered
+   questions in chat and stop for the reply. Keep each round small enough to
+   answer in one reply. When a question offers options, list the recommended
+   one first marked `(recommended)` with a one-line reason; leave open
+   questions open. Milestone mode skips this step; collect brownfield rulings
+   if brownfield, then use the Milestone mode confirmation.
+3. Surface contradictions immediately and ask the user to choose. Never
+   average incompatible answers.
+4. In standard and program modes, challenge the largest remaining assumption
+   at least once: ask what happens if it is false. Do not challenge a fact
+   the brownfield map already established. Milestone mode skips this step.
+5. Stop when coverage is complete or the user says `enough`. Record remaining
+   uncertainty under `## Open questions` with `RESEARCH` or `NEEDS-USER`.
+6. Classify the proposed milestone lane before writing the approval draft.
+   Milestone mode keeps `Lane: milestone` and skips this classification.
+   Program mode writes CHARTER.md instead of INTENT.md. Otherwise choose
+   `quick` when scope fits at most two deliverable-sized tasks (project
+   policy) in one wave with
+   no `RESEARCH` or `NEEDS-USER` items and no cross-wave integration risk;
+   otherwise `standard`. Read the local [intent template](templates/intent.md),
+   write that proposed lane and the complete draft to
+   `.project/intent/INTENT.md`, then ask for approval. Present an
+   **Outcome** playback of the Summary and proposed lane, a **Review** Markdown
+   link to the resolved absolute INTENT.md path, and one **Next** approval
+   question with approve first as `(recommended)` only when the evidence
+   supports it. Record corrections verbatim under `## Corrections`, update the
+   file, and present the new link before asking again. When STATE records a new
+   new-GitHub REPOSITORY.md binding, include its remote, default checkout, GSD
+   Path branch, and primary worktree under `## Constraints`. Recompute and write
+   the lane after every correction before relinking the file.
+
+## Output contract
+
+At approval, retain the already reviewed `Lane:` value and its one-line reason.
+Retain `Review panel:` as reviewed: the CHARTER copy or the user's override
+in milestone/lookahead mode, the CHARTER value in program mode, or `off`
+when the user did not choose a panel and no CHARTER default exists.
+
+After approval, finalize `.project/intent/INTENT.md` and run
+`pipeline_state.py transition` with expected `define/active`, the exact
+current milestone/branch/archive values, event `milestone intent approved`,
+`--set-phase define --set-status done --set-milestone <milestone slug>`, and
+`--project-dir .project/next` in lookahead. Require returned `define/done` and
+the exact milestone. Report the next phase
+from the approved lane. For `Lane: standard`, research is next. For
+`Lane: quick`, planning is next and research and decide are skipped. For
+`Lane: milestone`, use the resolved roadmap entry matching the track STATE's
+`milestone`: milestone-scoped research is next when that entry lists open
+questions; otherwise planning is next and research and decide are skipped.
+Confirm the approved outcome, link the final INTENT.md again, and name that
+next phase before routing. When routed by an active `$gsd-path`, return control
+to that router so its bundled next contract can auto-advance to the named
+phase. When invoked directly, stop and tell the user to explicitly invoke
+`$gsd-path`, which selects that next phase; do not invoke an explicit-only
+sibling skill yourself.
+
+## Rules
+
+- Trace every question to a checklist gap; omit curiosity questions.
+- In brownfield mode, state mapped facts for correction; never re-ask them.
+- Treat solution-shaped problems as hypotheses and uncover the underlying pain.
+- Preserve vetoes and corrections verbatim.
+- Wrap up when every coverage-checklist area is answered or the user signals
+  done, and tag remaining gaps.

package/skills/gsd-path/DOCS-AUDIT.md

@@ -0,0 +1,190 @@
+---
+name: gsd-path-docs-audit
+description: Verify Markdown claims against the actual code, commands, and GSD Path artifacts. Use only when the user explicitly invokes $gsd-path-docs-audit or an active $gsd-path router explicitly routes to this phase.
+---
+
+# GSD Path Docs Audit
+
+Answer one question with evidence: **does the project do what its documents
+say it does?** Runs standalone at the safe checkpoints below, and as half of
+`$gsd-path-inspect`. Output: `.project/research/DOCS-AUDIT.md`.
+
+Routing instructions below are caller handoffs under the AGENTS.md handoff
+rule; never invoke an explicit-only sibling skill yourself.
+
+Before audit work and again before completion, apply the AGENTS.md
+pending-answer rule with the bundled `scripts/discussion_records.py`; a
+follow-up owned by docs audit is resolved in DOCS-AUDIT.md, or the phase
+blocks.
+
+Require an existing `.project/STATE.md` that passes `python3 <absolute
+pipeline_state.py> validate --repo <absolute root>`; never
+create pipeline state or write into an unowned `.project/`. A missing state
+stops and offers explicit `$gsd-path` initialization; do not invoke it
+automatically. A different marker blocks and reports ownership without writing.
+Embedded inspect mode is legal only at `inspect/active|blocked`.
+Standalone mode is legal only at a stable pre-build boundary
+`inspect|define|research|decide|roadmap|plan` with `status: done`, or at
+`ship/blocked` with no in-progress task. `build/*`, `ship/active`,
+`shipped/done`, and every other state block: changing the canonical audit there
+would dirty execution, invalidate review, or mutate shipped history.
+
+## Process
+
+1. Before writing the output, freeze the helper's exact stdout from `python3
+   <absolute check_docs_audit.py> --repo <absolute root> --emit-inventory`
+   (add `--alignment` in alignment mode) in a temporary file. Before any
+   rewrite, preserve an existing canonical audit in a separate temporary file
+   and record its SHA-256. When that audit records an `Audited HEAD` that Git
+   resolves as an ancestor of HEAD, also freeze the changed set — `git -c
+   core.quotePath=false diff --name-only --no-renames <prior HEAD>` plus
+   `git -c core.quotePath=false ls-files --others --exclude-standard`, one
+   path per line — in a temporary file; otherwise there is no changed set and
+   the auditor re-verifies every claim. The frozen inventory and
+   changed set travel inside the dispatch brief and
+   the gate below; never persist them as `.project/` sidecar files — the
+   audit's own path records are the durable copy. If a previous run left an
+   inventory sidecar under `.project/research/`, the orchestrator deletes it
+   when transferring the new audit — a leftover sidecar blocks the archive
+   transaction. Dispatch one docs auditor with deterministic logical task
+   name `docs_audit`, following the local
+   [runtime dispatch contract](references/dispatch.md): local role
+   [docs-auditor](references/docs-auditor.md), template
+   [docs-audit](templates/docs-audit.md), absolute repo root, exact frozen
+   inventory, the changed set when one exists, alignment flag, prior audit as
+   carry-forward input, and output
+   `.project/research/DOCS-AUDIT.md`. When Git has a resolvable HEAD and no
+   non-`.project` worktree changes, the orchestrator creates a verify sidecar
+   with `python3 <absolute isolation.py> isolate-verify --repo <absolute
+   primary> --base <HEAD> --name docs-audit` for project commands. The auditor
+   writes only its assigned output under that sidecar. Gate it there before
+   collection. Then run `python3 <absolute isolation.py> collect-artifact
+   --repo <absolute primary> --source <returned worktree> --base <recorded
+   HEAD> --branch <returned branch> --source-path
+   .project/research/DOCS-AUDIT.md --destination-path
+   .project/research/DOCS-AUDIT.md`, adding `--expected-destination <recorded
+   prior SHA-256>` when a prior audit existed. Require the returned base,
+   branch, source, and destination to match; then non-force retire that exact
+   worktree and branch with `isolation.py retire`. A corrected redispatch is
+   gated before collection and uses the same expected prior hash. Otherwise no
+   project command may run. The dispatch brief carries current HEAD as the
+   audit baseline only when that verify sidecar was created at HEAD; otherwise
+   it carries `none`. The auditor writes that baseline as `Audited HEAD`.
+2. Gate the artifact with the bundled helper: write the frozen inventory to
+   a temporary file (one path per line) and run
+   `python3 <absolute check_docs_audit.py> --repo <docs sidecar> --inventory
+   <file> [--prior-audit <temporary prior-audit file>] [--changed <temporary
+   changed-set file>]`.
+   It enforces the contract — every doc with at least one testable claim has
+   a claims table, every claim a valid type and verdict with evidence, every
+   claimless doc appears once in the `## Descriptive docs` list, the section
+   paths and that list are disjoint and together equal the frozen inventory
+   exactly, the Summary counts match the rows, the remediation queue
+   classifies every non-verified claim, every prior User-ruling row and
+   Planned value survives in order, and every `unchanged:` row satisfies
+   the Delta rule below. A non-zero exit names the failed
+   rule. Redispatch one complete corrected brief under logical task name
+   `docs_audit`, following the runtime dispatch contract. If it still fails,
+   present **Outcome** with the failed gate, **Review** linking DOCS-AUDIT.md or
+   STATE.md when it is missing, and **Next** naming the required correction.
+3. Report to the user: verdict counts, the drift list (stale + aspirational
+   claims), and the remediation queue. Link the resolved absolute
+   `.project/research/DOCS-AUDIT.md` path before asking for any ruling. Do not
+   fix anything in this skill.
+4. **Collect rulings** (standalone runs; during `$gsd-path-inspect` define
+   owns this). Walk the remediation queue with the user — batches of three,
+   an interactive input tool when available. Present the auditor's
+   classification as the first option marked `(recommended)` with its
+   recorded evidence as the one-line reason; a `NEEDS-USER` item where the
+   auditor cannot tell which side is wrong carries no recommendation, stated
+   as such. Each item gets one ruling:
+   - `fix-code` — the doc is the contract; the code must catch up
+   - `fix-doc` — reality is right; the doc must be corrected
+   - `accept-drift` — known and tolerated; recorded so the next audit
+     doesn't resurface it
+   Append every ruling to DOCS-AUDIT.md under `## User rulings`, verbatim.
+   A ruling that contradicts an INTENT.md veto stops the walk — the veto
+   wins until the user amends INTENT.md itself.
+5. **Queue, don't execute.** Every `fix-code` and `fix-doc` ruling enters
+   the alignment queue: its `## User rulings` row is marked
+   `planned: no`. Ruling and executing are separate decisions — the user
+   may not be ready to work the backlog. Close by offering once: plan the
+   patch wave now, or hold. If an active `$gsd-path` routed this audit and the
+   user chooses now, return control with DOCS-AUDIT.md as the patch findings
+   source. When invoked directly, do not invoke an explicit-only sibling;
+   tell a user who chooses now to explicitly invoke `$gsd-path`, which will
+   offer the queued source to plan. On hold — the default — report the queue
+   size and that `$gsd-path` will offer alignment until the
+   queue is drained. Only `accept-drift` rulings → nothing queued, done.
+   After the choice, link the updated DOCS-AUDIT.md and state whether planning
+   starts now or the queue remains for a later router pass.
+
+## The verification methodology
+
+The auditor follows this checklist for every doc; the audit file is the
+filled-in checklist, so the method and the artifact stay one thing.
+
+**Inventory.** Every `.md` in the repo (root, `docs/`, nested), plus
+`.project/` artifacts when present. Excluded: `node_modules`, build output,
+vendored code, `.project/archive/`, and the output audit itself — archives are
+read-only history and are never audited. The orchestrator freezes this list
+before dispatch; the auditor uses it verbatim. Every file is accounted for —
+a doc with no testable claims gets one line in `## Descriptive docs`, not its
+own section and not skipped. Rewriting DOCS-AUDIT.md preserves any
+existing `## User rulings` rows: rulings and `planned` markers carry forward
+verbatim, so a re-audit never wipes the alignment queue.
+
+**Delta.** A re-audit re-verifies only what could have moved: every doc in
+the changed set, every claim whose evidence names a changed path, every
+command claim, and every prior non-verified claim. Any other prior
+`verified` row is carried with exactly one `unchanged: ` prefix on its
+Evidence. An already-carried row is copied verbatim without adding another
+prefix. The gate rejects a carried row that fails any of those conditions.
+No recorded `Audited HEAD`, or one that is not an ancestor of HEAD, means no
+changed set and a full re-audit.
+
+**Extract claims.** A claim is any statement reality can contradict:
+
+| Claim type | Example | Check |
+|------------|---------|-------|
+| command | "run `npm test`" | run it; record exit code |
+| feature | "supports OAuth login" | find the implementing code path |
+| structure | "parsers live in `src/parse/`" | path exists and matches |
+| status | "phase 2 complete", checked box | artifact/commit/code exists |
+| config | "set `API_URL` in `.env`" | variable is actually read |
+| integration | "syncs to Linear" | client code + config present |
+
+**Verify.** Each claim gets checked by the cheapest sufficient method, in
+order: run the command; read the named code; run the relevant test; check
+git history. Verdicts:
+
+- `verified` — checked and true, evidence recorded (file:line or command + output)
+- `stale` — was plausibly true once; code has moved on
+- `aspirational` — describes something never built
+- `unverifiable` — cannot be checked from the repo (external service, credentials)
+
+**Alignment mode** (when `.project/` exists) — the pipeline audits itself:
+
+- every INTENT.md success criterion → `met` so far / `not yet` / `contradicted`
+- every task with `status: done` → `isolation.py recover` proves its landing
+  commit and its Verify command still passes
+- SYNTHESIS.md decisions → the code actually uses the decided stack/shape
+- STATE.md → agrees with task frontmatter and review files
+
+**Remediate.** Every non-`verified` claim lands in the remediation queue,
+classified `fix-doc` (reality is right, doc lies) or `fix-code`
+(doc is the contract, code fell short) or `NEEDS-USER` when the auditor
+cannot tell which side is wrong. The queue is input for the user's ruling —
+during inspection it feeds define; mid-project, accepted `fix-code`
+items become a patch wave through `$gsd-path-plan`.
+
+## Rules
+
+- Audit is read-only; the auditor never edits docs or code.
+- Build, test, lint, and help commands run only in an agent-specific verify
+  sidecar at a recorded clean revision. If that cannot faithfully
+  represent the claim, use static evidence or mark it `unverifiable`; never run
+  project commands in the source worktree.
+- A verdict without recorded evidence is itself a defect — the audit must
+  meet the same evidence standard it enforces.
+- Never let the auditor decide doc-vs-code conflicts; that is a user ruling.