@warpgogol/forge 5.3.4 → 6.2.0

package/os/spec/spec.module.ts

@@ -6,10 +6,18 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>RFC-0394: initial forgeSpecModule registering spec.validate.</item>
-  <item>RFC-0396: added spec.status and spec.materialize commands.</item>
-  <item>RFC-0711: added spec.live.merge, spec.live.list, spec.live.show, spec.live.validate commands.</item>
+  <item>RFC-1230: added spec.live.rebuild command + --force flag on spec.live.merge (idempotent merge design).</item>
   <item>RFC-1173: declare mutatesState on all kernel commands — collectDeclarationDiagnostics emits error-severity MUTATES-STATE-DECLARED, command.manifest.validate is the blocking consumer in packages.check, sweep declares the flag on every command definition (factories hardcode false for read-only check specs)</item>
+  <item>RFC-1230: review findings — scoped droppedSections to namespaced headings, warn on unreadable spec, fail-fast merge on corrupt frontmatter, CHANGE_SUMMARY dedupe</item>
+  <item>RFC-1231: step 1 — rename supportsAllSites to acceptsAllFlag
+
+Mechanical sweep: the field only ever gated --all argv acceptance; fan-out
+follows the parsed selector. Guard renamed assertAllSitesAllowed ->
+assertAllFlagAccepted, message updated. 417 declaration sites + type
+surfaces (KernelCommandMetadata, ForgeCommandMetadata) in one atomic pass.</item>
+  <item>RFC-1234: spec.live.validate description lists V-LS-09 drift rule.</item>
+  <item>RFC-1240: --consumer flag on spec.validate/spec.status/spec.materialize; SPEC-12/13 rules in spec.validate description.</item>
+  <history>RFC-0394, RFC-0396, RFC-0711</history>
 </CHANGE_SUMMARY>
 */
 
@@ -23,6 +31,7 @@ const { runSpecValidate } = await import("./spec-validate.ts");
     const { runSpecLiveList } = await import("./live-spec-list.ts");
     const { runSpecLiveShow } = await import("./live-spec-show.ts");
     const { runSpecLiveValidate } = await import("./live-spec-validate.ts");
+    const { runSpecLiveRebuild } = await import("./live-spec-rebuild.ts");
   return {
   name: "forge-spec",
   version: "0.2.0",
@@ -33,11 +42,26 @@ const { runSpecValidate } = await import("./spec-validate.ts");
       name: "spec.validate",
       mutatesState: false,
       contract: "spec",
-      rules: [],
+      rules: [
+        "SPEC-01",
+        "SPEC-02",
+        "SPEC-03",
+        "SPEC-04",
+        "SPEC-05",
+        "SPEC-06",
+        "SPEC-07",
+        "SPEC-08",
+        "SPEC-09",
+        "SPEC-10",
+        "SPEC-11",
+        "SPEC-12",
+        "SPEC-13",
+      ],
       description:
         "Validate vendored spec packages under docs/specs/. " +
         "Checks integrity (SHA-256), schema, dependency graph (acyclic), " +
-        "reference resolution, wave coverage, duplicate ids, and materializedAs links. " +
+        "reference resolution, wave coverage, duplicate ids, materializedAs links, " +
+        "and consumer hygiene (SPEC-12 duplicates/empty, SPEC-13 identity warning). " +
         "Use --spec=<id> to validate a single spec.",
       scope: "workspace",
       flags: {
@@ -45,12 +69,17 @@ const { runSpecValidate } = await import("./spec-validate.ts");
           kind: "string",
           description: "Validate only the named spec.",
         },
+        consumer: {
+          kind: "string",
+          description: "Local consumer identity override (default: forge.yaml project.consumer).",
+        },
       },
       reads: ["docs/specs/**/*"],
       execute: runSpecValidate,
     },
     {
       name: "spec.status",
+      coverage: "operator" as const,
       mutatesState: false,
       description:
         "Show roadmap progress for vendored specs. " +
@@ -61,12 +90,17 @@ const { runSpecValidate } = await import("./spec-validate.ts");
           kind: "string",
           description: "Show status for a single spec.",
         },
+        consumer: {
+          kind: "string",
+          description: "Local consumer identity override (default: forge.yaml project.consumer).",
+        },
       },
       reads: ["docs/specs/**/*", "docs/rfcs/**/*.md"],
       execute: runSpecStatus,
     },
     {
       name: "spec.materialize",
+      coverage: "operator" as const,
       description:
         "Scaffold RFC files for the next N front nodes of a spec roadmap. " +
         "Requires --spec=<id>. Optional: --next=<N> (default 8, max 12), --nodes=<id,id> explicit selection.",
@@ -79,6 +113,7 @@ const { runSpecValidate } = await import("./spec-validate.ts");
         spec: { kind: "string", required: true, description: "Spec id to materialize from." },
         next: { kind: "string", description: "Number of front nodes to materialize (default 8, max 12)." },
         nodes: { kind: "string", description: "Comma-separated explicit node ids to materialize." },
+        consumer: { kind: "string", description: "Local consumer identity override (default: forge.yaml project.consumer)." },
       },
       execute: runSpecMaterialize,
     },
@@ -89,7 +124,8 @@ const { runSpecValidate } = await import("./spec-validate.ts");
         "under docs/specs/live/<domain>.md. Requires --id=<RFC-XXXX>. " +
         "Domain is auto-derived from packagesImpacted[0] when liveSpec: true, or uses " +
         "the string value when liveSpec: <domain>. " +
-        "All-or-nothing: aborts on any heading conflict without writing. " +
+        "Idempotent: an RFC already in spec history[] is skipped as already-merged; " +
+        "use --force to re-merge (replaces that RFC's namespaced sections). " +
         "Use --dry-run to preview deltas without writing.",
       scope: "workspace",
       mutatesState: true,
@@ -98,12 +134,14 @@ const { runSpecValidate } = await import("./spec-validate.ts");
       reads: ["docs/rfcs/**/*.md", "docs/specs/live/*.md"],
       flags: {
         id: { kind: "string", required: true, description: "RFC id to merge (e.g. RFC-0711)." },
+        force: { kind: "boolean", description: "Re-merge an already-merged RFC — strips its (RFC-XXXX) sections and old history entries first." },
         "dry-run": { kind: "boolean", description: "Preview deltas without writing files." },
       },
       execute: runSpecLiveMerge,
     },
     {
       name: "spec.live.list",
+      coverage: "operator" as const,
       mutatesState: false,
       description:
         "List all living feature specs in docs/specs/live/. " +
@@ -115,6 +153,7 @@ const { runSpecValidate } = await import("./spec-validate.ts");
     },
     {
       name: "spec.live.show",
+      coverage: "operator" as const,
       mutatesState: false,
       description:
         "Show a single living feature spec by domain. " +
@@ -128,18 +167,56 @@ const { runSpecValidate } = await import("./spec-validate.ts");
     },
     {
       name: "spec.live.validate",
+      coverage: "operator" as const,
+      coverageNote: "spec.live drift audit — current debt repaired via spec.live.rebuild",
       mutatesState: false,
       contract: "spec",
-      rules: [],
+      rules: [
+        "V-LS-01",
+        "V-LS-02",
+        "V-LS-03",
+        "V-LS-04",
+        "V-LS-05",
+        "V-LS-06",
+        "V-LS-07",
+        "V-LS-08",
+        "V-LS-09",
+      ],
       description:
         "Validate all living feature specs in docs/specs/live/. " +
         "Checks V-LS-01 (frontmatter), V-LS-02 (domain/filename match), " +
         "V-LS-03 (lastMergedRfc is archived), V-LS-04 (history entries are archived), " +
-        "V-LS-05 (no duplicate domains).",
+        "V-LS-05 (no duplicate domains), V-LS-06 (no duplicate RFC-namespaced headings), " +
+        "V-LS-07 (no duplicate history RFCs), V-LS-08 (merged-history coverage is complete), " +
+        "V-LS-09 (spec content matches the deterministic replay of its history). " +
+        "Repair path: spec.live.rebuild.",
       scope: "workspace",
       flags: {},
       reads: ["docs/specs/live/*.md", "docs/rfcs/**/*.md"],
       execute: runSpecLiveValidate,
+    },
+    {
+      name: "spec.live.rebuild",
+      coverage: "operator" as const,
+      acceptsAllFlag: true,
+      description:
+        "Rebuild a living feature spec by replaying its deduplicated history[] — " +
+        "the repair path for duplicated (RFC-XXXX) sections and duplicate history entries " +
+        "reported by spec.live.validate (V-LS-06/V-LS-07). " +
+        "Each unique RFC's current ## Design is re-applied in first-occurrence order; " +
+        "unreadable or unimplemented RFCs are skipped with a warning. " +
+        "With no --domain (or --all) every spec is rebuilt. Use --dry-run to preview.",
+      scope: "workspace",
+      mutatesState: true,
+      writes: ["docs/specs/live/*.md"],
+      generates: [],
+      reads: ["docs/specs/live/*.md", "docs/rfcs/**/*.md"],
+      flags: {
+        domain: { kind: "string", description: "Rebuild a single living spec by domain (filename without .md)." },
+        all: { kind: "boolean", description: "Rebuild every living spec in docs/specs/live/ (default when --domain is omitted)." },
+        "dry-run": { kind: "boolean", description: "Preview rebuild without writing files." },
+      },
+      execute: runSpecLiveRebuild,
     }
   ],
   pipelines: [

package/os/werkstatt/handlers/werkstatt-operation-validate.ts

@@ -12,6 +12,7 @@ helper module (RFC-0362 §6).</purpose>
 <CHANGE_SUMMARY>
   <item>RFC-0362: initial operation.validate command handler.</item>
   <item>RFC-0556: moved from @warpgogol/site-kernel-checks to @warpgogol/forge for autonomous mode. Uses node:fs/promises directly instead of context.io.</item>
+  <item>RFC-1248: VITE-CLIENT-DEP-02 lazy-import gate + SCAN-02 validator reads-root existence check (RFC-1248)</item>
 </CHANGE_SUMMARY>
 */
 
@@ -25,8 +26,8 @@ import type {
   ForgeRuntimeContext,
 } from "../../../src/types.ts";
 
-const SCAN_DIR = "packages/os/site-kernel-handoff/src";
-const ALLOWLIST_DIR = "packages/os/site-kernel-handoff/src/werkstatt";
+const SCAN_DIR = "packages/werkstatt-engine/src/handoff";
+const ALLOWLIST_DIR = "packages/werkstatt-engine/src/werkstatt";
 
 const DIRECT_WRITE_PATTERNS: Array<{ regex: RegExp; label: string }> = [
   { regex: /\bwriteFile\s*\(/g, label: "writeFile" },
@@ -56,10 +57,15 @@ export async function runWerkstattOperationValidate(
 
   const violations: Array<{ file: string; line: number; pattern: string }> = [];
 
-  const PRE_EXISTING_ALLOWLIST = new Set(["handoff-pack.ts", "materialize.ts", "bundle-io.ts"]);
+  const PRE_EXISTING_ALLOWLIST = new Set([
+    "handoff-pack.ts",
+    "materialize.ts",
+    "bundle-io.ts",
+    "platform-consistency.ts",
+  ]);
 
   for (const filePath of files) {
-    if (filePath.startsWith(allowlistPath) || filePath.includes("werkstatt")) continue;
+    if (filePath.startsWith(allowlistPath)) continue;
 
     const fileName = basename(filePath);
     if (fileName.endsWith(".test.ts") || fileName.endsWith(".spec.ts")) continue;

package/os/werkstatt/werkstatt.module.ts

@@ -9,6 +9,13 @@
   <item>RFC-0374: initial forgeWerkstattModule registering 3 werkstatt commands.</item>
   <item>RFC-0556: removed dynamic imports of @warpgogol/site-kernel-handoff and @warpgogol/site-kernel-checks, all handlers now inlined in forge/os/werkstatt/handlers/.</item>
   <item>RFC-1173: declare mutatesState on all kernel commands — collectDeclarationDiagnostics emits error-severity MUTATES-STATE-DECLARED, command.manifest.validate is the blocking consumer in packages.check, sweep declares the flag on every command definition (factories hardcode false for read-only check specs)</item>
+  <item>RFC-1231: step 1 — rename supportsAllSites to acceptsAllFlag
+
+Mechanical sweep: the field only ever gated --all argv acceptance; fan-out
+follows the parsed selector. Guard renamed assertAllSitesAllowed ->
+assertAllFlagAccepted, message updated. 417 declaration sites + type
+surfaces (KernelCommandMetadata, ForgeCommandMetadata) in one atomic pass.</item>
+  <item>RFC-1248: VITE-CLIENT-DEP-02 lazy-import gate + SCAN-02 validator reads-root existence check (RFC-1248)</item>
 </CHANGE_SUMMARY>
 */
 
@@ -25,20 +32,22 @@ export const forgeWerkstattModule: ForgeModule = {
   commands: [
     {
       name: "werkstatt.lock.status",
+      coverage: "operator" as const,
       mutatesState: false,
       description: "Report all Werkstatt locks, their age, owner, and staleness (RFC-0362).",
       scope: "workspace",
-      supportsAllSites: false,
+      acceptsAllFlag: false,
       flags: {},
       reads: [".werkstatt/locks/**"],
       execute: runWerkstattLockStatus,
     },
     {
       name: "werkstatt.lock.recover",
+      coverage: "operator" as const,
       description:
         "Classify and clean stale locks and staging artifacts (RFC-0362). Flags: --scope, --purge.",
       scope: "workspace",
-      supportsAllSites: false,
+      acceptsAllFlag: false,
       mutatesState: true,
       flags: {
         scope: { kind: "string", description: "Recover only a single lock scope." },
@@ -61,9 +70,9 @@ export const forgeWerkstattModule: ForgeModule = {
       description:
         "Validate that mutating Werkstatt commands use shared lock/idempotency/atomic-write helpers (RFC-0362).",
       scope: "workspace",
-      supportsAllSites: false,
+      acceptsAllFlag: false,
       flags: {},
-      reads: ["packages/os/site-kernel-handoff/src/**/*.ts"],
+      reads: ["packages/werkstatt-engine/src/handoff/**/*.ts"],
       execute: runWerkstattOperationValidate,
     },
   ],

package/os/workflow/workflow.module.ts

@@ -9,6 +9,13 @@
   <item>RFC-0075: Add workflow command module.</item>
   <item>RFC-0374: Migrated from packages/os/site-kernel/src/workflow/ to packages/forge/os/workflow/.</item>
   <item>RFC-1173: declare mutatesState on all kernel commands — collectDeclarationDiagnostics emits error-severity MUTATES-STATE-DECLARED, command.manifest.validate is the blocking consumer in packages.check, sweep declares the flag on every command definition (factories hardcode false for read-only check specs)</item>
+  <item>RFC-1231: step 1 — rename supportsAllSites to acceptsAllFlag
+
+Mechanical sweep: the field only ever gated --all argv acceptance; fan-out
+follows the parsed selector. Guard renamed assertAllSitesAllowed ->
+assertAllFlagAccepted, message updated. 417 declaration sites + type
+surfaces (KernelCommandMetadata, ForgeCommandMetadata) in one atomic pass.</item>
+  <item>RFC-1248: VITE-CLIENT-DEP-02 lazy-import gate + SCAN-02 validator reads-root existence check (RFC-1248)</item>
 </CHANGE_SUMMARY>
 */
 
@@ -32,19 +39,20 @@ export async function createForgeWorkflowModule(): Promise<ForgeModule> {
           "and per-chain phase links (RFC-0075 + RFC-0136).",
         scope: "workspace",
         flags: {},
-        supportsAllSites: true,
-        reads: [".agents/workflows/**/*.md", ".windsurf/workflows/**/*.md"],
+        acceptsAllFlag: true,
+        reads: [".agents/workflows/**/*.md", ".windsurf/workflows/**/*.md"], // scan-coverage: optional tool dirs — workshops declare workflows under either
         execute: runWorkflowLint,
       },
       {
         name: "workflow.list",
+        coverage: "operator" as const,
         mutatesState: false,
         description:
           "List .agents/workflows entries with phase, IO summary, and next workflow (RFC-0075).",
         scope: "workspace",
         flags: {},
-        supportsAllSites: true,
-        reads: [".agents/workflows/**/*.md", ".windsurf/workflows/**/*.md"],
+        acceptsAllFlag: true,
+        reads: [".agents/workflows/**/*.md", ".windsurf/workflows/**/*.md"], // scan-coverage: optional tool dirs — workshops declare workflows under either
         execute: runWorkflowList,
       },
       {
@@ -54,7 +62,7 @@ export async function createForgeWorkflowModule(): Promise<ForgeModule> {
           "List .agents/workflows-amend entries with phase, IO summary, and next workflow (RFC-0136).",
         scope: "workspace",
         flags: {},
-        supportsAllSites: true,
+        acceptsAllFlag: true,
         reads: [".agents/workflows-amend/**/*.md"],
         execute: runWorkflowAmendList,
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpgogol/forge",
-  "version": "5.3.4",
+  "version": "6.2.0",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",

package/skills/_shared/fo-pipeline-conventions.md

@@ -27,6 +27,27 @@ Stage only the files this skill produces or modifies. Another agent may be worki
 - **RFC pipeline**: create → audit → enhance → plan → implement (includes review → fix)
 - **ADR pipeline**: create → implement (includes review → fix)
 
+## Review triggers (T1/T2/T3)
+
+Reviews fire on mandatory triggers across the pipeline lifecycle, not only at delivery.
+
+| Trigger | Point | Covered by |
+| --- | --- | --- |
+| T1 — plan review | Before implementation starts | `fo-idea-audit` + `fo-idea-enhance` + `fo-idea-plan` grilling (existing — declared, unchanged) |
+| T2 — checkpoint review | A step checkpoint that records an approach change vs. the plan, or a plan step that consumed >2 fix iterations | `fo-review` invocation scoped to the step diff, `independent` mode preferred |
+| T3 — pre-delivery review | End of `fo-idea-implement` | Existing; `independent` mode by default in the full pipeline |
+
+## Review blocking semantics
+
+`fo-review` verdicts carry `blockLevel` (`pass | warning | soft-block | hard-block`), mapped to `verdict` for backward compatibility (`fo-fix` consumes `verdict` unchanged).
+
+- **`hard-block` (`rejected`)** — the item must be corrected and then undergo a **full** re-review (not a delta on the flagged point) before it may proceed to stamping. At most two fix→re-review cycles inside one pipeline run; a third failure escalates to the operator regardless of mode. In queue mode the item stops before stamping and is recorded as blocked in the batch report; the batch continues.
+- **`soft-block` (`needs-revision` + `escalation: operator`)** — interactive mode: the pipeline pauses and escalates to the operator via a structured question (`acknowledge and continue` / `redirect` / `abort`), presenting stop/redirect as first-class options to counter the continue-bias. Queue mode: the item is paused, recorded in the batch summary as `awaiting operator arbitration`, the arbitration question is appended to the queue's decision ledger (§Decision ledger), and the batch continues with the next item.
+- **`warning` (`needs-revision`)** — findings are recorded as tracked observations; unresolved warnings at T3 escalate to `soft-block`.
+- **`pass` (`approved`)** — no fracture signals; zero findings.
+
+**Queue-mode resume:** a parked item resumes by re-invoking the orchestrator with the same manifest — `queue.validate` derives the continuation point from document status (the queue resume contract). Parking never leaves an item stranded without a defined re-entry path. `blocked` remains report language only — never persisted into RFC frontmatter or queue manifests.
+
 ## Minimality ladder
 
 Before writing implementation code, climb the minimality ladder. Stop at the first rung that holds — that is your implementation. The ladder runs after you understand the problem (read the code, trace the flow), not instead of it.
@@ -229,6 +250,7 @@ When the orchestrator skill processes multiple documents (>=2), perform a contex
    - `commits`: list of commit SHAs produced for this document
    - `lessons`: 1-3 short freeform sentences capturing key errors, root causes, patterns discovered, or validator quirks encountered during this document's pipeline run
    - `dependencies`: cross-RFC dependency notes (e.g., "RFC-YYYY depends on RFC-XXXX for schema field Z") — empty if none
+   - `unclosed`: list of `{ item, state: closed | unclosed | undecidable }` — mandatory when the item carried a checklist structure (§Tri-state closure marking); required in particular when `status` is `failed` or the item was parked
    - `next`: id of the next document to process, or `null` if this was the last
 2. **Release context** — explicitly treat all detailed context from the completed document as no longer actionable: file contents, search results, edit operations, intermediate reasoning. Retain only the checkpoint block. Release means treat as no longer actionable for reasoning, not delete or undo.
 3. **Fresh start** — begin the next document with a fresh read phase: re-read the RFC file and all related documents (amends, supersedes, related RFCs, DNA invariants, AGENTS.md sections).
@@ -248,6 +270,7 @@ When the orchestrator skill implements a single RFC with >=5 plan steps, perform
    - `commit`: SHA of the commit produced by this step
    - `decisions`: 1-3 short freeform sentences capturing key micro-decisions made during this step (e.g., "used flag instead of new command", "skipped validator X because it's in package Y, not in scope")
    - `errors`: list of errors encountered and fixed during this step — empty if none
+   - `unclosed`: list of `{ item, state: closed | unclosed | undecidable }` for every multi-item checklist the step carried — mandatory when a checklist exists (§Tri-state closure marking); three or more `undecidable` entries escalate to the operator
    - `nextStep`: number of the next plan step, or `null` if this was the last
 2. **Release step context** — treat all detailed context from the completed step as no longer actionable: codebase search results, file reads, edit operations, validation output. Retain only the step-checkpoint block and the RFC's plan file.
 3. **Fresh start** — begin the next plan step with a fresh read of the plan file and the specific files the next step touches.
@@ -270,12 +293,46 @@ The beacon text must use `aiLanguage` per the language policy.
 
 When a pipeline step fails and cannot be auto-fixed within 2 attempts (per §Command execution timeout discipline), emit a structured error checkpoint block in conversation output:
 
-1. **Emit error checkpoint** — output a YAML block with: rfc, step, planStep (if within implement phase), error (command, exitCode, summary, attempts), partialState (filesModified, commits, rfcStatus), resumePoint.
+1. **Emit error checkpoint** — output a YAML block with: rfc, step, planStep (if within implement phase), error (command, exitCode, summary, attempts), partialState (filesModified, commits, rfcStatus), resumePoint, unclosed (tri-state list per §Tri-state closure marking — mandatory here because a failing step always carries an implicit checklist of attempted sub-items).
 2. **Stop the pipeline** — do not continue to the next pipeline step. The error is not auto-fixable; continuing would compound the problem. This is an **explicit exception** to the orchestrator's "no pauses between pipeline steps" constraint. The "no pauses" directive assumes the pipeline can proceed; when an error is unfixable after 2 attempts, continuing is impossible and the exception is justified. The pause is for error reporting, not for optional operator input.
 3. **Report to operator** — present the error checkpoint in `aiLanguage` and ask the operator how to proceed: fix manually, skip the step, or abort the RFC.
 
 The error checkpoint doubles as a resume marker: when resuming an interrupted session, scan for the last error checkpoint. If found, resume from the failed step using the partialState and resumePoint fields.
 
+## Falsified-routes ledger
+
+Plan files (`docs/plans/plan-*.md`) MAY carry a `## Falsified routes` section — the negative-knowledge ledger for the work item:
+
+```markdown
+## Falsified routes
+
+| Route | Root cause | Falsified at | Forbidden retry |
+| --- | --- | --- | --- |
+| <approach tried> | <why it cannot work — the evidence, not the vibe> | <commit-sha or date> | yes \| no |
+```
+
+Rules for `fo-idea-implement` and `fo-fix`:
+
+- **Append on abandon** — when an approach is abandoned after a real attempt (not merely considered and skipped), append a row with the route, the root cause discovered, and falsified-at evidence (commit SHA or date). Never write prose instead of rows.
+- **Consult before proposing** — before proposing an alternative route, read the plan's `## Falsified routes` section. A `Forbidden retry: yes` row rejects a matching proposal unless the proposal states a new fact that invalidates the recorded root cause. A plan-prescribed route that matches a forbidden row counts as an approach change for this rule — consult applies even when the route was chosen by a previous session.
+- **Rows are never deleted** — a superseded route gets a `revivedAt` annotation: annotate the row's Route cell as `<route> (revived <date>: <new fact that invalidates the root cause>)`, matching criterion-versioning discipline. An empty or absent section is legal: the ledger is required only when an approach was actually abandoned.
+- `blocked` and `falsified` are report and ledger vocabulary — never persist them into RFC frontmatter or queue manifests.
+
+### Blind-spot pass
+
+After **two failed attempts on the same approach** within one work item — whether during step execution or the fix loop — and before the next retry or pivot, dispatch a clean-context re-examination using the same artifacts-only contract as `fo-review` `independent` mode: the problem statement, the falsified-routes table, the raw failing-run evidence, and the settled conclusion phrased as a question — never the executor's session narrative or self-assessment. The pass answers one question: _is the settled conclusion ("dead end", "impossible", "only option left") actually supported by evidence?_ Where no subagent primitive exists, degrade to an `isolated-inline` re-derive-from-artifacts pass and record that mode. The record lands in the session output and in the next step checkpoint's `decisions` field.
+
+The pass runs once per approach — it never chains recursively. It answers a different question than the T2 checkpoint review (conclusion validity vs. implementation quality), so neither de-duplicates against the other.
+
+## Tri-state closure marking
+
+Checkpoint blocks and handoff documents declare their open items with a tri-state value — `closed | unclosed | undecidable` — so that "silently forgotten" is distinguishable from "done".
+
+- **Mandatory-if-any:** wherever a checkpoint or handoff carries a multi-item checklist or unclosed-items structure, the `unclosed` list is mandatory and must state every item: `unclosed: [{ item, state: closed | unclosed | undecidable }]`. Where the anchor is a simple declare/verify with no checklist structure, `unclosed` may be absent entirely — the mandate binds the structure, not every anchor.
+- **Absence is never success:** an item absent from `unclosed` after the checkpoint executes is treated as `undecidable`.
+- **`undecidable` is explicit and legal:** an executor that cannot determine closure records `undecidable` — never silence.
+- **Escalation:** a checkpoint carrying three or more `undecidable` items escalates to the operator instead of continuing — the tri-state exists to surface uncertainty, not to warehouse it.
+
 ## Pipeline continuation
 
 When a pipeline step completes (audit, enhance, plan), the agent MUST proactively suggest the next step and offer to proceed. This is NOT automatic chaining — the agent asks the operator first. This applies when the operator is manually driving the pipeline step by step.
@@ -322,3 +379,71 @@ When the orchestrator skill processes multiple documents (>=2), emit a batch pla
 The preview is informational — it does not pause for operator approval unless the operator explicitly requests confirmation. The operator's invocation of the orchestrator is the instruction to proceed.
 
 The preview text must use `aiLanguage` per the language policy.
+
+## Decision ledger
+
+Every orchestrator run materializes a queue manifest (single-document runs are a one-item queue) and owns a **decision ledger** sibling: `docs/queues/<id>.decisions.yaml`. The ledger is the durable record of "what requires operator judgment" for that queue — committed, append-only, survives sessions, isolated per manifest so parallel batches in different sessions never share mutable decision state.
+
+The ledger's `id` field equals the filename stem `<manifest-id>.decisions`, and its `queue` field equals the manifest `id` — `queue.validate` enforces both bindings (QUEUE-02) plus `Q-N` uniqueness (QUEUE-05), so a misplaced or copy-pasted ledger can never apply foreign decisions to this queue. `answered` and `auto-resolved` entries MUST carry `answer`, and every entry's `doc` MUST be a manifest item — violations surface as non-blocking QUEUE-08 warnings. Schema lives in `packages/forge/os/queue/types.ts` (`decisionLedgerSchema`).
+
+Status vocabulary for `items[]` entries:
+
+- `open` — awaiting the decision window; blocks execution (QUEUE-07) unless the entry is `parked`.
+- `answered` — decided by the operator at the window; carries `answer` + `answeredAt`.
+- `auto-resolved` — the agent applied its recommended option and logged it. Covers both resolved-by-inference rows emitted during maturation (shown at the window for dispute) and emergent questions auto-resolved during execution; carries `answer` + `answeredAt`.
+- `deferred` — the operator deferred; the item is parked for this run.
+
+Parking vocabulary: `parked: true` on an `open` entry means the _system_ parked the item pending arbitration — written only by the enumerated parking paths (execution hard-stop per §Auto-resolve and log, soft-block review arbitration). `deferred` means the _operator_ parked it at a window. Both make the item non-executable this run; `queue.validate`'s `next` skips them, and an item whose `dependsOn` target is parked is itself parked (cascade). QUEUE-07 is an error: an item derivable to the implement stage (RFC `pipelineStep: implement`, or a non-terminal ADR) that is NOT parked and carries ≥1 un-parked `open` entry blocks `queue.validate`. A parked entry never fires QUEUE-07 — the park is already the containment; it surfaces in the briefing's parked section and waits for the next window's arbitration. An un-parked `open` on an implementable item means "collected but never resolved" — its presence routes the run into the decision window rather than halting it, and the only suppression is resolving the entries.
+
+The rendered human view is `docs/queues/<id>.briefing.md` — generated from the ledger, never the source of truth.
+
+**Pending-decision markers.** Documents carry `> PENDING DECISION: Q-N — <one-line question>` blockquote markers at the point where an answer matters (RFC section, plan step). A document with open markers cannot transition to `accepted`, and an implementable document with open markers trips QUEUE-07. Markers lift during the resolution phase when the answer lands.
+
+The ledger is append-only: changing an `answered` entry is forbidden. A disputed or superseded decision gets a new entry referencing the old `Q-N` — never an in-place edit. `blocked`, `parked`, and `deferred` are report/ledger vocabulary — never persisted into RFC frontmatter or queue manifests.
+
+## Collect and finalize contract
+
+Pipeline steps that produce operator-facing questions run in one of two modes:
+
+- **`interview`** (standalone skill invocations — the operator is at the keyboard): ask inline, one question at a time, as today.
+- **`collect`** (orchestrator-driven runs with a queue manifest): never call `ask_user_question` for pipeline questions. Emit each unresolved question as a ledger entry with `status: open`, a `resolutionPath`, and recommended options; apply all autonomous work; leave `PENDING DECISION` markers where an answer is required.
+- **`finalize`** (the resolution phase after the window): consume `answered` entries, integrate them into the document, lift markers, complete the stage's stamps and commits. Finalize per document is atomic — a crash mid-document leaves markers intact and the next run re-finalizes idempotently.
+
+Mode trigger: collect/finalize activate only under an orchestrator run carrying a manifest + ledger path. Everything else is `interview`.
+
+## Decision window
+
+The decision window is the single scheduled operator interaction of a queue run — placed after maturation, before execution. It doubles as the batch acceptance act: `draft → accepted` transitions happen in the resolution phase that follows the window, so the operator signs off having seen every trade-off at once.
+
+Window mechanics:
+
+- The orchestrator renders the ledger into `docs/queues/<id>.briefing.md`: batch header, batch policies, per-document decision blocks (question, `resolutionPath`, options with `recommended`, consequences), the resolved-by-inference list (disputable at a glance), and the parked-items section.
+- The operator answers in free text — codes like `Q-03: B`, `all — per recommendations`, `Q-07: defer`. `ask_user_question` is legal only for ≤4 highest-risk decisions (it cannot carry open-ended answers).
+- Batch `policies[]` collapse identical questions across documents — answer once, items inherit unless overridden.
+- One bounded follow-up round is permitted only when an answer invalidates a drafted plan and surfaces a genuinely new trade-off; then the batch proceeds.
+
+## Self-resolution ladder
+
+Before any question reaches the ledger, the emitting skill MUST exhaust these rungs in order — a fact is looked up, never asked:
+
+1. **codebase** — the answer is a fact in the repository; find it.
+2. **convention** — derivable from DNA invariants, AGENTS.md rules, established patterns; record as inference.
+3. **profile** — covered by `PREFERENCES.md`, `.agents/operator-profile.md`, or grilling `learned-principles.md` (`status: active`).
+4. **policy** — already answered by a batch-level `policies[]` entry or an identical earlier question.
+5. **none** — a genuine trade-off only the operator can settle → ledger entry.
+
+Every ledger entry records which rung produced it (`resolutionPath`) — this disciplines the agent and gives the operator audit context. Inferences land in the ledger too (as briefing-visible "resolved-by-inference" rows) — the operator reviews them at the window but answers only genuine `none`-rung trade-offs.
+
+## Auto-resolve and log
+
+Questions discovered during execution (emergent questions) do not interrupt the operator. The agent applies its recommended option and appends a ledger entry with `status: auto-resolved` — append-only evidence, disputable post-factum via a follow-up document, never silently decided.
+
+Only the **hard-stop** class parks an item instead of auto-resolving:
+
+1. DNA-invariant changes or conflicts.
+2. Security or privacy impact.
+3. External-contract changes (Verbund, third-party APIs, published interfaces).
+4. Irreversible or data-destructive operations.
+5. Hard-block review verdicts surviving two fix→re-review cycles.
+
+A hard-stopped question lands in the ledger as `status: open` + `parked: true`; the item parks, `dependsOn` dependents cascade-park, and the batch continues. These items surface for arbitration in the final batch report — or at the start of the next session with the same manifest.

package/skills/fo/fo-doc-audit/SKILL.md

@@ -49,7 +49,7 @@ The ecosystem has seven documentation surfaces. Each has a different audience an
 | **architecture-dna.md** | `ref(forge.yaml bindings.paths.invariantsFile)` | AI agents + humans | New DNA invariant, invariant amendment, or invariant retirement |
 | **Templates** | `packages/werkstatt-site/src/onboarding/templates/`, `packages/werkstatt-site/src/codegen/templates/` | Future apps/packages (scaffold time) | Change to what a new app or package should look like at creation time |
 | **Generated artifacts** | `docs/ecosystem.generated.json`, `docs/command-manifest.generated.yaml`, `fleet/*.generated.yaml`, `*.generated.css` | AI agents (read-only projection) | **Never edit directly** — update the generator or registry, then regenerate |
-| **COMMANDS / PACKAGE_GRAPH** | `docs/COMMANDS.md`, `docs/PACKAGE_GRAPH.md` | Humans + AI agents | New command, removed command, package graph change |
+| **Command / ecosystem docs** | `docs/COMMANDS.md`, `docs/ecosystem.generated.yaml` | Humans + AI agents | New command, removed command, package graph change — regenerate via `docs.commands.generate` / `ecosystem.manifest.generate`, never hand-edit |
 
 ## Process
 
@@ -147,12 +147,12 @@ ref(forge.yaml bindings.commands.produce) --workspace=command.manifest.generate
 
 Note: if the regeneration command is expensive or unavailable in the current session, document the need to regenerate in the session summary and move on.
 
-#### 2g. COMMANDS.md / PACKAGE_GRAPH.md
+#### 2g. Command / ecosystem doc surfaces
 
 - Were **commands** added, removed, or renamed?
 - Did the **package graph** change (new package, removed package, new dependency)?
 
-If yes, update `docs/COMMANDS.md` and/or `docs/PACKAGE_GRAPH.md`. If these are generated, update the generator instead (see 2f).
+If yes, regenerate the owned projections — `docs.commands.generate` refreshes `docs/command-manifest.generated.yaml` + `docs/COMMANDS.md`; `ecosystem.manifest.generate` refreshes `docs/ecosystem.generated.yaml` (the successor of the retired `docs/PACKAGE_GRAPH.md`). Never hand-edit generated files — update the generator or registry (see 2f).
 
 ### 3. Present analysis to the operator
 
@@ -264,7 +264,7 @@ Skills that delegate to `fo-doc-audit`:
 - **`fo-fix`** step 5 ("Documentation audit") — invokes `fo-doc-audit`.
 - **`fo-fix`** merge conflict resolution step 4 ("Documentation audit") — invokes `fo-doc-audit`.
 - **`fo-idea-implement`** step 4.9 ("Documentation audit") — invokes `fo-doc-audit`.
-- **`fo-idea-implement`** ADR-FLOW step 5.6 ("Documentation audit") — invokes `fo-doc-audit`.
+- **`fo-idea-implement`** step 5.6 ("Documentation audit", ADR path) — invokes `fo-doc-audit`.
 
 ## Constraints
 

package/skills/fo/fo-explore/SKILL.md

@@ -9,7 +9,7 @@ languagePolicy: ref(PREFERENCES.md)
 bindings:
   requires: [paths.invariantsFile]
   optional: []
-triggerPhrases: ["explore this idea", "let me think about this", "what are the options for", "what if we"]
+triggerPhrases: ["нам надо закрыть открытые вопросы", "explore this idea", "let me think about this", "what are the options for", "what if we"]
 ---
 
 <!--
@@ -23,6 +23,7 @@ triggerPhrases: ["explore this idea", "let me think about this", "what are the o
   <item>RFC-1097: sweep — SKILL.md headers + classification fixes
 
 Sweep batch 1: add Compass v2 headers to 45 SKILL.md files (purpose derived from frontmatter description). Fix non-skill-markdown exclusion to check filename not workspace-relative path (packages/AGENTS.md escaped it). Add .coverage to ignoredDirs.</item>
+  <item>RFC-1247: triggerPhrases vocabulary sync — mined operator phrasing applied to this skill's trigger set.</item>
 </CHANGE_SUMMARY>
 -->
 

package/skills/fo/fo-fix/SKILL.md

@@ -9,7 +9,7 @@ languagePolicy: ref(PREFERENCES.md)
 bindings:
   requires: [commands.typecheck]
   optional: [commands.test, paths.invariantsFile]
-triggerPhrases: ["fix issues from review", "apply review findings and fix", "iterative fix workflow for code"]
+triggerPhrases: ["исправим", "примени findings", "fix all", "fix issues from review", "apply review findings and fix"]
 ---
 
 <!--
@@ -20,9 +20,13 @@ triggerPhrases: ["fix issues from review", "apply review findings and fix", "ite
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
+  <item>RFC-1250: orchestrated-run contract — ambiguous findings auto-resolve
+  with auto-resolved ledger entries; hard-stop class parks the item instead of
+  asking.</item>
   <item>RFC-1097: sweep — SKILL.md headers + classification fixes
 
 Sweep batch 1: add Compass v2 headers to 45 SKILL.md files (purpose derived from frontmatter description). Fix non-skill-markdown exclusion to check filename not workspace-relative path (packages/AGENTS.md escaped it). Add .coverage to ignoredDirs.</item>
+  <item>RFC-1247: triggerPhrases vocabulary sync — mined operator phrasing applied to this skill's trigger set.</item>
 </CHANGE_SUMMARY>
 -->
 
@@ -87,10 +91,14 @@ If the review used the legacy format (`[Critical errors]`, `[Warnings]`, `[Concr
 For each finding:
 
 - If it includes a concrete line range or code snippet, apply the change directly.
-- If it is ambiguous, ask the user before changing.
+- If it is ambiguous, ask the user before changing — **except under an orchestrated queue run**: never call `ask_user_question` there. Auto-resolve the ambiguity with the recommended option and append a ledger entry `status: auto-resolved`; if the ambiguity falls in the hard-stop class (§Auto-resolve and log), append `status: open` + `parked: true` and park the item instead.
 - Do not delete or weaken existing tests without explicit direction.
 - Prefer minimal upstream fixes over downstream workarounds.
 
+**Falsified-routes ledger** — before choosing a fix approach for a finding, read the plan's `## Falsified routes` section when the work item carries a plan file: a `Forbidden retry: yes` row rejects the approach unless you can state a new fact that invalidates its root cause. When a fix approach is abandoned after a real attempt, append a row (route, root cause, falsified-at evidence) before moving on — when no plan file exists, record the falsified route in the session output instead. See `_shared/fo-pipeline-conventions.md` §Falsified-routes ledger.
+
+**Blind-spot pass after two failures on one approach** — after two failed attempts on the same fix approach, and before the next retry or pivot, run the clean-context blind-spot pass defined in `_shared/fo-pipeline-conventions.md` §Blind-spot pass.
+
 After applying fixes, update any tests that should cover the change, then run the relevant package tests before the full build when that saves time.
 
 ### 3. Run scoped typecheck verification
@@ -155,7 +163,7 @@ If no source files were touched, skip this step.
 
 This step is **always** performed — it is not optional and must not be skipped.
 
-Invoke `fo-doc-audit` via the `skill` tool. It analyzes the session's changes, checks all documentation surfaces (AGENTS.md, README, Compass XML, `ref(forge.yaml bindings.paths.invariantsFile)`, templates, generated artifacts, COMMANDS.md/PACKAGE_GRAPH.md), applies needed updates, and commits them separately. Wait for it to complete.
+Invoke `fo-doc-audit` via the `skill` tool. It analyzes the session's changes, checks all documentation surfaces (AGENTS.md, README, Compass XML, `ref(forge.yaml bindings.paths.invariantsFile)`, templates, generated artifacts, generated command docs (COMMANDS.md, ecosystem.generated.yaml)), applies needed updates, and commits them separately. Wait for it to complete.
 
 If `fo-doc-audit` reports that no updates are needed, state this explicitly and move on — the check itself is the mandatory part, not the outcome.