@warpgogol/forge 2.21.5 → 2.21.7

package/AGENTS.md

@@ -18,7 +18,7 @@ Packet 000 will add the portable `forge/program@1` control plane under `os/progr
 | Module | Commands | Source |
 | --- | --- | --- |
 | `forgeCoreModule` | `create`, `doctor`, `upgrade`, `forge.agents.generate`, `scaffold`, `port.scaffold`, `skill.validate`, `skill.list`, `port.validate`, `profile.validate`, `dev`, `build`, `validate`, `pinned.validate`, `pinned.init`, `package.health`, `docs.archive`, `forge.autonomy.validate` | `os/core/` |
-| `forgeRfcModule` | `rfc.list`, `rfc.validate`, `rfc.create`, etc. | `os/rfc/` |
+| `forgeRfcModule` | `rfc.list`, `rfc.validate`, `rfc.create`, `rfc.verification.emit`, `rfc.verification.refresh`, etc. | `os/rfc/` |
 | `forgeWorkflowModule` | `workflow.lint`, `workflow.list`, `workflow.amend.list` | `os/workflow/` |
 | `forgeNamingModule` | `naming.convention.lint` | `os/naming/` |
 | `forgeCompassModule` | `compass.inventory`, `compass.validate`, `compass.summary.trim`, etc. (8 commands). All compass commands accept `--workpiece <path>` for scoping to a mission workpiece directory (RFC-0617). | `os/compass/` |
@@ -48,6 +48,8 @@ Skill packs MAY declare additional Compass contract blocks beyond the built-in `
 
 - **Verify `ecosystem.commit` output.** `ecosystem.commit` commits whatever is in the git index (staged files). If another agent staged files before your call, those files will be included in your commit instead of your own. After every `ecosystem.commit`, run `git show --stat HEAD` to verify the correct files were committed. If wrong files were committed, the missing files remain untracked/unstaged and must be committed separately.
 - **Wrap `loadForgeConfig` in try/catch in handlers that run in test workspaces.** `loadForgeConfig` throws when `forge.yaml` does not exist at the workspace root. Handlers that may be called from test workspaces without a `forge.yaml` (e.g. `runCompassValidation`) must guard the call with try/catch and skip pack-dependent logic when config is unavailable.
+- **Register new top-level directories in `NAMING_CONVENTION_IGNORED_TOP_LEVEL`.** When a new top-level directory appears in the repo (e.g. `.adr-locks`, `.devin`, `.forge`, `.rfc-locks`, `patches`, `storage`), add it to `NAMING_CONVENTION_IGNORED_TOP_LEVEL` in `os/naming/naming-convention.ts`. Otherwise `naming.convention.lint` reports "unknown top-level directory" errors.
+- **Add tool-generated/imported/historical dirs to `NAMING_CONVENTION_EXEMPT_DIRS`.** Directories containing tool-generated files (e.g. `docs/performance` with timestamp-based names), imported specification documents (e.g. `docs/specs` with `01-PBP-System-Specification.md`), and archived RFCs (e.g. `docs/rfcs/archive`) should be added to `NAMING_CONVENTION_EXEMPT_DIRS` in `os/naming/naming-convention.ts` to avoid false-positive kebab-case violations on files whose naming is controlled by external tools or conventions.
 
 ## Program packet control plane (RFC-0856)
 
@@ -151,6 +153,30 @@ YAML plain scalar values that **start with a backtick** (`` ` ``) must be double
 
 `rfc.implement.stamp` enforces RFC-IMP-02: every checked acceptance criterion (`- [x]`) MUST have an inline `(evidence: ...)` annotation. Parenthetical references without the `evidence:` keyword (e.g. `(promote.ts, 13 tests)`) do NOT satisfy the rule — the stamp fails with "checked criteria lack inline (evidence: ...) annotation". Always format as: `- [x] <criterion text> (evidence: <file paths, commands, or test counts>)`. Commit the annotated criteria before running `rfc.implement.stamp`.
 
+## RFC acceptance probes: criterion binding and coverage (RFC-0997)
+
+RFC-0997 binds acceptance probes to criteria via the `criterion: "AC-N"` field and adds three validation rules for post-cutoff RFCs (createdAt >= `2026-09-01`):
+
+- **V-35**: every probe SHALL declare `criterion` referencing an existing `AC-N` id. Missing, malformed, or dangling `criterion` is a blocking error.
+- **V-36**: every top-level checklist line (`- [ ]` / `- [x]`) in `## Acceptance criteria` SHALL start with a unique `AC-N:` identifier. Duplicate or missing identifiers are blocking errors.
+- **V-37**: checked criteria evidence SHALL resolve — `probe:AC-N` must reference a criterion with at least one bound probe; `test:<path>` and `<path>:<line>` must reference an existing file. **Evidence annotations MUST NOT contain em-dashes (—) or nested quotes** — the V-37 parser breaks on `test: path — "description"` and reports the file as non-existent. **The `<path>` token MUST be the file path only — no AC-N suffixes, no descriptions, no extra text after the path.** The parser treats everything after `test:` until end-of-parenthesis as the file path; `test: packages/forge/os/rfc/file.test.ts AC-1` is reported as non-existent because the parser looks for a file named `packages/forge/os/rfc/file.test.ts AC-1`. Use simple `(evidence: test:packages/forge/src/tests/file.test.ts)` without em-dashes, nested quotes, or AC-N suffixes. Discovered during RFC-0998 and RFC-0999.
+- **RFC-IMP-08**: `rfc.implement.stamp` blocks stamping for post-cutoff RFCs of kind `architecture`, `contract`, or `command` that declare zero acceptance probes. Policy and deprecation kinds are exempt.
+- **Coverage report**: `rfc.validate --json` and `rfc.acceptance.run` emit a non-blocking `coverage` block per post-cutoff RFC with `totalCriteria`, `probeBackedCriteria`, `coverageRatio`, `uncoveredCriteria`, `unboundProbes`.
+
+## RFC criteria content rules: phase separation, reject checklist, criterion versioning (RFC-1006)
+
+RFC-1006 adds five validation rules for post-cutoff RFCs and ADRs (createdAt >= `2026-09-03`):
+
+- **V-38**: `accepted`/`implemented` RFCs with unchecked `DR-N` items in `## Document readiness` section are blocking errors. Document readiness criteria (`DR-N`) are separated from system conformance criteria (`AC-N`).
+- **V-39**: acceptance criteria containing `SHALL ... and ...` joining two verb phrases are non-atomic — split into separate criteria.
+- **V-40**: acceptance criteria containing unbounded quantity triggers (`fast`, `scalable`, `low latency`, etc.) are blocking errors — state a specific number.
+- **V-41**: acceptance criteria containing weasel verbs (`handle gracefully`, `robust`, `works correctly`, etc.) are blocking errors — replace with a specific observable behavior.
+- **V-42**: malformed criterion supersession annotations (`> Superseded AC-N (YYYY-MM-DD): <reason>`) are blocking errors. Superseded criteria are excluded from the unchecked count.
+
+V-39..V-41 also apply to post-cutoff `implemented` ADRs via `adr.validate`. Pre-cutoff RFCs and ADRs are exempt. The reject checklist is conservative — it uses closed trigger lists, not semantic analysis. See `packages/forge/skills/fo/fo-idea-create-rfc/acceptance-criteria-standard.md` for the canonical authoring guide.
+
+- **Section extractors in `validate-rules.ts` MUST call `stripFencedCodeBlocks(body)` before regex-matching markdown sections.** RFC documents contain fenced code blocks with example headings and checklists. Without stripping, extractors like `extractDocumentReadinessSection` and `extractAcceptanceCriteriaSection` match headings inside code blocks, producing false-positive validation errors (e.g. V-38 reporting unchecked criteria from a code block example). The `stripFencedCodeBlocks` helper removes all ` ```...``` ` blocks before extraction. Any new section extractor added to `validate-rules.ts` must follow this pattern.
+
 ## Re-entrant werkstatt locks (RFC-0616)
 
 `acquireLock` and `releaseLock` in `os/werkstatt/handlers/lock.ts` are re-entrant by PID. When the same process re-acquires a lock it already holds, `acquireLock` increments the `depth` counter instead of throwing. `releaseLock` decrements `depth` and only deletes the lock file when `depth` reaches `1` or is `undefined`. The `depth` field is `.optional()` in `werkstattLockSchema` — old lock files without `depth` parse successfully and are treated as `depth=1` via `?? 1` fallbacks. Agents MUST NOT assume `acquireLock` always throws on an existing lock file — it only throws when a **different** live process holds the lock.

package/README.md

@@ -447,6 +447,99 @@ Forge provides the tools — `forge doctor`, `forge rfc.validate`, `forge skill.
 
 ---
 
+## Skill packs
+
+Skill packs let you create project-local skills under your own prefix, separate from Forge's portable `fo-` skills. This is useful when your project has domain-specific workflows that don't belong in Forge's portable skill set.
+
+### Declaring a pack
+
+Add a `skillPacks` entry to `forge.yaml`:
+
+```yaml
+skillPacks:
+  - prefix: wg
+    dir: packages/my-skills/skills
+```
+
+- `prefix` — short identifier used as a skill name prefix (e.g. `wg-deploy`, `wg-content-check`). Cannot be `fo` (reserved for Forge).
+- `dir` — directory containing your pack skills. Each skill is a subdirectory with a `SKILL.md` file.
+
+### Pack manifest (`forge.plugin.yaml`)
+
+Each pack directory must contain a `forge.plugin.yaml` manifest:
+
+```yaml
+id: my-pack
+version: 1.0.0
+```
+
+- `id` — kebab-case identifier for the pack.
+- `version` — semver version string.
+
+`forge init` auto-creates this manifest if it's missing. You can also create it manually.
+
+### Skill structure
+
+Skills follow the same structure as Forge skills:
+
+```
+packages/my-skills/skills/
+  forge.plugin.yaml          # pack manifest
+  wg-deploy/
+    SKILL.md                 # skill definition with frontmatter
+  wg-content-check/
+    SKILL.md
+```
+
+Each `SKILL.md` has standardized frontmatter (name, description, category, concerns, dependsOn) — the same format as Forge's `fo-` skills.
+
+### Validation commands
+
+```sh
+# Validate all pack manifests
+pnpm exec forge plugin.validate
+
+# List discovered packs
+pnpm exec forge plugin.discover
+
+# Validate individual skills (including pack skills)
+pnpm exec forge skill.validate
+
+# List all skills (pack skills annotated with pack:<prefix>)
+pnpm exec forge skill.list
+```
+
+### Extension points (Compass contract blocks)
+
+Packs can declare custom Compass contract blocks — source-file markers that `compass.validate` enforces. This lets your pack define its own `<MY_CONTRACT>` blocks with required tags:
+
+```yaml
+id: my-pack
+version: 1.0.0
+extensionPoints:
+  compass:
+    contract:
+      blocks:
+        - blockId: api-contract
+          requiredFor:
+            - "packages/my-pack/**/*.ts"
+          requiredTags:
+            - name: purpose
+              minWords: 3
+```
+
+`compass.validate` will emit `COMPASS-PLUGIN-01` (missing block), `COMPASS-PLUGIN-02` (missing required tag), and `COMPASS-PLUGIN-03` (tag below minWords) for files matching `requiredFor` that don't carry the block.
+
+### Rules
+
+- Pack skill names must start with the pack prefix (e.g. `wg-deploy` for prefix `wg`).
+- Pack skills cannot use the `fo-` prefix (reserved for Forge).
+- Pack skills cannot reference platform RFC/ADR ids or platform names.
+- Pack skills may depend on Forge skills, but Forge skills may not depend on pack skills (preserves portability).
+- If a pack skill name conflicts with a Forge skill name, the pack skill is skipped during sync.
+
+---
+
 ## Stack profiles
 
 A stack profile defines the project scaffold: directory structure, dependencies, CI config, and first workspace. Choose a profile with `--profile` when creating a new project.

package/README.uk.md

@@ -438,6 +438,99 @@ Forge надає інструменти — `forge doctor`, `forge rfc.validate`
 
 ---
 
+## Пакети навичок
+
+Пакети навичок (skill packs) дозволяють створювати навички проєкту під власним префіксом, окремо від портативних `fo-` навичок Forge. Це корисно, коли ваш проєкт має домен-специфічні робочі процеси, які не належать до портативного набору Forge.
+
+### Оголошення пакету
+
+Додайте запис `skillPacks` у `forge.yaml`:
+
+```yaml
+skillPacks:
+  - prefix: wg
+    dir: packages/my-skills/skills
+```
+
+- `prefix` — короткий ідентифікатор, що використовується як префікс імені навички (наприклад `wg-deploy`, `wg-content-check`). Не може бути `fo` (зарезервовано для Forge).
+- `dir` — директорія, що містить навички вашого пакету. Кожна навичка — піддиректорія з файлом `SKILL.md`.
+
+### Маніфест пакету (`forge.plugin.yaml`)
+
+Кожна директорія пакету повинна містити маніфест `forge.plugin.yaml`:
+
+```yaml
+id: my-pack
+version: 1.0.0
+```
+
+- `id` — ідентифікатор пакету в kebab-case.
+- `version` — рядок версії у форматі semver.
+
+`forge init` автоматично створює цей маніфест, якщо він відсутній. Ви також можете створити його вручну.
+
+### Структура навичок
+
+Навички мають ту саму структуру, що й навички Forge:
+
+```
+packages/my-skills/skills/
+  forge.plugin.yaml          # маніфест пакету
+  wg-deploy/
+    SKILL.md                 # визначення навички з frontmatter
+  wg-content-check/
+    SKILL.md
+```
+
+Кожен `SKILL.md` має стандартизований frontmatter (name, description, category, concerns, dependsOn) — той самий формат, що й у `fo-` навичок Forge.
+
+### Команди валідації
+
+```sh
+# Валідувати всі маніфести пакетів
+pnpm exec forge plugin.validate
+
+# Перелічити виявлені пакети
+pnpm exec forge plugin.discover
+
+# Валідувати окремі навички (включно з навичками пакетів)
+pnpm exec forge skill.validate
+
+# Перелічити всі навички (навички пакетів позначені pack:<prefix>)
+pnpm exec forge skill.list
+```
+
+### Точки розширення (блоки Compass-контракту)
+
+Пакети можуть оголошувати власні блоки Compass-контракту — маркери у вихідних файлах, які `compass.validate` перевіряє. Це дозволяє вашому пакету визначати власні `<MY_CONTRACT>` блоки з обов'язковими тегами:
+
+```yaml
+id: my-pack
+version: 1.0.0
+extensionPoints:
+  compass:
+    contract:
+      blocks:
+        - blockId: api-contract
+          requiredFor:
+            - "packages/my-pack/**/*.ts"
+          requiredTags:
+            - name: purpose
+              minWords: 3
+```
+
+`compass.validate` видаватиме `COMPASS-PLUGIN-01` (відсутній блок), `COMPASS-PLUGIN-02` (відсутній обов'язковий тег) та `COMPASS-PLUGIN-03` (тег з меншою кількістю слів) для файлів, що відповідають `requiredFor`, але не містять блок.
+
+### Правила
+
+- Імена навичок пакету повинні починатися з префіксу пакету (наприклад `wg-deploy` для префіксу `wg`).
+- Навички пакету не можуть використовувати префікс `fo-` (зарезервовано для Forge).
+- Навички пакету не можуть посилатися на ідентифікатори платформених RFC/ADR або назви платформи.
+- Навички пакету можуть залежати від навичок Forge, але навички Forge не можуть залежати від навичок пакету (зберігає портативність).
+- Якщо ім'я навички пакету конфліктує з іменем навички Forge, навичка пакету пропускається під час синхронізації.
+
+---
+
 ## Профілі стеку
 
 Профіль стеку визначає каркас проєкту: структуру директорій, залежності, конфігурацію CI та перший робочий простір. Оберіть профіль прапорцем `--profile` під час створення проєкту.

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

@@ -44,3 +44,11 @@ Forces and trade-offs that led to the decision: alternatives considered, constra
 ## Evolution
 
 How the decision may change: thresholds that trigger revisiting it, metrics to watch, and — for post-hoc ADRs — references to commits or PRs that implemented it.
+
+## Acceptance criteria
+
+<!-- Optional. If present, each criterion is a falsifiable claim about an observable artifact,
+     written in EARS form with a stable AC-N: identifier. See packages/forge/skills/fo/fo-idea-create-rfc/acceptance-criteria-standard.md (RFC-0996).
+     When this section exists and the ADR is implemented, adr.validate enforces AV-17: all items must be checked with (evidence: ...). -->
+
+- [ ] AC-1: THE <artifact> SHALL <observable property> (evidence: file: <path:line>)

package/os/adr/handlers/validate.test.ts

@@ -230,3 +230,206 @@ describe("ADR-DIR-01: directory structure convention (RFC-0722)", () => {
     }
   });
 });
+
+const ADR_BODY_WITH_CRITERIA = `
+# ADR-9998: Test ADR with criteria
+
+## Context
+
+Test context.
+
+## Decision
+
+Test decision.
+
+## Consequences
+
+Test consequences.
+
+## Evolution
+
+Test evolution.
+
+## Acceptance criteria
+
+- [ ] AC-1: THE system SHALL do X
+- [ ] AC-2: THE system SHALL do Y
+`;
+
+const ADR_BODY_WITH_CHECKED_CRITERIA_NO_EVIDENCE = `
+# ADR-9997: Test ADR with checked criteria no evidence
+
+## Context
+
+Test context.
+
+## Decision
+
+Test decision.
+
+## Consequences
+
+Test consequences.
+
+## Evolution
+
+Test evolution.
+
+## Acceptance criteria
+
+- [x] AC-1: THE system SHALL do X
+- [x] AC-2: THE system SHALL do Y
+`;
+
+const ADR_BODY_WITH_CHECKED_CRITERIA_WITH_EVIDENCE = `
+# ADR-9996: Test ADR with checked criteria with evidence
+
+## Context
+
+Test context.
+
+## Decision
+
+Test decision.
+
+## Consequences
+
+Test consequences.
+
+## Evolution
+
+Test evolution.
+
+## Acceptance criteria
+
+- [x] AC-1: THE system SHALL do X (evidence: test: src/test.test.ts)
+- [x] AC-2: THE system SHALL do Y (evidence: file: src/index.ts:42)
+`;
+
+function createAdrFilePostCutoff(
+  workspaceRoot: string,
+  id: string,
+  status: string,
+  body: string,
+  extraFm: Record<string, unknown> = {},
+): void {
+  const adrDir = join(workspaceRoot, "docs", "adrs");
+  mkdirSync(adrDir, { recursive: true });
+  const slug = id.toLowerCase();
+  const fm = [
+    "---",
+    `id: ${id}`,
+    `title: "Test ADR"`,
+    `status: ${status}`,
+    `scope: package`,
+    `decider: human:test`,
+    `createdAt: 2026-09-15`,
+    `updatedAt: 2026-09-15`,
+    ...Object.entries(extraFm).map(([k, v]) => `${k}: ${v}`),
+    "---",
+    "",
+    body,
+  ].join("\n");
+  writeFileSync(join(adrDir, `${slug}-test.md`), fm);
+}
+
+describe("AV-17: acceptance criteria completeness for implemented post-cutoff ADRs (RFC-0996)", () => {
+  test("AC-6: post-cutoff implemented ADR with unchecked criteria → AV-17 error", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "av17-unchecked-"));
+    try {
+      createAdrFilePostCutoff(dir, "ADR-9998", "implemented", ADR_BODY_WITH_CRITERIA, {
+        implementedAt: "2026-09-16",
+      });
+      const violations = await runValidate(dir, "ADR-9998");
+      const av17 = filterRule(violations, "AV-17");
+      expect(av17).toHaveLength(1);
+      expect(av17[0]!.severity).toBe("error");
+      expect(av17[0]!.message).toContain("2 unchecked acceptance criteria");
+      expect(av17[0]!.message).toContain("implemented");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("AC-7: post-cutoff implemented ADR with checked criteria but no evidence → AV-17 error", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "av17-noevidence-"));
+    try {
+      createAdrFilePostCutoff(
+        dir,
+        "ADR-9997",
+        "implemented",
+        ADR_BODY_WITH_CHECKED_CRITERIA_NO_EVIDENCE,
+        {
+          implementedAt: "2026-09-16",
+        },
+      );
+      const violations = await runValidate(dir, "ADR-9997");
+      const av17 = filterRule(violations, "AV-17");
+      expect(av17).toHaveLength(2);
+      expect(av17.every((v) => v.severity === "error")).toBe(true);
+      expect(av17.every((v) => v.message.includes("without (evidence: ...)"))).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("AC-8a: pre-cutoff implemented ADR with unchecked criteria → no AV-17", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "av17-precutoff-"));
+    try {
+      createAdrFile(dir, "ADR-9998", "implemented", ADR_BODY_WITH_CRITERIA, {
+        implementedAt: "2026-01-15",
+      });
+      const violations = await runValidate(dir, "ADR-9998");
+      const av17 = filterRule(violations, "AV-17");
+      expect(av17).toHaveLength(0);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("AC-8b: post-cutoff implemented ADR without criteria section → no AV-17", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "av17-nosection-"));
+    try {
+      createAdrFilePostCutoff(dir, "ADR-9999", "implemented", ADR_BODY, {
+        implementedAt: "2026-09-16",
+      });
+      const violations = await runValidate(dir, "ADR-9999");
+      const av17 = filterRule(violations, "AV-17");
+      expect(av17).toHaveLength(0);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("AC-8c: post-cutoff accepted (not implemented) ADR with unchecked criteria → no AV-17", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "av17-notimplemented-"));
+    try {
+      createAdrFilePostCutoff(dir, "ADR-9998", "accepted", ADR_BODY_WITH_CRITERIA);
+      const violations = await runValidate(dir, "ADR-9998");
+      const av17 = filterRule(violations, "AV-17");
+      expect(av17).toHaveLength(0);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("post-cutoff implemented ADR with all criteria checked and evidence → no AV-17", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "av17-clean-"));
+    try {
+      createAdrFilePostCutoff(
+        dir,
+        "ADR-9996",
+        "implemented",
+        ADR_BODY_WITH_CHECKED_CRITERIA_WITH_EVIDENCE,
+        {
+          implementedAt: "2026-09-16",
+        },
+      );
+      const violations = await runValidate(dir, "ADR-9996");
+      const av17 = filterRule(violations, "AV-17");
+      expect(av17).toHaveLength(0);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/os/adr/handlers/validate.ts

@@ -35,8 +35,10 @@ import {
   ADR_REQUIRED_SECTIONS,
   ADR_SCOPES,
   ADR_STATUSES,
+  ADR_ACCEPTANCE_CRITERIA_CUTOFF,
 } from "../types.ts";
-import { RFC_DIR } from "../../rfc/types.ts";
+import { RFC_DIR, RFC_CRITERIA_CONTENT_CUTOFF } from "../../rfc/types.ts";
+import { evaluateAcceptanceCriteria } from "../../rfc/handlers/validate-rules.ts";
 
 async function loadRfcIds(workspaceRoot: string): Promise<Set<string>> {
   const rfcIds = new Set<string>();
@@ -426,6 +428,57 @@ async function validateSingleAdr(
       }
     }
   }
+
+  // AV-17: acceptance criteria completeness for implemented post-cutoff ADRs (RFC-0996)
+  if (status === "implemented" && createdAt >= ADR_ACCEPTANCE_CRITERIA_CUTOFF) {
+    const evaluation = evaluateAcceptanceCriteria(body);
+    if (evaluation.totalUnchecked > 0) {
+      addViolation(
+        adrId,
+        relFile,
+        "AV-17",
+        `${adrId} has ${evaluation.totalUnchecked} unchecked acceptance criteria in "## Acceptance criteria" section but status is "implemented".`,
+      );
+    }
+    for (const line of evaluation.checkedWithoutEvidence) {
+      const snippet = line.length > 80 ? line.slice(0, 77) + "..." : line;
+      addViolation(
+        adrId,
+        relFile,
+        "AV-17",
+        `${adrId} has checked criterion without (evidence: ...) annotation: "${snippet}".`,
+      );
+    }
+  }
+
+  // V-39..V-41: reject checklist for post-cutoff implemented ADRs (RFC-1006)
+  if (status === "implemented" && createdAt >= RFC_CRITERIA_CONTENT_CUTOFF) {
+    const evaluation = evaluateAcceptanceCriteria(body);
+    for (const v of evaluation.nonAtomicViolations) {
+      addViolation(
+        adrId,
+        relFile,
+        "V-39",
+        `${adrId} acceptance criterion ${v.acId} is non-atomic (contains "and" joining two behaviors): "${v.line}". Split into separate criteria.`,
+      );
+    }
+    for (const v of evaluation.unboundedQuantityViolations) {
+      addViolation(
+        adrId,
+        relFile,
+        "V-40",
+        `${adrId} acceptance criterion ${v.acId} contains unbounded quantity "${v.trigger}": state a specific number or reference the decision that will set it.`,
+      );
+    }
+    for (const v of evaluation.weaselVerbViolations) {
+      addViolation(
+        adrId,
+        relFile,
+        "V-41",
+        `${adrId} acceptance criterion ${v.acId} contains weasel verb "${v.trigger}": replace with a specific observable behavior.`,
+      );
+    }
+  }
 }
 
 function execGitLog(workspaceRoot: string, args: string[]): Promise<string> {

package/os/adr/types.ts

@@ -16,6 +16,7 @@ statuses, scopes, frontmatter shape, validation results, and list output.
   <item>Post-refactor hardening: document that an ADR may be superseded by a broader RFC.</item>
   <item>RFC-0521: migrated from packages/os/site-kernel/src/adr/ to packages/forge/os/adr/.</item>
   <item>RFC-0727: add AdrImplementStamp types for atomic ADR status transition.</item>
+  <item>RFC-0996: add AV-17 acceptance criteria completeness check for implemented post-cutoff ADRs.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -103,6 +104,12 @@ export const ADR_REQUIRED_SECTIONS = [
   "Evolution",
 ] as const;
 
+/**
+ * RFC-0996: cutoff date for AV-17 (acceptance criteria completeness on implemented ADRs).
+ * ADRs created on or after this date are subject to AV-17. Pre-cutoff ADRs are exempt.
+ */
+export const ADR_ACCEPTANCE_CRITERIA_CUTOFF = "2026-09-01";
+
 export const ADR_KNOWN_KEYS: readonly string[] = [
   "id",
   "title",

package/os/compass/handlers/compass-inventory-handler.ts

@@ -48,9 +48,12 @@ function extractBlockContentForPlugin(source: string, tagName: string): string |
 
 const INVENTORY_OUTPUT_PATH = "docs/compass-inventory.xml";
 
-function getExpectedCommentSyntax(filePath: string): "block" | "hash" | "semicolon" | null {
+function getExpectedCommentSyntax(
+  filePath: string,
+): "block" | "hash" | "semicolon" | "html" | null {
   if (filePath.endsWith(".gd")) return "hash";
   if (filePath.endsWith(".tscn") || filePath.endsWith(".tres")) return "semicolon";
+  if (filePath.endsWith(".md")) return "html";
   if (
     filePath.endsWith(".ts") ||
     filePath.endsWith(".tsx") ||
@@ -96,6 +99,13 @@ function checkCommentSyntax(source: string, filePath: string): string | null {
         }
       }
     }
+  } else if (syntax === "html") {
+    const blockStart = source.indexOf("<!--");
+    const blockEnd = source.lastIndexOf("-->");
+    const tagPos = source.indexOf("<MODULE_CONTRACT>");
+    if (blockStart === -1 || blockEnd === -1 || blockStart > tagPos || tagPos > blockEnd) {
+      return "MODULE_CONTRACT must be inside a <!-- ... --> HTML comment for .md files";
+    }
   }
   return null;
 }

package/os/compass/handlers/compass-inventory.ts

@@ -15,6 +15,7 @@ for Compass source-file inventory.</purpose>
   <item>Post-refactor hardening: detect nested packages/os workspaces before deriving Compass layer and workspace name.</item>
   <item>RFC-0556: moved canonical implementation from @warpgogol/site-kernel to @warpgogol/forge for autonomous mode.</item>
   <item>Game extensions: added .cs, .tscn, .tres, .gd to SOURCE_EXTENSIONS; createCompassInventoryEntries now reads forge.yaml compass.fileExtensions at runtime and merges with hardcoded set.</item>
+  <item>Added .md to SOURCE_EXTENSIONS for SKILL.md Compass coverage; detectAuthoringStatus excludes non-SKILL.md markdown files.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -58,6 +59,7 @@ const SOURCE_EXTENSIONS = new Set([
   ".tscn",
   ".tres",
   ".gd",
+  ".md",
 ]);
 const IGNORED_DIRECTORY_NAMES = new Set([
   ".git",
@@ -266,6 +268,7 @@ function detectLayer(relativePath: string): string {
   )
     return "test";
   if (relativePath.startsWith("src/")) return "source";
+  if (relativePath.endsWith("SKILL.md")) return "skill";
   return "other";
 }
 
@@ -386,6 +389,13 @@ function detectAuthoringStatus(
     };
   }
 
+  if (relativePath.endsWith(".md") && !relativePath.endsWith("SKILL.md")) {
+    return {
+      authoringStatus: "excluded",
+      exclusionReason: "non-skill-markdown",
+    };
+  }
+
   const isRootFile = !relativePath.includes("/");
   if (
     isRootFile &&