@warpgogol/forge 2.21.6 → 2.21.7

package/os/rfc/verification-refresh.ts

@@ -0,0 +1,216 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0999: re-run acceptance probes for implemented RFCs and update their
+verification evidence envelopes in-place. Preserves emittedAt, adds
+lastRefreshedAt, replaces probes[] with fresh results. Supports --id,
+--all, and --dry-run flags.
+</purpose>
+<non-goals>
+  <item>Do not duplicate probe execution — reuse runProbe from acceptance.ts.</item>
+  <item>Do not create new envelopes — refresh only updates existing ones.</item>
+  <item>Do not run for non-implemented RFCs — only implemented status has evidence.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0999: initial implementation.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { performance } from "node:perf_hooks";
+import { parse as yamlParse } from "yaml";
+
+import { runProbe } from "./acceptance.ts";
+import { listRfcFiles, readAndParseRfc } from "./frontmatter-io.ts";
+import { writeFileAtomic } from "../../src/utils/fs-atomic.ts";
+import { buildGeneratedHeader } from "../../src/utils/generated-marker.ts";
+import { stringify as yamlStringify } from "yaml";
+import {
+  captureGitContext,
+  getKernelVersion,
+  byteHashHex,
+  VERIFICATION_DIR,
+  buildEvidenceEnvelope,
+} from "./verification-evidence.ts";
+import { RFC_DIR } from "./types.ts";
+import type {
+  AcceptanceProbe,
+  RfcStatus,
+  VerificationEvidence,
+  VerificationEvidenceProbeRecord,
+  RfcVerificationRefreshResult,
+} from "./types.ts";
+import type {
+  Diagnostic,
+  ForgeCommandInput,
+  ForgeCommandResult,
+  ForgeRuntimeContext,
+} from "../../src/types.ts";
+
+function normalizeProbes(probes: AcceptanceProbe[]): string {
+  return JSON.stringify(probes, Object.keys(probes[0] ?? {}).sort());
+}
+
+export async function runRfcVerificationRefresh(
+  input: ForgeCommandInput,
+  context: ForgeRuntimeContext,
+): Promise<ForgeCommandResult<RfcVerificationRefreshResult>> {
+  const { workspaceRoot, logger, outputFormat } = context;
+  const rfcDirPath = join(workspaceRoot, RFC_DIR);
+  const targetId = input.flags["id"] as string | undefined;
+  const allMode = input.flags["all"] === true;
+  const dryRun = input.flags["dry-run"] === true;
+
+  if (!targetId && !allMode) {
+    return {
+      data: {
+        command: "rfc.verification.refresh",
+        status: "pass",
+        refreshed: [],
+        skipped: [],
+        diagnostics: [],
+        summary: { total: 0, passed: 0, failed: 0, skipped: 0 },
+      },
+      exitCode: 0,
+      summary:
+        "rfc.verification.refresh: pass --id <rfc-id> or --all to select target RFC(s)",
+    };
+  }
+
+  const allFiles = await listRfcFiles(rfcDirPath);
+  const refreshed: RfcVerificationRefreshResult["refreshed"] = [];
+  const skipped: RfcVerificationRefreshResult["skipped"] = [];
+  const diagnostics: Diagnostic[] = [];
+
+  const gitContext = await captureGitContext(workspaceRoot);
+  const kernelVersion = await getKernelVersion(workspaceRoot);
+
+  for (const fileName of allFiles) {
+    const parsedFile = await readAndParseRfc(rfcDirPath, fileName);
+    if (!parsedFile) continue;
+    if ("error" in parsedFile) continue;
+    const fm = parsedFile.parsed.frontmatter;
+    const rfcId = String(fm["id"] ?? "");
+    const status = String(fm["status"] ?? "");
+
+    if (targetId && rfcId.toLowerCase() !== targetId.toLowerCase()) continue;
+
+    if (status !== "implemented") {
+      skipped.push({ rfcId, reason: "not implemented" });
+      continue;
+    }
+
+    const slug = rfcId.toLowerCase();
+    const evidenceFileName = `${slug}.generated.yaml`;
+    const evidenceRelPath = join(VERIFICATION_DIR, evidenceFileName);
+    const evidenceAbsPath = join(workspaceRoot, evidenceRelPath);
+
+    let existingEnvelope: VerificationEvidence | null = null;
+    try {
+      const raw = await readFile(evidenceAbsPath, "utf-8");
+      const parsed = yamlParse(raw) as VerificationEvidence;
+      if (parsed && typeof parsed === "object" && parsed.rfcId) {
+        existingEnvelope = parsed;
+      }
+    } catch {
+      // file doesn't exist or can't be parsed
+    }
+
+    if (!existingEnvelope) {
+      skipped.push({ rfcId, reason: "no evidence envelope" });
+      continue;
+    }
+
+    const acceptance = fm["acceptance"];
+    if (!Array.isArray(acceptance) || acceptance.length === 0) {
+      skipped.push({ rfcId, reason: "no evidence envelope" });
+      continue;
+    }
+
+    const probes = acceptance as AcceptanceProbe[];
+    const probeRecords: VerificationEvidenceProbeRecord[] = [];
+    const rfcFilePath = join(rfcDirPath, fileName);
+    const rfcMarkdown = await readFile(rfcFilePath, "utf-8");
+    const now = new Date().toISOString();
+
+    for (const probe of probes) {
+      const start = performance.now();
+      const result = await runProbe(probe, workspaceRoot, context.commandRegistry);
+      const durationMs = Math.round(performance.now() - start);
+      probeRecords.push({
+        probe,
+        ok: result.ok,
+        detail: result.detail,
+        durationMs,
+      });
+    }
+
+    const envelope = buildEvidenceEnvelope(
+      rfcId,
+      String(fm["title"] ?? ""),
+      String(fm["status"] ?? "") as RfcStatus,
+      rfcMarkdown,
+      probes,
+      probeRecords,
+      gitContext,
+      kernelVersion,
+      existingEnvelope.emittedAt,
+    );
+    envelope.lastRefreshedAt = now;
+
+    if (!dryRun) {
+      const yamlContent = `${buildGeneratedHeader({ filePath: evidenceRelPath, ownerCommand: "rfc.verification.refresh" })}${yamlStringify(envelope)}\n`;
+      await writeFileAtomic(evidenceAbsPath, yamlContent);
+    }
+
+    const probesFailed = probeRecords.filter((r) => !r.ok).length;
+    refreshed.push({
+      rfcId,
+      file: evidenceRelPath,
+      overall: envelope.overall,
+      probesTotal: probeRecords.length,
+      probesFailed,
+    });
+
+    if (envelope.overall === "fail") {
+      diagnostics.push({
+        ruleId: "RFC-REFRESH-01",
+        severity: "error",
+        file: evidenceRelPath,
+        message: `${rfcId}: refresh overall is "fail" — ${probesFailed}/${probeRecords.length} probe(s) failed.`,
+      });
+    }
+
+    if (outputFormat === "pretty") {
+      logger.info(
+        `[refresh] ${rfcId} → ${evidenceRelPath} (${envelope.overall}, ${probeRecords.length} probes${dryRun ? ", dry-run" : ""})`,
+      );
+    }
+  }
+
+  const passed = refreshed.filter((r) => r.overall === "pass").length;
+  const failed = refreshed.filter((r) => r.overall === "fail").length;
+  const hasFailures = failed > 0;
+  const hasSkippedNoEnvelope = skipped.some((s) => s.reason === "no evidence envelope");
+  const status: RfcVerificationRefreshResult["status"] = hasFailures ? "fail" : "pass";
+
+  return {
+    data: {
+      command: "rfc.verification.refresh",
+      status,
+      refreshed,
+      skipped,
+      diagnostics,
+      summary: {
+        total: refreshed.length,
+        passed,
+        failed,
+        skipped: skipped.length,
+      },
+    },
+    exitCode: hasFailures || hasSkippedNoEnvelope ? 1 : 0,
+    summary: `rfc.verification.refresh: ${refreshed.length} refreshed, ${skipped.length} skipped`,
+  };
+}

package/os/session/handlers/save.ts

@@ -265,6 +265,16 @@ export async function runSessionSave(
       if (outputFormat === "pretty") {
         logger.info(`Skipped ${rawFileName}: already converted to ${outputRel}`);
       }
+      // Delete raw file even when skipping — otherwise .atif files accumulate
+      if (!dryRun && !keepRaw) {
+        try {
+          await trashPath(rawFilePath);
+        } catch (err) {
+          if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+            throw err;
+          }
+        }
+      }
       continue;
     } catch {
       // Output doesn't exist — proceed

package/os/spec/spec-validate.test.ts

@@ -0,0 +1,59 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Prove vendored spec validation resolves materialized RFCs across the canonical RFC archive topology.</purpose>
+<non-goals><item>Do not duplicate individual integrity, graph, or amendment rule tests.</item></non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY><item>Gap fix: cover SPEC-07 after terminal RFC archival.</item></CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import type { ForgeRuntimeContext } from "../../src/types.ts";
+import { runSpecValidate } from "./spec-validate.ts";
+
+const roots: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => fs.rm(root, { recursive: true, force: true })));
+});
+
+describe("spec.validate SPEC-07", () => {
+  it("accepts a materialized RFC after docs.archive moves it below archive/implemented", async () => {
+    const workspaceRoot = await fs.mkdtemp(path.join(os.tmpdir(), "spec-validate-archive-"));
+    roots.push(workspaceRoot);
+    const specDir = path.join(workspaceRoot, "docs/specs/example");
+    const archiveDir = path.join(workspaceRoot, "docs/rfcs/archive/implemented");
+    await fs.mkdir(specDir, { recursive: true }); await fs.mkdir(archiveDir, { recursive: true });
+    await fs.writeFile(path.join(archiveDir, "rfc-9001-example.md"), "---\nid: RFC-9001\n---\n");
+    await fs.writeFile(path.join(specDir, "forge-spec.yaml"), `schema: forge/spec@1
+id: example
+title: Example
+version: 1.0.0
+status: accepted
+reviewers: []
+sourceNote: test fixture
+vendoredAt: 2026-09-03
+documents: {}
+decisions: []
+rfcs:
+  - id: EX-001
+    title: Archived RFC
+    dependsOn: []
+    wave: 1
+    sources: []
+    materializedAs: RFC-9001
+waves:
+  - id: 1
+    name: Test
+    goal: Exercise archived resolution
+`);
+    await fs.writeFile(path.join(specDir, "integrity.yaml"), "schema: forge/spec-integrity@1\nfiles: {}\n");
+    const context = { workspaceRoot, dryRun: false, outputFormat: "json",
+      logger: { section() {}, info() {}, warn() {}, error() {}, success() {} } } as ForgeRuntimeContext;
+    const result = await runSpecValidate({ argv: [], flags: { spec: "example" } }, context);
+    expect(result).toMatchObject({ exitCode: 0, data: { status: "pass",
+      specs: [{ id: "example", violations: [] }] } });
+  });
+});

package/os/spec/spec-validate.ts

@@ -9,6 +9,7 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0394: initial spec.validate handler with SPEC-01..07 rules.</item>
+  <item>Gap fix: resolve materialized RFCs recursively so terminal RFC archival does not invalidate accepted specs.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -19,6 +20,7 @@ import { parse as parseYaml } from "yaml";
 import { byteHash } from "../../src/utils/hash.ts";
 import { collectFiles } from "../../src/utils/fs.ts";
 import { loadForgeConfig } from "../../src/config/forge-config.ts";
+import { listRfcFiles } from "../rfc/frontmatter-io.ts";
 import type {
   ForgeCommandInput,
   ForgeCommandResult,
@@ -260,15 +262,15 @@ function checkDuplicates(spec: ForgeSpec, violations: SpecViolation[]): void {
 
 async function checkMaterializedAs(
   spec: ForgeSpec,
-  workspaceRoot: string,
   rfcDir: string,
   violations: SpecViolation[],
 ): Promise<void> {
+  const rfcFiles = await listRfcFiles(rfcDir);
   for (const node of spec.rfcs) {
     if (!node.materializedAs) continue;
     const rfcId = node.materializedAs;
-    const rfcFiles = await fs.readdir(rfcDir).catch(() => []);
-    const found = rfcFiles.some((f) => f.startsWith(rfcId.toLowerCase().replace(/^RFC-/, "rfc-")));
+    const prefix = rfcId.toLowerCase().replace(/^rfc-/, "rfc-");
+    const found = rfcFiles.some((file) => path.basename(file).startsWith(prefix));
     if (!found) {
       violations.push({
         rule: "SPEC-07",
@@ -467,7 +469,7 @@ export async function runSpecValidate(
     checkDuplicates(spec, violations);
 
     // SPEC-07: materializedAs
-    await checkMaterializedAs(spec, workspaceRoot, rfcDir, violations);
+    await checkMaterializedAs(spec, rfcDir, violations);
 
     // SPEC-08..11: Amendments (RFC-0397)
     const amendments = await loadAmendments(specDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpgogol/forge",
-  "version": "2.21.6",
+  "version": "2.21.7",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -169,6 +169,7 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1116.0",
+    "ajv": "^8.20.0",
     "picomatch": "^4.0.5",
     "trash": "^10.1.1",
     "yaml": "^2.9.0",

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

@@ -1,6 +1,6 @@
 ---
 name: fo-handoff
-description: Compact the current conversation into a handoff document for another agent to pick up. Saves to OS temp directory, not the workspace.
+description: Compact the current conversation into a handoff document for another agent to pick up. Saves to docs/handoffs/ (resolved from forge.yaml paths.handoffsDir) and commits via ecosystem.commit.
 invocation: user
 category: fo
 concerns: document-only
@@ -13,7 +13,7 @@ triggers: ["create a handoff document", "compact conversation for next agent", "
 
 Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
 
-Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS — not the current workspace.
+Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the project's handoffs directory (resolved from `forge.yaml` `paths.handoffsDir`, defaulting to `docs/handoffs/`), not the OS temp directory.
 
 ## Process
 
@@ -47,18 +47,27 @@ Redact any sensitive information, such as API keys, passwords, or personally ide
 
 ### 3. Save
 
-Save to the OS temporary directory — not the current workspace. On Windows, use `$env:TEMP`. On macOS/Linux, use `/tmp`.
+Resolve the target directory from `forge.yaml` `paths.handoffsDir` (falling back to `docs/handoffs/` if unset). Filename pattern: `handoff-YYYY-MM-DD-session-<brief-description>.md`.
 
 If the operator passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.
 
-### 4. Report
+### 4. Commit
+
+Commit the handoff document via `ecosystem.commit` so it survives stash operations and is available to the next session.
+
+```sh
+rtk pnpm exec werkstatt run ecosystem.commit --message "docs: add handoff document"
+```
+
+### 5. Report
 
 Tell the operator the absolute path of the handoff document and suggest opening a fresh session that references it. Report in `aiLanguage`.
 
 ## Constraints
 
-- **Do not save to the workspace.** The handoff document goes to the OS temp directory.
+- **Save to `docs/handoffs/`** (or the directory resolved from `forge.yaml` `paths.handoffsDir`). Never save to `/tmp/` or other temporary directories.
+- **Commit the handoff document** via `ecosystem.commit` after saving.
 - **Do not duplicate existing artifacts.** Reference them by path or URL.
 - **Redact sensitive information.** API keys, passwords, PII.
-- **Commit only your own files.** This skill does not commit anything — the handoff doc is in the temp directory. See `_shared/fo-pipeline-conventions.md` §Commit discipline.
+- **Stage only the handoff file.** See `_shared/fo-pipeline-conventions.md` §Commit discipline.
 - **Session summary.** End every session with the closing block defined in `_shared/fo-session-summary.md`.

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

@@ -91,7 +91,7 @@ Beyond V-13 (required sections exist) and V-14 (≥3 acceptance items), check th
 - **Rollout** describes default behavior, adoption path for existing apps, and new-app compliance.
 - **Alternatives considered** is honest — at least one real alternative with a rejection reason.
 - **Risks** includes agent misinterpretation risk and false-positive rate for validators.
-- **Acceptance criteria** items are checkable (can an agent or human verify each one?) and sufficient (do they cover the decision's full scope?).
+- **Acceptance criteria** items are checkable (can an agent or human verify each one?) and sufficient (do they cover the decision's full scope?). Run the reject checklist (RFC-1006): no non-atomic "and"-joined claims (V-39), no unbounded quantities like "fast" or "scalable" (V-40), no weasel verbs like "handle gracefully" (V-41). Check that document-readiness criteria (DR-N) are separated from system-conformance criteria (AC-N) if a `## Document readiness` section is present.
 - **Implementation notes for agents** are explicit behavioral rules, not vague guidance.
 
 #### Axis B — DNA alignment

package/skills/fo/fo-idea-create-rfc/SKILL.md

@@ -88,7 +88,7 @@ Read the generated file and the full template (`docs/rfcs/rfc-0000-template.md`)
 - **Rollout** — implementation order, generated-file refresh, migration path for existing apps.
 - **Alternatives considered** — at least one real alternative with a rejection reason.
 - **Risks** — including agent-misinterpretation risk and false-positive rates for validators.
-- **Acceptance criteria** — ≥3 checkable checkboxes mapped to implementation artifacts.
+- **Acceptance criteria** — EARS-form criteria with stable `AC-N:` identifiers, following the authoring standard in `packages/forge/skills/fo/fo-idea-create-rfc/acceptance-criteria-standard.md` (RFC-0996 + RFC-1006). Required mix: at least one behavior, one contract, one negative, and one sync criterion. 3–10 items. Each criterion is a falsifiable claim about an observable artifact, not an effort claim. One claim = one checking mechanism. Run the reject checklist (RFC-1006): no non-atomic "and"-joined claims, no unbounded quantities, no weasel verbs.
 - **Implementation notes for agents** — explicit MAY/MUST NOT rules, status-gate reminders, escalation triggers.
 
 When a section cannot be filled with confidence, insert `> NEEDS CLARIFICATION: <question>` instead of guessing. Do not leave sections empty or fill them with speculative content. Markers are resolved during the enhance step.

package/skills/fo/fo-idea-create-rfc/acceptance-criteria-standard.md

@@ -0,0 +1,75 @@
+# Acceptance Criteria Authoring Standard (EARS-based)
+
+> Source of truth: RFC-0996 (EARS form, required mix, evidence discipline) and RFC-1006 (phase separation, reject checklist, criterion versioning). This document is the canonical reference — templates and skills summarize and link to it, never fork the normative wording.
+
+## Agent instruction
+
+A criterion is a _falsifiable claim about an observable artifact_, not a description of work performed. Before writing each criterion, answer: _what command, test, or probe would turn red if this claim were false?_ If you cannot answer, the criterion is not ready — rewrite it or insert `> NEEDS CLARIFICATION`.
+
+**Form.** Each criterion carries a stable identifier `AC-N:` and uses EARS-style phrasing:
+
+- Invariant: `AC-N: THE <artifact> SHALL <observable property>`
+- Event-driven: `AC-N: WHEN <trigger>, THE <system> SHALL <response> [within <bound>]`
+- Failure-path: `AC-N: IF <violation>, THEN THE <system> SHALL <explicit failure behavior>`
+
+**One criterion = one claim = one checking mechanism.** Never bundle ("types defined AND command registered AND docs updated" is three criteria). Each criterion names its mechanism inline or via a probe.
+
+**Required mix.** A well-formed set (3–10 items) covers:
+
+1. **Behavior** — at least one criterion per user-visible or agent-visible behavior change, backed by a `run`/`test` probe or a named test file.
+2. **Contract** — schema/type/output-format claims, backed by `file-contains`, schema validation, or a compile check.
+3. **Negative** — at least one criterion asserting what _fails_ (wrong input rejected, gate blocks, error escalates). Specs that only describe the happy path are half-specs.
+4. **Sync** — docs/AGENTS.md/DNA updates, backed by `file-contains`.
+
+**Forbidden patterns:**
+
+- Effort claims: "code written", "X implemented", "refactored Y".
+- Unfalsifiable adverbs: "works correctly", "handles gracefully", "is robust".
+- Tautologies: "`rfc.validate` passes on this file" as the only substantive criterion.
+- Mind-reading: criteria whose truth requires asking the implementer.
+- Copied template boilerplate left unedited.
+
+**Probes.** Every criterion checkable by an existing probe kind MUST get a probe in `acceptance:` frontmatter. Criteria without a feasible probe must state their manual verification procedure explicitly — "manually verified" without a procedure is not evidence.
+
+**Evidence discipline (at check-off time).** `(evidence: ...)` must point to the _mechanism_, not the _artifact_: prefer `probe:AC-N` or `test: path/to/file.test.ts`, then `file:line`. Never check a box based on intention; run the mechanism first.
+
+**Self-test before submitting:** hand the criteria set to a hostile reviewer who has _only_ the repo and a shell. If they cannot verify every box without talking to you, the spec is prose, not a spec.
+
+## Phase separation (RFC-1006)
+
+RFCs have two phases of criteria:
+
+- **RFC-phase (document readiness)** — criteria that gate whether the document itself is ready for acceptance. These live in `## Document readiness` with `DR-N:` identifiers. They are NOT EARS statements about system behavior. Examples: "every considered alternative has a rejection reason", "the RFC states reversibility". Evidence is typically `file:line` pointing to the RFC itself.
+- **ADR-phase (acceptance criteria)** — criteria that verify the decision's implementation in the running system. These live in `## Acceptance criteria` with `AC-N:` identifiers. They ARE EARS statements with verification mapping (probe, test, or file:line).
+
+ADRs have only acceptance criteria (no document-readiness section).
+
+## Reject checklist (RFC-1006)
+
+Before submitting criteria, run this line-level reject check. A criterion that triggers any of these is rejected:
+
+1. **Not atomic** — two independently testable behaviors joined by "and" in a single criterion. Split into separate `AC-N` items. (V-39)
+2. **Unbounded quantity** — unitless numeric concepts: "fast", "scalable", "reasonable load", "efficiently", "high performance", "low latency". Replace with a specific number or reference the decision that sets it. (V-40)
+3. **Weasel verb** — closed set: "handle gracefully", "behave correctly", "as appropriate", "robust", "user-friendly", "works correctly", "is reliable". Replace with a specific observable behavior. (V-41)
+4. **No verification mapping** — a checked criterion without `(evidence: ...)` pointing to a mechanism. Already enforced by V-27 and V-37.
+
+The trigger lists for V-40 and V-41 are configuration constants in `validate-rules.ts` — they can be extended without an RFC.
+
+## Criterion versioning (RFC-1006)
+
+Criteria are append-only. To change an accepted criterion:
+
+1. Add a `> Superseded AC-N (YYYY-MM-DD): <reason>` annotation line above the original criterion.
+2. Add the new criterion with a new `AC-N` identifier.
+3. Never edit an accepted criterion in place — that erases the trace of what shipped.
+
+Superseded criteria are excluded from the unchecked count (V-26) but preserved in the document. Malformed supersession annotations are rejected by V-42.
+
+Example:
+
+```markdown
+> Superseded AC-3 (2026-09-15): original criterion was too broad, split into AC-3a and AC-3b
+- [x] AC-3: THE command SHALL return exit code 0 for valid input (evidence: test: test.ts:42)
+- [x] AC-3a: THE command SHALL return exit code 0 when input matches the schema (evidence: test: test.ts:42)
+- [x] AC-3b: IF input does not match the schema, THEN THE command SHALL return exit code 1 (evidence: test: test.ts:58)
+```

package/skills/fo/fo-idea-implement/SKILL.md

@@ -173,11 +173,12 @@ Read the RFC's `## Acceptance criteria` section. For each checkbox:
 1. **Verify the criterion is met semantically** — check the code does what the criterion says, run the relevant command, or inspect the artifact. Mechanical existence (command registered, test passes) is NOT sufficient. The criterion must describe observable behavior that the RFC defines, not just that a command exists.
 2. **Check for stubs** — if the code contains TODO, stub, not-implemented, or placeholder logic in the path the criterion covers, the criterion is NOT met. Implement the real logic before marking it.
 3. **If a criterion is not met**, implement the missing work, commit it, and re-verify.
-4. **Annotate every `[x]` with inline evidence** — add `(evidence: <file-path:line>, <test-or-command>)` to each checked criterion. This is enforced by V-27.
+4. **Annotate every `[x]` with inline evidence** — add `(evidence: ...)` to each checked criterion, pointing to the _checking mechanism_, not just the artifact. Prefer `probe:AC-N` or `test: path/to/file.test.ts`, then `file:line`. This is enforced by V-27 (RFC-0996 evidence discipline).
 5. **If a criterion cannot be met** (e.g., requires an external dependency not yet available, requires a pilot that is not registered), do NOT mark it `[x]` and do NOT stamp `implemented`. Instead, split the deferred work into a follow-up RFC via `rfc.supersede.propose`. An RFC with unchecked `[ ]` criteria cannot transition to `implemented` — this is enforced by V-26.
 6. **Ensure `reviewers` is non-empty** — `rfc.validate` enforces V-25: implemented RFCs with an empty `reviewers` field fail validation. Add at least one reviewer (e.g. `human:<name>`) before stamping `implemented`.
+7. **Check document readiness** (RFC-1006) — if the RFC has a `## Document readiness` section, verify every `DR-N` checkbox is checked `[x]`. Unchecked `DR-N` items block `accepted`/`implemented` status via V-38. Document readiness criteria cover document quality (sections present, risks described, alternatives considered), not system behavior — they are checked by inspecting the RFC itself, not by running code.
 
-Do not proceed to step 4.7 until every acceptance criterion checkbox is checked with evidence.
+Do not proceed to step 4.7 until every acceptance criterion checkbox AND every document readiness checkbox is checked with evidence.
 
 #### 4.7. Run acceptance probes and emit evidence
 

package/src/compass/contract-registry.ts

@@ -17,7 +17,7 @@ import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import picomatch from "picomatch";
 import type { ForgeConfig } from "../config/forge-config.ts";
-import { forgePluginManifestSchema } from "../plugin/ForgePluginManifest.ts";
+import { forgePluginManifestSchema } from "../plugin/forge-plugin-manifest.ts";
 import type {
   CompassContractBlockSpec,
   CompassContractRegistry,
@@ -27,15 +27,34 @@ import type {
 const BUILT_IN_SPECS: CompassContractBlockSpec[] = [
   {
     blockId: "module-contract",
-    requiredFor: ["packages/**/*.ts", "packages/**/*.tsx", "packages/**/*.astro", "packages/**/*.js", "packages/**/*.mjs", "services/**/*.ts", "apps/**/*.ts", "apps/**/*.tsx", "apps/**/*.astro"],
-    requiredTags: [
-      { name: "purpose", minWords: 10 },
-      { name: "non-goals" },
+    requiredFor: [
+      "packages/**/*.ts",
+      "packages/**/*.tsx",
+      "packages/**/*.astro",
+      "packages/**/*.js",
+      "packages/**/*.mjs",
+      "packages/**/SKILL.md",
+      "services/**/*.ts",
+      "apps/**/*.ts",
+      "apps/**/*.tsx",
+      "apps/**/*.astro",
     ],
+    requiredTags: [{ name: "purpose", minWords: 10 }, { name: "non-goals" }],
   },
   {
     blockId: "change-summary",
-    requiredFor: ["packages/**/*.ts", "packages/**/*.tsx", "packages/**/*.astro", "packages/**/*.js", "packages/**/*.mjs", "services/**/*.ts", "apps/**/*.ts", "apps/**/*.tsx", "apps/**/*.astro"],
+    requiredFor: [
+      "packages/**/*.ts",
+      "packages/**/*.tsx",
+      "packages/**/*.astro",
+      "packages/**/*.js",
+      "packages/**/*.mjs",
+      "packages/**/SKILL.md",
+      "services/**/*.ts",
+      "apps/**/*.ts",
+      "apps/**/*.tsx",
+      "apps/**/*.astro",
+    ],
     requiredTags: [],
   },
 ];

package/src/index.ts

@@ -160,7 +160,7 @@ export {
 export {
   forgePluginManifestSchema,
   type ForgePluginManifest,
-} from "./plugin/ForgePluginManifest.ts";
+} from "./plugin/forge-plugin-manifest.ts";
 
 // Compass contract types (RFC-0943)
 export type {

package/src/onboarding/doctor.ts

@@ -31,7 +31,7 @@ import { readFile, readdir, stat } from "node:fs/promises";
 import { readFileSync, existsSync } from "node:fs";
 import { join, relative, dirname, resolve } from "node:path";
 import { parse as parseYaml } from "yaml";
-import { forgePluginManifestSchema } from "../plugin/ForgePluginManifest.ts";
+import { forgePluginManifestSchema } from "../plugin/forge-plugin-manifest.ts";
 import type {
   ForgeCommandInput,
   ForgeCommandResult,

package/src/registry.ts

@@ -25,7 +25,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import type { ForgeConfig } from "./config/forge-config.ts";
-import { forgePluginManifestSchema } from "./plugin/ForgePluginManifest.ts";
+import { forgePluginManifestSchema } from "./plugin/forge-plugin-manifest.ts";
 
 /**
  * Every entry MUST be portable — it runs in any forge-bootstrapped project