/drain — on-demand gate drain pass

/drain is the on-demand entry point to the shared gate evaluator (REQ-H1.4, D-17, D-31). It sweeps every spec bundle's tasks.md for **Gate:** deferral entries, evaluates the structured GATE(when: …) ones against the closed grammar (free-text gates surface unevaluated), and presents the drain report. The scheduled entry point to the same evaluator is /orchestrate --bookkeeping; neither may parse gates on its own. Normative semantics (accumulator classes, grammar productions, lanes, data-only handling) live in the accumulator-taxonomy doctrine doc — read it via the rule-doc resolution path before interpreting the report.

Doctrine manifest (machine-parseable, per doctrine/instruction-hygiene.md; run-start loads before work begins, point-of-use at the named step):

Doctrine: run-start accumulator-taxonomy Doctrine: point-of-use interaction-style (Steps 3 and 4, the attended turns)

Procedure

1. Resolve the evaluator and the spec root

Resolve the planwright root via the standard chain (PLANWRIGHT_ROOT → CLAUDE_PLUGIN_ROOT → <claude-dir>/planwright); the evaluator is <root>/scripts/drain-gates.sh. The spec root is what scripts/resolve-root.sh spec prints from the current repository, in any posture (docs/spec-location.md); the sweep only reads it. If the root does not resolve or names no directory, report that there is nothing to drain and stop, naming the resolver's refusal when it gave one (this is a read-only authoring-path move: degrade gracefully, REQ-K1.7).

2. Run the evaluator

<planwright-root>/scripts/drain-gates.sh <spec-root>

The evaluator resolves task-completion atoms through the derivation engine (scripts/orchestrate-state.sh), which on a format-version 2 bundle is the only completion source — no ## Completed section exists (invariant-tasks D-8); v1 bundles keep the v1 read. Version keying reads the declared Format-version:; unparseable fails closed, never the v1 arm (D-7). Exit 0 means the sweep completed — malformed gates are report content, not failures. A non-zero exit means the evaluator could not run or could not complete the sweep; surface the error verbatim and stop. A complete report always ends with the == summary == section; treat a report missing it as a failed sweep, not a result.

3. Present the report

The evaluator's report is the record; the turn is its projection (interaction-style, the arbitration). Lead with one count per lane, the actionable lanes (1–4 below) first, then ask which lane to open, or go straight to Step 4 on the first actionable item when only one lane has any. A lane's rows reach the turn when the operator asks for that lane, never by default; re-running the evaluator regenerates the whole report, so nothing withheld is lost. Every lane follows the shape PENDING / DORMANT always had: counts first, detail on request. Mirror each turn into the structured decision/transcript log as one turn record, sanitized like the log's other records (D-19); where the harness provides no such log, say the mirror was skipped, never improvising one into the repository.

The lanes, in the order the counts and any opened detail follow, grouped by what the human should do with each:

1. MALFORMED — drain-report-level errors. For each, show the file:line,

the reason, and the offending gate text, and propose the corrected entry (restate the condition in the closed grammar, or reword it as a free-text gate if it cannot be said in the grammar). A row whose reason is that no atom is in the closed grammar already carries that second remedy as a hint; relay it rather than re-deriving one. Never evaluate or guess around a malformed gate.

1. SATISFIED — condition gates whose atoms all hold: these items have

re-surfaced and are actionable now.

1. SURFACED — date gates whose date has been reached (reminders, not

proof; a human judges whether the world caught up with the date).

1. FREE-TEXT — gates the machine never evaluates; list them so the

human can judge each condition.

1. PENDING / DORMANT — not yet actionable.
2. Manual verification — the == manual verification == section: each

live bundle (Draft, Ready, Active) with its [manual] test-spec entries, [test + manual] included. This is inventory, not state (D-15): nothing records whether an entry was ever exercised, so relay it as a standing reminder of what still needs a human to run it, not as a to-do list the sweep is tracking. Done and terminal bundles are out of scope by design.

1. Observations — the unmined count and oldest-entry age, derived from

the fragment store (entries/) and the frozen legacy file's unconsumed lines and naming both surfaces, plus any stuck consumes (fragments annotated Consumed-by: but not yet moved to archive/) and skipped invalid fragments; the reminder that its canonical reader is /spec-draft (mining happens there, not here). Then the venture drop's entry count from <planwright-root>/scripts/inception-registry.sh drop-read (its entry lines, entry none counting zero; exit 6 named as unavailable), mined in /spec-draft too.

Items within each lane of each spec's section arrive ordered low-confidence first (REQ-H1.5); when merging lanes across specs, re-sort by the [confidence] tag so low still comes first.

4. Disposition (human-reserved)

The sweep never auto-resolves and never auto-drops (REQ-H1.4) — and neither does this skill. For each re-surfaced or malformed item, one item per turn, ask the human what to do (un-defer the work, record the decision, re-gate with a new condition, fix the malformed entry, or leave it), each option stating its action and consequence, and apply only what they choose. Edits to tasks.md follow the normal state-move commit discipline (commit_on_state_move) on v1 bundles; on a format-version 2 bundle the edit is a human-payload write (a Deferred entry or reference bullet — the task block never moves) and commit_on_state_move does not apply (invariant-tasks D-2, D-7). A follow-up the operator names beyond the item at hand is captured per interaction-style's Capture at birth: this skill proposes the tracked form, and writes only what the operator confirms.

Maintenance

After each run, compare these instructions against the doctrine and spec they implement: the accumulator-taxonomy doctrine doc (lanes, grammar, drain-pass contract) and REQ-H1.3/REQ-H1.4/REQ-H1.5. If the evaluator's report format, lanes, or grammar have drifted from what this skill describes, record a one-line drift observation through the shared helper (scripts/obs-record.sh --slug skill-drift --scope <repo> --text 'skill-drift(drain): <what>' — the entry text keeps the skill-drift(...) prefix) and commit the fragment as its own chore commit, per REQ-B3.2 / D-42; surface a non-zero helper exit rather than silently dropping the observation. In repositories without specs/, surface the drift to the user instead of recording it. Do not edit this skill or the doctrine docs to resolve the drift; the accumulator's canonical reader (/spec-draft) owns folding drift into spec amendments.