@warpgogol/forge 5.3.4 → 6.2.0

package/os/core/docs-archive.test.ts

@@ -0,0 +1,136 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for the docs.archive this-run live-merge selection —
+collectLiveMergeTargets derives merge candidates purely from the rfc.archive
+moved[] result (into-archive + implemented), keeping a second docs.archive run
+at zero merge operations (RFC-1230, AC-3).</purpose>
+<non-goals>
+  <item>Do not invoke the docs.archive execute closure — the selection helper is the test seam.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1230: initial tests for collectLiveMergeTargets.</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-1235: failed-merge accounting tests — classifyLiveMergeOutcome, liveMergeFailureEntry, formatLiveMergeFailure, buildLiveMergeBlock (AC-1..4).</item>
+</CHANGE_SUMMARY>
+*/
+
+import { describe, it, expect } from "vitest";
+import {
+  collectLiveMergeTargets,
+  classifyLiveMergeOutcome,
+  liveMergeFailureEntry,
+  formatLiveMergeFailure,
+  buildLiveMergeBlock,
+} from "../spec/live-spec-shared.ts";
+
+function move(
+  id: string,
+  status: string,
+  direction: "into-archive" | "out-of-archive" = "into-archive",
+) {
+  return { id, status, direction, file: `docs/rfcs/${id}.md`, from: "", to: "" };
+}
+
+describe("docs.archive collectLiveMergeTargets (AC-3)", () => {
+  it("selects only RFCs moved into archive/implemented/ this run", () => {
+    const selection = collectLiveMergeTargets([
+      move("RFC-1001", "implemented"),
+      move("RFC-1002", "rejected"),
+      move("RFC-1003", "implemented", "out-of-archive"),
+      move("RFC-1004", "superseded"),
+    ]);
+
+    expect(selection.candidates).toEqual(["RFC-1001"]);
+    expect(selection.rejected).toEqual(["RFC-1002"]);
+  });
+
+  it("returns an empty selection when nothing moved — second docs.archive run", () => {
+    const selection = collectLiveMergeTargets([]);
+    expect(selection.candidates).toEqual([]);
+    expect(selection.rejected).toEqual([]);
+  });
+
+  it("ignores out-of-archive moves entirely", () => {
+    const selection = collectLiveMergeTargets([move("RFC-1001", "implemented", "out-of-archive")]);
+    expect(selection.candidates).toEqual([]);
+    expect(selection.rejected).toEqual([]);
+  });
+});
+
+describe("docs.archive failed-merge accounting (RFC-1235)", () => {
+  it("AC-1: exit-nonzero merge with populated data lands in failed[], not merged[]", () => {
+    // RFC-1230 fail-fast shape: exit 1 with a full data object.
+    const outcome = classifyLiveMergeOutcome("RFC-1299", {
+      exitCode: 1,
+      data: {
+        command: "spec.live.merge",
+        domain: "forge",
+        operation: "modified",
+        deltas: [],
+        conflicts: [],
+        dryRun: false,
+      },
+      summary:
+        "spec.live.merge: forge.md exists but has no valid frontmatter — inspect or repair via spec.live.rebuild",
+    });
+
+    expect(outcome.kind).toBe("failed");
+    if (outcome.kind === "failed") {
+      expect(outcome.entry.id).toBe("RFC-1299");
+      expect(outcome.entry.exitCode).toBe(1);
+      expect(outcome.entry.error).toContain("no valid frontmatter");
+    }
+  });
+
+  it("AC-2: thrown merge produces a failed[] entry carrying the error and a printable line", () => {
+    const failure = liveMergeFailureEntry("RFC-1299", new Error("boom: disk full"));
+    expect(failure.id).toBe("RFC-1299");
+    expect(failure.exitCode).toBeUndefined();
+    expect(failure.error).toBe("boom: disk full");
+
+    // The pretty path prints formatLiveMergeFailure(entry) via logger.error —
+    // asserting the formatted line proves the printed message carries id + error.
+    const line = formatLiveMergeFailure(failure);
+    expect(line).toContain("RFC-1299");
+    expect(line).toContain("boom: disk full");
+  });
+
+  it("AC-3: exit-0 merge keeps the merged[] shape and failed[] stays empty", () => {
+    const outcome = classifyLiveMergeOutcome("RFC-1230", {
+      exitCode: 0,
+      data: { domain: "forge", operation: "modified", conflicts: [] },
+    });
+    expect(outcome).toEqual({
+      kind: "merged",
+      entry: { id: "RFC-1230", domain: "forge", operation: "modified", conflicts: 0 },
+    });
+    expect(outcome.kind).toBe("merged");
+    const entry =
+      outcome.kind === "merged"
+        ? outcome.entry
+        : liveMergeFailureEntry("RFC-1230", new Error("unreachable"));
+
+    const block = buildLiveMergeBlock([entry], [], 0, false);
+    expect(block).toEqual({
+      merged: [{ id: "RFC-1230", domain: "forge", operation: "modified", conflicts: 0 }],
+      failed: [],
+      skipped: 0,
+      dryRun: false,
+    });
+  });
+
+  it("AC-4: all-failed and all-empty runs produce data, never a throw — archive stays non-fatal", () => {
+    const failure = liveMergeFailureEntry("RFC-1299", new Error("corrupt"));
+    const block = buildLiveMergeBlock([], [failure], 0, false);
+    // All-failed still emits the block — otherwise the failures stay invisible.
+    expect(block).toEqual({
+      merged: [],
+      failed: [{ id: "RFC-1299", error: "corrupt" }],
+      skipped: 0,
+      dryRun: false,
+    });
+    // Nothing attempted → no block at all (unchanged pre-RFC-1235 silence).
+    expect(buildLiveMergeBlock([], [], 0, false)).toBeUndefined();
+  });
+});

package/os/core/handlers/file-size-lint.ts

@@ -14,6 +14,7 @@ collectFiles and diagnosticsResult. Ratcheted baseline at workspace root.
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-1088: initial implementation — ported from packages/werkstatt-site/src/checks/file-size-lint.ts to forge for autonomy.</item>
+  <item>RFC-1249: wire werkstatt.commands.validate into packages.check + retire CMD-OUTPUT debt</item>
 </CHANGE_SUMMARY>
 */
 
@@ -53,6 +54,7 @@ export function countLines(source: string): number {
 async function collectSourceFiles(root: string): Promise<string[]> {
   const results: string[] = [];
 
+  // fs.walk.lint: allow — walks via WorkspaceIO abstraction (io.readdir), not node fs — collectFiles has no io contract
   async function walk(dir: string): Promise<void> {
     let entries;
     try {

package/os/exploration/exploration.module.ts

@@ -27,6 +27,7 @@ export async function createForgeExplorationModule(): Promise<ForgeModule> {
     commands: [
       {
         name: "exploration.list",
+        coverage: "operator" as const,
         description:
           "List all exploration notes in docs/explorations/. Returns id, title, status, and createdAt for each note. " +
           "Use --status <status> to filter by status (open, explored, archived). " +
@@ -46,6 +47,7 @@ export async function createForgeExplorationModule(): Promise<ForgeModule> {
       },
       {
         name: "exploration.show",
+        coverage: "operator" as const,
         description:
           "Show the full content of a single exploration note. Use --id <slug> to specify the note slug " +
           "(kebab-case, lowercase, latin-only). Returns the note's frontmatter and body. " +
@@ -66,6 +68,7 @@ export async function createForgeExplorationModule(): Promise<ForgeModule> {
       },
       {
         name: "exploration.archive",
+        coverage: "operator" as const,
         description:
           "Archive an exploration note by setting its status to 'archived'. Use --id <slug> to specify the note. " +
           "Use --rfc <RFC-XXXX> to add an RFC id to the note's 'related' field. " +

package/os/naming/naming-convention.ts

@@ -9,6 +9,7 @@ uses kebab-case (lowercase letters, digits, hyphens only), with documented exemp
 <CHANGE_SUMMARY>
   <item>RFC-0303: split out of structure.ts (Phase 3 file-size split).</item>
   <item>RFC-0360: extend scan roots from apps/ and packages/ to the whole repo.</item>
+  <item>RFC-1249: wire werkstatt.commands.validate into packages.check + retire CMD-OUTPUT debt</item>
 </CHANGE_SUMMARY>
 */
 
@@ -76,6 +77,9 @@ const NAMING_CONVENTION_IGNORED_TOP_LEVEL = new Set([
   "storage",
   ".check-warpgogol",
   ".coverage-report-html",
+  // Local-only operator dirs (gitignored): Ed25519 signing keys (RFC-0966) and scratch output.
+  ".keys",
+  ".scratch",
 ]);
 
 // Tool-mandated filenames exempt from kebab-case (Docker, Caddy use these exact names).
@@ -101,7 +105,13 @@ const NAMING_CONVENTION_IGNORED_DIRS = new Set([
   // RFC-0186) — the numeric-underscore prefix is required for ordering and is not authored prose.
   "migrations",
 ]);
-const NAMING_CONVENTION_EXEMPT_KEYWORDS = ["config", "module"] as const;
+const NAMING_CONVENTION_EXEMPT_KEYWORDS = [
+  "config",
+  "module",
+  // xrepo-<from>-to-<to>-<increment> handoff artifacts carry externally-referenced
+  // contract version pins (V01/V04/V05) — the uppercase token is the version id, not prose.
+  "xrepo",
+] as const;
 
 // Set of directory paths that are exempt from naming convention (generated files)
 const NAMING_CONVENTION_EXEMPT_DIRS = new Set([

package/os/naming/naming.module.ts

@@ -8,6 +8,13 @@
 <CHANGE_SUMMARY>
   <item>RFC-0374: initial forgeNamingModule registering naming.convention.lint.</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>
 */
 
@@ -29,14 +36,14 @@ export async function createForgeNamingModule(): Promise<ForgeModule> {
         description:
           "Validate all filenames use kebab-case (no underscores) across registered workspace roots.",
         scope: "workspace",
-        supportsAllSites: true,
+        acceptsAllFlag: true,
         flags: {
           "include-ignored": {
             kind: "boolean",
             description: "Also scan files ignored by .gitignore or .windsurfignore.",
           },
         },
-        reads: ["packages/**/*.{ts,tsx}", "apps/**/*.{ts,tsx}", "services/**/*.{ts,tsx}"],
+        reads: ["packages/**/*.{ts,tsx}", "apps/**/*.{ts,tsx}", "services/**/*.{ts,tsx}"], // scan-coverage: consumer-workshop root — apps/ exists in consumer workshops, not this monorepo
         execute: runNamingConventionLint,
       },
     ],

package/os/notes/notes.module.ts

@@ -8,6 +8,13 @@
 <CHANGE_SUMMARY>
   <item>RFC-0808: initial forgeNotesModule registering 3 note validation commands.</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>
 */
 
@@ -58,7 +65,7 @@ export async function createForgeNotesModule(): Promise<ForgeModule> {
         description:
           "Validate wikilink integrity across a markdown note vault. Scans [[wikilinks]] and resolves each against the note graph.",
         scope: "workspace",
-        supportsAllSites: false,
+        acceptsAllFlag: false,
         flags: {
           "vault-dir": {
             kind: "string",
@@ -69,19 +76,21 @@ export async function createForgeNotesModule(): Promise<ForgeModule> {
             description: "Subdirectory within the vault to scope the scan to.",
           },
         },
-        reads: ["vault/**/*.md"],
+        reads: ["vault/**/*.md"], // scan-coverage: consumer-vault root — vault/ exists in knowledge-profile workshops
         cacheable: false,
         execute: noteLinkValidateWrapper,
       },
       {
         name: "note.frontmatter.validate",
+        coverage: "operator",
+        coverageNote: "notes vault frontmatter hygiene (vault workshops)",
         mutatesState: false,
         contract: "note",
         rules: [],
         description:
           "Validate frontmatter consistency across a markdown note vault. Checks for required fields in YAML frontmatter.",
         scope: "workspace",
-        supportsAllSites: false,
+        acceptsAllFlag: false,
         flags: {
           "vault-dir": {
             kind: "string",
@@ -92,24 +101,26 @@ export async function createForgeNotesModule(): Promise<ForgeModule> {
             description: "Comma-separated list of required fields (default: title).",
           },
         },
-        reads: ["vault/**/*.md"],
+        reads: ["vault/**/*.md"], // scan-coverage: consumer-vault root — vault/ exists in knowledge-profile workshops
         cacheable: false,
         execute: noteFrontmatterValidateWrapper,
       },
       {
         name: "note.orphan.detect",
+        coverage: "operator",
+        coverageNote: "notes vault orphan detection (vault workshops)",
         mutatesState: false,
         description:
           "Detect orphan notes in a markdown note vault — notes with zero inbound wikilinks. Always exits zero (warnings, not errors).",
         scope: "workspace",
-        supportsAllSites: false,
+        acceptsAllFlag: false,
         flags: {
           "vault-dir": {
             kind: "string",
             description: "Vault directory relative to workspace root (default: vault).",
           },
         },
-        reads: ["vault/**/*.md"],
+        reads: ["vault/**/*.md"], // scan-coverage: consumer-vault root — vault/ exists in knowledge-profile workshops
         cacheable: false,
         execute: noteOrphanDetectWrapper,
       },

package/os/plan/plan-0000-template.md

@@ -0,0 +1,150 @@
+---
+rfcId: RFC-0000
+planId: PLAN-RFC-0000-01
+status: draft
+owner: architecture
+createdAt: YYYY-MM-DD
+updatedAt:
+scope:
+  apps: []
+  packages: []
+  services: []
+  docs: []
+---
+
+# Implementation Plan: RFC-0000
+
+## 1. Objectives
+
+<!-- 3-7 concrete objectives tied to RFC acceptance criteria.
+     Each objective should map to one or more acceptance-criteria
+     checkboxes in the RFC. -->
+
+- [ ] Objective 1 — maps to acceptance criterion [...]
+- [ ] Objective 2 — maps to acceptance criterion [...]
+
+## 2. Affected artifacts
+
+### 2.1 Code and commands
+
+<!-- packages/*, services/*, apps/* files.
+     Site OS commands (pnpm exec werkstatt run ...).
+     Registry entries, module registrations, pipeline wiring. -->
+
+### 2.2 Configuration and data
+
+<!-- YAML/JSON/NDJSON, system.md, manifests, biome files,
+     ontology catalogs (StarCatalog, PlanetCatalog, MoonCatalog),
+     content schemas, blueprints. -->
+
+### 2.3 Documentation and specs
+
+<!-- RFC file (read-only reference).
+     AGENTS.md (root, apps/, packages/, services/).
+     docs/*.xml Compass files (requirements, technology,
+     development-plan, knowledge-graph, verification-plan,
+     source-markup, styling).
+     docs/architecture-dna.md (if new DNA invariant). -->
+
+### 2.4 Validation and pipelines
+
+<!-- build.check, build.prepare, apps-check, apps-check-postbuild.
+     CI workflows (.github/workflows/).
+     New or changed validate commands. -->
+
+## 3. Step sequence
+
+### Step 1. [Step title]
+
+**Goal:** [what this step achieves]
+
+**Agent actions:**
+
+- [concrete action]
+- [concrete action]
+
+**Validation:**
+
+- [command or check that confirms completion]
+
+**Completion criterion:** [checkable condition]
+
+**Human review:** [yes/no — if yes, what needs approval and from whom]
+
+---
+
+### Step 2. [Step title]
+
+<!-- Repeat for each step. Follow the contract-first ordering:
+     contracts → commands → documentation → tests → validation → evidence. -->
+
+### Final Step. Documentation sync, review, fix, and acceptance criteria verification
+
+**Goal:** Synchronize all documentation artifacts, run code review and fix, verify acceptance criteria, and stamp the RFC as implemented.
+
+**Agent actions:**
+
+- Update affected `AGENTS.md` files (root, apps/, packages/, services/) with new modules, commands, or ownership changes.
+- Update affected `docs/*.xml` Compass files (requirements, technology, development-plan, knowledge-graph, verification-plan, source-markup, styling) when repository-wide semantics changed.
+- Update `docs/architecture-dna.md` if a new DNA invariant was introduced.
+- **Verify every file listed in `scope.docs` is updated** — check each path against `git diff`; if a scope doc was not modified, document why.
+- Run `pnpm exec werkstatt run ecosystem.manifest.generate` if command surfaces or pipeline topology changed (do not hand-edit `docs/ecosystem.generated.yaml`).
+- **Run code review:** invoke `fo-review` via the `skill` tool on all session code changes (`git diff <merge-base-of-session>...HEAD`). Wait for the review report in `docs/reviews/code/`.
+- **Run fix if needed:** if `fo-review` reported findings, invoke `fo-fix` via the `skill` tool. Re-run `fo-review` to confirm all findings are resolved. Maximum 3 iterations.
+- **Check off acceptance criteria:** verify each criterion in the RFC against the implemented code. Mark `[x]` for verified criteria. For unchecked `[ ]` criteria, document why (e.g. "requires runtime command blocked by environment").
+- **Stamp the RFC as implemented:** run `pnpm exec werkstatt run rfc.implement.stamp --id RFC-XXXX --implementation-commit <sha>` to atomically transition `accepted → implemented` (RFC-0476). The command validates all preconditions (status, criteria, clean tree, commit reachability). Do NOT hand-edit `status`, `implementedAt`, or `closedAt` fields — use the command.
+
+**Validation:**
+
+- `git status` — no uncommitted changes from the current session.
+- `pnpm exec werkstatt run rfc.validate --id RFC-XXXX`
+- Every file in `scope.docs` is either updated or documented as not-applicable.
+- Review report exists in `docs/reviews/code/` for this session.
+
+**Completion criterion:** All documentation artifacts in scope are updated; code review passed (findings fixed if any); all acceptance criteria are checked off with inline `(evidence: ...)` annotations; RFC is stamped as `implemented` via `rfc.implement.stamp`.
+
+**Human review:** no — the `accepted → implemented` transition is automated via `rfc.implement.stamp` (RFC-0476), which validates all preconditions atomically. Code review is automated via `fo-review`.
+
+## 4. Validation suite
+
+### 4.1 Required checks
+
+<!-- Commands that must pass before stamping implemented (RFC-0224). -->
+
+- `pnpm exec werkstatt run rfc.validate --id RFC-XXXX`
+- `pnpm --filter <package> run build:check`
+- `pnpm exec werkstatt run rfc.acceptance.run --id RFC-XXXX` (if acceptance probes declared)
+- `pnpm exec werkstatt run rfc.verification.emit --id RFC-XXXX` (RFC-0330, for probe-bearing RFCs created on or after 2026-07-07)
+
+### 4.2 Evidence artifacts
+
+<!-- What to commit alongside the implemented status. -->
+
+- `docs/rfcs/verification/rfc-xxxx.generated.json` — verification evidence (RFC-0330)
+- Commit messages referencing `RFC-XXXX` in the subject line (RFC-0265 commit hygiene)
+
+## 5. Risks and mitigation
+
+<!-- Map each risk from the RFC's Risks section to specific plan
+     steps that control it. -->
+
+| Risk (from RFC) | Mitigation (plan step)   |
+| --------------- | ------------------------ |
+| [risk text]     | [how step N controls it] |
+
+## 6. Escalation triggers
+
+<!-- Conditions that should trigger rfc.supersede.propose (RFC-0334)
+     instead of working around an invariant conflict. -->
+
+- If implementation reveals an invariant conflict with DNA-N, run `pnpm exec werkstatt run rfc.supersede.propose --id RFC-XXXX --reason "..." --invariant "DNA-N"` instead of working around it.
+
+## Falsified routes
+
+<!-- Negative-knowledge ledger — append a row whenever an approach is
+     abandoned after a real attempt. Consult before proposing alternatives;
+     "yes" rows reject matching proposals without a stated new fact.
+     Rows are never deleted — superseded rows get a revivedAt annotation. -->
+
+| Route | Root cause | Falsified at | Forbidden retry |
+| ----- | ---------- | ------------ | --------------- |

package/os/plan/plan.module.ts

@@ -22,6 +22,8 @@ export async function createForgePlanModule(): Promise<ForgeModule> {
     commands: [
       {
         name: "plan.archive",
+        coverage: "delegated",
+        coverageNote: "dispatched by docs.archive as a function call",
         description:
           "Move plan files whose parent RFC has terminal status " +
           "(implemented, rejected, superseded) into docs/plans/archive/<status>/ " +

package/os/plugin/plugin.module.ts

@@ -9,6 +9,12 @@
 <CHANGE_SUMMARY>
   <item>RFC-0941: initial forgePluginModule with forge.plugin.validate and forge.plugin.discover commands.</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>
 </CHANGE_SUMMARY>
 */
 
@@ -244,7 +250,7 @@ export const forgePluginModule: ForgeModule = {
       description:
         "Validate forge.plugin.yaml manifests for all declared skill packs (RFC-0941). Checks manifest schema (id: kebab-case, version: semver) and reports missing or invalid manifests.",
       scope: "workspace",
-      supportsAllSites: false,
+      acceptsAllFlag: false,
       flags: {},
       reads: ["forge.yaml", "**/forge.plugin.yaml"],
       cacheable: false,
@@ -252,11 +258,12 @@ export const forgePluginModule: ForgeModule = {
     },
     {
       name: "forge.plugin.discover",
+      coverage: "operator" as const,
       mutatesState: false,
       description:
         "Enumerate all project-declared skill packs with valid forge.plugin.yaml manifests (RFC-0941). Returns pack id, version, prefix, and directory.",
       scope: "workspace",
-      supportsAllSites: false,
+      acceptsAllFlag: false,
       flags: {},
       reads: ["forge.yaml", "**/forge.plugin.yaml"],
       cacheable: false,

package/os/program/program.module.ts

@@ -9,6 +9,12 @@ kernel registry (RFC-0856).</purpose>
 <CHANGE_SUMMARY>
   <item>RFC-0856: initial program module registration.</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>
 </CHANGE_SUMMARY>
 */
 
@@ -28,6 +34,8 @@ export async function createForgeProgramModule(): Promise<ForgeModule> {
     commands: [
       {
         name: "program.packet.validate",
+        coverage: "operator" as const,
+        coverageNote: "requires --program",
         mutatesState: false,
         execOnReadOnly: true,
         contract: "program",
@@ -37,7 +45,7 @@ export async function createForgeProgramModule(): Promise<ForgeModule> {
           "and state machine rules. Read-only. " +
           "Usage: program.packet.validate --program=RFC-XXXX --packet=NNN-foo --phase=draft --json",
         scope: "workspace",
-        supportsAllSites: false,
+        acceptsAllFlag: false,
         flags: {
           program: {
             kind: "string",
@@ -64,6 +72,7 @@ export async function createForgeProgramModule(): Promise<ForgeModule> {
       },
       {
         name: "program.packet.seal",
+        coverage: "operator" as const,
         description:
           "Steward finalizes a packet against the predecessor's completion commit, " +
           "updates packet state from draft to sealed, and records the seal in the " +
@@ -71,7 +80,7 @@ export async function createForgeProgramModule(): Promise<ForgeModule> {
           "Usage: program.packet.seal --program=RFC-XXXX --packet=NNN-foo " +
           "--steward=human:id --idempotency-key=<key> --json",
         scope: "workspace",
-        supportsAllSites: false,
+        acceptsAllFlag: false,
         mutatesState: true,
         flags: {
           program: {
@@ -106,6 +115,7 @@ export async function createForgeProgramModule(): Promise<ForgeModule> {
       },
       {
         name: "program.packet.lease",
+        coverage: "operator" as const,
         mutatesState: true,
         description:
           "Manage the exclusive local executor lease for a sealed packet. " +
@@ -114,7 +124,7 @@ export async function createForgeProgramModule(): Promise<ForgeModule> {
           "Usage: program.packet.lease --program=RFC-XXXX --packet=NNN-foo " +
           "--action=start --executor=agent:id --json",
         scope: "workspace",
-        supportsAllSites: false,
+        acceptsAllFlag: false,
         flags: {
           program: {
             kind: "string",
@@ -135,6 +145,10 @@ export async function createForgeProgramModule(): Promise<ForgeModule> {
             kind: "string",
             description: "Executor actor id (required for --action=start).",
           },
+          phase: {
+            kind: "string",
+            description: "Lease phase: preparation or execution (default: execution).",
+          },
           steward: {
             kind: "string",
             description: "Steward actor id (required for --action=recover).",
@@ -160,6 +174,7 @@ export async function createForgeProgramModule(): Promise<ForgeModule> {
       },
       {
         name: "program.packet.complete",
+        coverage: "operator" as const,
         description:
           "Steward validates the implementation range, writes the completion report, " +
           "and updates the program manifest. Supports --bootstrap for packet 000. " +
@@ -167,7 +182,7 @@ export async function createForgeProgramModule(): Promise<ForgeModule> {
           "Usage: program.packet.complete --program=RFC-XXXX --packet=NNN-foo " +
           "--steward=human:id --lease-token=<token> --implementation-head=<sha> --json",
         scope: "workspace",
-        supportsAllSites: false,
+        acceptsAllFlag: false,
         mutatesState: true,
         flags: {
           program: {