@izkac/forgekit 0.1.0

package/src/vendor-openspec-overlays.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/**
+ * Re-apply Forge overlays to vendor OpenSpec skills and opsx:apply commands.
+ *
+ *   forge overlay
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export function resolveOverlayDir() {
+  const fromEnv = process.env.FORGEKIT_ROOT
+    ? path.join(process.env.FORGEKIT_ROOT, 'packages', 'cli', 'src', 'openspec-overlays')
+    : null;
+  const nextToSrc = path.join(__dirname, 'openspec-overlays');
+  for (const c of [fromEnv, nextToSrc].filter(Boolean)) {
+    if (c && fs.existsSync(c)) return c;
+  }
+  throw new Error('openspec-overlays directory not found');
+}
+
+const OVERLAY_START = '<!-- forgekit:openspec-overlay:start -->';
+const OVERLAY_END = '<!-- forgekit:openspec-overlay:end -->';
+const LEGACY_START = '<!-- janus-forge:openspec-overlay:start -->';
+const LEGACY_END = '<!-- janus-forge:openspec-overlay:end -->';
+const STEP_MARKER = 'REQUIRED (Forge):';
+const LEGACY_STEP_MARKER = 'REQUIRED (Janus Forge):';
+
+const AGENT_PATHS = {
+  cursor: {
+    skillRoot: '.cursor/skills/forge',
+    opsxApply: '.cursor/commands/opsx-apply.md',
+    applySkill: '.cursor/skills/openspec-apply-change/SKILL.md',
+  },
+  claude: {
+    skillRoot: '.claude/skills/forge',
+    opsxApply: '.claude/commands/opsx/apply.md',
+    applySkill: '.claude/skills/openspec-apply-change/SKILL.md',
+  },
+  codex: {
+    skillRoot: '.codex/skills/forge',
+    opsxApply: null,
+    applySkill: '.codex/skills/openspec-apply-change/SKILL.md',
+  },
+};
+
+function readOverlay(overlayDir, name) {
+  return fs.readFileSync(path.join(overlayDir, name), 'utf8');
+}
+
+export function renderOverlay(template, agentKey) {
+  const root = AGENT_PATHS[agentKey].skillRoot;
+  return template
+    .replaceAll('{{PHASES_IMPLEMENT}}', `${root}/phases/implement.md`)
+    .replaceAll('{{PHASES_VERIFY}}', `${root}/phases/verify.md`)
+    .replaceAll('{{PHASES_REVIEW}}', `${root}/phases/review.md`)
+    .replaceAll('{{SKILL_ROOT}}', root);
+}
+
+export function stripOverlayBlock(content) {
+  let out = content;
+  for (const [start, end] of [
+    [OVERLAY_START, OVERLAY_END],
+    [LEGACY_START, LEGACY_END],
+  ]) {
+    const blockRe = new RegExp(
+      `(\\r?\\n---\\r?\\n\\r?\\n)?${escapeRegExp(start)}[\\s\\S]*?${escapeRegExp(end)}\\r?\\n?`,
+      'g',
+    );
+    out = out.replace(blockRe, '\n');
+  }
+  return `${out.replace(/\n{3,}/g, '\n\n').trimEnd()}\n`;
+}
+
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function applySkillFooter(content, agentKey, overlayDir = resolveOverlayDir()) {
+  const footer = renderOverlay(
+    readOverlay(overlayDir, 'openspec-apply-change-footer.md'),
+    agentKey,
+  );
+  let out = stripOverlayBlock(content);
+  if (!out.endsWith('\n')) out += '\n';
+  return out + footer;
+}
+
+const STEP6_RE =
+  /(6\. \*\*Implement tasks \(loop until done or blocked\)\*\*\r?\n\r?\n)([\s\S]*?)(\r?\n\r?\n   \*\*Pause if:\*\*)/;
+
+export function patchOpsxApplyContent(content, agentKey, overlayDir = resolveOverlayDir()) {
+  if (!STEP6_RE.test(content)) {
+    return { content, status: 'no-match' };
+  }
+
+  const implementStep = renderOverlay(
+    readOverlay(overlayDir, 'opsx-apply-implement-step.md'),
+    agentKey,
+  );
+  let out = content.replace(STEP6_RE, `$1${implementStep}$3`);
+
+  const completionLine = renderOverlay(
+    readOverlay(overlayDir, 'opsx-apply-completion-step.md'),
+    agentKey,
+  ).trimEnd();
+
+  if (/   - If all done:.*\r?\n/.test(out)) {
+    out = out.replace(/   - If all done:.*\r?\n/, `${completionLine}\r\n`);
+  } else {
+    out = out.replace(
+      /(7\. \*\*On completion or pause, show status\*\*\r?\n\r?\n   Display:\r?\n)/,
+      `$1${completionLine}\r\n`,
+    );
+  }
+
+  const already =
+    content.includes(STEP_MARKER) || content.includes(LEGACY_STEP_MARKER);
+  const status = already ? 're-patched' : 'patched';
+  return { content: out, status };
+}
+
+function patchFile(relPath, transform, label) {
+  const abs = path.join(process.cwd(), relPath);
+  if (!fs.existsSync(abs)) {
+    process.stdout.write(`skip (missing): ${relPath}\n`);
+    return 'missing';
+  }
+  const before = fs.readFileSync(abs, 'utf8');
+  const after = transform(before);
+  if (after === before) {
+    process.stdout.write(`unchanged: ${relPath}\n`);
+    return 'unchanged';
+  }
+  fs.writeFileSync(abs, after, 'utf8');
+  process.stdout.write(`${label}: ${relPath}\n`);
+  return label;
+}
+
+function main() {
+  const overlayDir = resolveOverlayDir();
+
+  for (const [agentKey, paths] of Object.entries(AGENT_PATHS)) {
+    if (paths.opsxApply) {
+      patchFile(
+        paths.opsxApply,
+        (content) => patchOpsxApplyContent(content, agentKey, overlayDir).content,
+        'patched-opsx-apply',
+      );
+    }
+
+    patchFile(
+      paths.applySkill,
+      (content) => applySkillFooter(content, agentKey, overlayDir),
+      'patched-skill-footer',
+    );
+  }
+
+  process.stdout.write('\nDone. Forge-owned /forge:apply commands are not modified.\n');
+  process.stdout.write('After OpenSpec upgrade: forge overlay\n');
+}
+
+const isDirect =
+  process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url;
+
+if (isDirect) {
+  try {
+    main();
+  } catch (err) {
+    process.stderr.write(`${err.message || err}\n`);
+    process.exit(1);
+  }
+}

package/src/vendor-openspec-overlays.test.mjs

@@ -0,0 +1,62 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  applySkillFooter,
+  patchOpsxApplyContent,
+  stripOverlayBlock,
+} from './vendor-openspec-overlays.mjs';
+
+const VANILLA = `---
+name: test
+---
+
+6. **Implement tasks (loop until done or blocked)**
+
+   For each pending task:
+   - Show which task is being worked on
+   - Make the code changes required
+   - Keep changes minimal and focused
+   - Mark task complete in the tasks file: \`- [ ]\` → \`- [x]\`
+   - Continue to next task
+
+   **Pause if:**
+   - Task is unclear
+
+7. **On completion or pause, show status**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive
+`;
+
+test('patchOpsxApplyContent injects Forge implement step', () => {
+  const { content, status } = patchOpsxApplyContent(VANILLA, 'cursor');
+  assert.equal(status, 'patched');
+  assert.match(content, /REQUIRED \(Forge\):/);
+  assert.match(content, /\.cursor\/skills\/forge\/phases\/implement\.md/);
+  assert.match(content, /Dispatch \*\*implementer\*\* subagent/);
+  assert.doesNotMatch(content, /Make the code changes required/);
+});
+
+test('patchOpsxApplyContent is idempotent on re-run', () => {
+  const first = patchOpsxApplyContent(VANILLA, 'claude');
+  const second = patchOpsxApplyContent(first.content, 'claude');
+  assert.equal(second.status, 're-patched');
+  assert.match(second.content, /\.claude\/skills\/forge\/phases\/verify\.md/);
+});
+
+test('applySkillFooter adds overlay block once', () => {
+  const skill = '---\nname: openspec-apply-change\n---\n\nBody.\n';
+  const once = applySkillFooter(skill, 'codex');
+  assert.match(once, /forgekit:openspec-overlay:start/);
+  assert.match(once, /\/forge:apply/);
+  const twice = applySkillFooter(once, 'codex');
+  assert.equal((twice.match(/## Forge overlay/g) || []).length, 1);
+});
+
+test('stripOverlayBlock removes footer', () => {
+  const withFooter = applySkillFooter('body\n', 'cursor');
+  const stripped = stripOverlayBlock(withFooter);
+  assert.doesNotMatch(stripped, /forgekit:openspec-overlay/);
+});

package/vendor/skills/archive-to-adr/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: archive-to-adr
+description: >-
+  Create or update Architecture Decision Records (ADRs) from an archived OpenSpec
+  change. Fire after archive-shaped Bash completes (hooks wrap `openspec archive`
+  plus `mv` into dated `openspec/changes/archive/…`). Also use when sessionStart
+  reports pending archives, the user says `/archive-to-adr`, or they ask to
+  generate ADRs from an archive. Skip entirely when the project has ADRs disabled
+  (`.forge/config.json` → `adr.enabled: false`).
+disable-model-invocation: false
+---
+
+# Archive to ADR
+
+Turn a **completed and archived** OpenSpec change into one or more ADRs, following
+the project's decisions doc (scaffolded as `docs/decisions.md` by default via
+`forge init --adr`).
+
+This skill is **decoupled** from OpenSpec itself: archive hooks inject a reminder
+after successful archive-shaped shells; you judge whether an ADR is warranted.
+
+## Project config
+
+Read **`.forge/config.json`** at the repo root (written by `forge init` / optional
+`forgekit install` project scaffold):
+
+```json
+{
+  "adr": {
+    "enabled": true,
+    "dir": "docs/adr",
+    "decisionsDoc": "docs/decisions.md"
+  }
+}
+```
+
+| Field | Default | Meaning |
+|-------|---------|---------|
+| `adr.enabled` | `true` if file missing and `docs/adr/` exists; else follow install | When `false`, do **not** run this skill — no ADR, no "No ADR" stamp |
+| `adr.dir` | `docs/adr` | Directory for `NNNN-short-topic.md` + status `README.md` |
+| `adr.decisionsDoc` | sibling `decisions.md` of `adr.dir` | Process / template (when to write, format, hooks) |
+| `plan.engine` | `openspec` | `specs` = built-in engine; archives live under `<plan.dir>/changes/archive/` instead of `openspec/changes/archive/` |
+
+Below, **`{adrDir}`** and **`{decisionsDoc}`** mean those configured paths, and
+**`{archiveRoot}`** means `openspec/changes/archive` (OpenSpec engine) or
+`<plan.dir>/changes/archive` (specs engine, default `specs/changes/archive`).
+
+If `adr.enabled` is `false`, stop and tell the user ADRs are disabled for this project.
+
+## When to skip entirely (ADRs enabled)
+
+If the change is a bug fix, copy tweak, docs-only edit, or refactor with no
+architectural choice, **do not** create an ADR. Instead add this **single line**
+to the archived `proposal.md`:
+
+```text
+No ADR — non-architectural change
+```
+
+That silences the session-start pending-ADR backstop.
+
+## Input
+
+**Required:** the archive directory path, e.g.
+`{archiveRoot}/2026-05-15-payment-add-service/`.
+
+If the user only gives the change name, resolve it: list `{archiveRoot}/`
+and pick the matching dated folder.
+
+## Steps
+
+1. **Confirm ADRs are enabled** — read `.forge/config.json` as above.
+
+2. **Read the archived artifacts**
+   - `proposal.md` — Why, What Changes, Capabilities, Impact
+   - `design.md` — Context, Decisions, Risks, Migration
+   - `specs/**/*.md` in the archive (capability deltas)
+
+3. **Apply the ADR gate** (`{decisionsDoc}` § "When to write an ADR")
+   - Write an ADR when the change establishes/revises a **boundary**, picks one
+     approach over a **real** alternative, introduces a **constraint** future code
+     must respect, picks a **vendor/protocol/library** that is expensive to swap,
+     or codifies a **repo-wide** convention.
+   - Skip when it's purely implementation detail inside an existing decision.
+
+4. **Pick the next ADR number**
+   - List `{adrDir}/*.md` (four-digit prefix pattern `NNNN-*.md`).
+   - Use **the next sequential integer**; never reuse a number.
+   - If multiple distinct architectural decisions warrant separate ADRs in one
+     archive, create multiple files (`NNNN-…`, `NNNN+1-…`), each with one sharp decision.
+
+5. **Author the ADR file** at `{adrDir}/NNNN-short-topic.md` using the **exact
+   section structure** from `{decisionsDoc}`:
+   - Title: `# NNNN. <Short, decision-shaped title>`
+   - Frontmatter lines: **Status**, **Date**, **Area**, **Related** (link the
+     archive path, sibling ADRs)
+   - Body: Context, Decision, Alternatives considered, Consequences
+     (Positive / Negative / Neutral), References
+
+   Keep it terse (target ~80–200 lines total across all new ADRs for the change).
+   Link to the archive for forensic detail; don't paste the whole design.
+
+6. **Update the status index** `{adrDir}/README.md` — add or amend the table
+   row(s). If `README.md` is missing, create it with the table scaffold from
+   `{decisionsDoc}`.
+
+7. **Cross-reference from the archive**
+   - In `{archiveRoot}/<dated-change>/proposal.md`, add (or extend):
+
+   ```markdown
+   ## Decision record
+
+   This change is recorded as ADR-NNNN ({adrDir}/NNNN-short-topic.md).
+   ```
+
+   Use `ADR-NNNN` text so pending-ADR hooks (`grep 'ADR-[0-9]'`) recognize the link.
+
+8. **If capability specs were promoted** during archive: consider a one-line
+   pointer in the ADR **References** to `openspec/specs/<capability>/spec.md`
+   (optional but valuable).
+
+## Output
+
+- Paths of created/updated `{adrDir}/*.md`
+- Confirmation `{adrDir}/README.md` was updated
+- Confirmation the archived `proposal.md` now references `ADR-NNNN`
+- One-sentence summary per ADR written
+
+## Guardrails
+
+- Naming: **`NNNN-short-topic.md`**, not date-only filenames.
+- **Never** add `{adrDir}/` to `.cursorindexignore` (or equivalent ignore that
+  blocks agent retrieval).
+- Don't duplicate content that belongs only in OpenSpec — the archive remains
+  the verbose record; the ADR is the distilled "why."
+- If unsure whether to write an ADR, re-read the decisions gate; when still
+  ambiguous, ask the user once rather than inventing ceremony.
+
+## Relationship to hooks
+
+Project hooks (from `forge init --adr`) may:
+
+- Remind agents to run **archive-to-adr** after `openspec archive` / an archive
+  move (either engine)
+- At session start, list archives (both `openspec/changes/archive/` and
+  `specs/changes/archive/`) whose `proposal.md` lacks `ADR-*` **and** lacks
+  the `No ADR — non-architectural change` stamp
+
+Neither hook writes ADR files; **this skill** does.

package/vendor/skills/forge/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: forge
+description: >-
+  Forge — self-contained disciplined development workflow. Triage substantial work,
+  brainstorm, tracked plan (OpenSpec or built-in specs engine), subagent-driven TDD
+  implementation, verify, review, and finish.
+  Use when building features, fixing non-trivial bugs, or when the user invokes /forge.
+  Skip only when user says /forge:skip or work is trivial.
+disable-model-invocation: false
+---
+
+# Forge
+
+Spec-tracked development pipeline. Planning engine is per-project
+(`.forge/config.json` → `plan.engine`): **OpenSpec** (vendor CLI) or the
+**built-in specs engine** (`specs/changes/`, same layout). **Self-contained** —
+all workflow skills live under `./skills/` (vendored from Superpowers MIT; see
+[skills/NOTICE.md](./skills/NOTICE.md)).
+
+Full reference: forgekit `docs/forge.md` (shipped with this skill’s source repo).
+
+**Announce at start:** "Using Forge for this work." Include effective pace from
+`forge status` (e.g. `Pace: auto → brisk (…)`) — see [references/pace.md](./references/pace.md).
+
+## Instruction priority
+
+1. User explicit instructions (including `/forge:skip` and pace overrides)
+2. This skill + `./phases/`, `./references/`, and `./skills/`
+3. Project OpenSpec skills (`openspec-propose`, `openspec-apply-change`) — do not edit vendor copies (OpenSpec-engine projects only)
+
+## Pace (thoroughness)
+
+Checkout-local prefs control review/verify ceremony. Default pace is **`auto`**
+(resolves once per session from risk signals).
+
+```bash
+forge prefs                         # print effective pace (does NOT write a file)
+forge prefs brisk                   # WRITE .forge/preferences.local.json
+forge prefs --session-set lite
+forge models                        # print billing (does NOT write); set: included|metered
+forge doctor                        # plan-engine readiness (OpenSpec CLI or specs/ layout)
+```
+
+Honor [references/pace.md](./references/pace.md) in implement / verify / review.
+Hard floor: money/auth/contracts/migrations always get per-task review (even under `standard` mid-group / `brisk` / `lite`).
+Local overlays: forgekit `docs/forge.md` § Checkout-local overrides.
+
+## Bundled skills
+
+| Skill | Path | When |
+| ----- | ---- | ---- |
+| Brainstorming | [skills/brainstorming/SKILL.md](./skills/brainstorming/SKILL.md) | brainstorm phase |
+| TDD | [skills/test-driven-development/SKILL.md](./skills/test-driven-development/SKILL.md) | every implement task |
+| Subagent-driven dev | [skills/subagent-driven-development/SKILL.md](./skills/subagent-driven-development/SKILL.md) | implement phase |
+| Systematic debugging | [skills/systematic-debugging/SKILL.md](./skills/systematic-debugging/SKILL.md) | blockers / test failures |
+| Verification | [skills/verification-before-completion/SKILL.md](./skills/verification-before-completion/SKILL.md) | verify phase |
+| Code review | [skills/requesting-code-review/SKILL.md](./skills/requesting-code-review/SKILL.md) | review phase |
+
+## Step 0 — Triage (default)
+
+Before coding on any non-trivial request, run triage per
+[references/substantial-work.md](./references/substantial-work.md).
+
+- **Substantial (tracked-change-worthy)** → continue Forge (bootstrap session if needed)
+- **Too small for a tracked change** → execute directly, no session
+- **`/forge:skip`** → mark session `phase: skipped` if one exists; execute directly
+
+Bootstrap session when entering Forge:
+
+```bash
+forge new <kebab-slug>
+# optional: forge new <slug> --signal "add stripe refund"
+```
+
+`forge new` resolves pace (default `auto`) onto the session and runs the
+plan-engine doctor in warn-only mode (missing OpenSpec CLI does not block
+session creation; specs-engine projects skip the CLI check).
+
+Resume: read `.forge/active.json` → `forge status`.
+
+Update phase as you progress:
+
+```bash
+forge phase <phase> [--plan-type openspec|specs] [--openspec <change>]
+```
+
+Valid phases: `triage`, `brainstorm`, `plan`, `implement`, `verify`, `review`, `finish`, `done`, `skipped`.
+
+## Phase flow
+
+| Phase | Action |
+| ----- | ------ |
+| brainstorm | [phases/brainstorm.md](./phases/brainstorm.md) → **skills/brainstorming** |
+| plan | [references/plan-routing.md](./references/plan-routing.md) → engine from `.forge/config.json`: **OpenSpec** ([plan-openspec.md](./phases/plan-openspec.md)) or **specs** ([plan-specs.md](./phases/plan-specs.md)) |
+| implement | [phases/implement.md](./phases/implement.md) → **subagent-driven-development** + **TDD** |
+| verify | [phases/verify.md](./phases/verify.md) → **verification-before-completion** |
+| review | [phases/review.md](./phases/review.md) → **requesting-code-review** |
+| finish | [phases/finish.md](./phases/finish.md) |
+
+<HARD-GATE>
+Do NOT write implementation code during brainstorm or plan phases until the user approves the tracked change (OpenSpec or specs).
+</HARD-GATE>
+
+<HARD-GATE>
+Subagent dispatch: NEVER pass a model slug you picked yourself (including any from the host's model list). Run `forge resolve-model --tier <fast|standard|capable>` and honor its JSON — omit the `model` parameter when `omitModel` is true, else pass `model` exactly. Metered/API models only on explicit user request. This applies to retries and fallbacks too: if a dispatch fails, re-resolve — do not hand-pick a replacement slug.
+</HARD-GATE>
+
+## Session artefacts
+
+Layout: [references/forge-layout.md](./references/forge-layout.md)
+
+Testing: [references/test-strategy.md](./references/test-strategy.md) — tier 1 scoped TDD per task, tier 2 narrow evidence per task, tier 3 full workspace once at verify.
+
+## Guardrails (every phase)
+
+- No autonomous `git commit` / push unless the user explicitly asks
+- Tests required for behavior changes
+- Trace ecosystem consumers when contracts change
+- Honor `openspec/config.yaml` prefixes when the project uses them (OpenSpec engine)
+- **Runtime integrity** — [references/runtime-integrity.md](./references/runtime-integrity.md): **spine.json mandatory every change** (rows or `notApplicable` — not keyword-gated); no stubs / false success; capability specs beat narrow task wording; every claimed capability needs a named production caller; product-loop when spine has rows (or BLOCKED); deferred wiring only via `forge defer` — `forge phase done` mechanically refuses on `forge integrity-check` failures
+
+## Agent surfaces
+
+| Agent | Skill (after `forgekit install`) | Project wiring (`forge init`) |
+| ----- | ----------------------------- | ----------------------------- |
+| **Cursor** | `~/.cursor/skills/forge/` | commands, `forge.mdc`, SessionStart hook |
+| **Claude Code** | `~/.claude/skills/forge/` | commands, `forge.md`, SessionStart + prompt hooks |
+| **Codex CLI** | `~/.codex/skills/forge/` | thin rule |
+
+**Planning (all agents):** after brainstorm, proceed directly to the configured engine — no plan-mode prompt. See [references/plan-routing.md](./references/plan-routing.md). Hooks remind agents to run the propose flow when `planType` is unset.
+
+**Distribute:** edit `skills/forge/` in forgekit, then `forgekit install --skills forge --force` on each machine. The bundled skills are a maintained fork (see [skills/NOTICE.md](./skills/NOTICE.md)) — do not re-vendor from Superpowers.
+
+## Do not edit vendor OpenSpec skills
+
+OpenSpec vendor skills upgrade in place. Forge behaviour lives in this tree and forgekit `docs/forge.md`. Re-apply vendor patches with `forge overlay` after OpenSpec upgrades.

package/vendor/skills/forge/phases/brainstorm.md

@@ -0,0 +1,23 @@
+# Brainstorm phase
+
+Read and follow [../skills/brainstorming/SKILL.md](../skills/brainstorming/SKILL.md) in full.
+
+**Pace:** Honor `brainstorm.depth` from [../references/pace.md](../references/pace.md) / `forge status` — `full` (default skill), `short` (≤2–3 approaches), or `minimal` (confirm intent + one approach when design is obvious).
+
+## Terminal state
+
+After user approves the design:
+
+1. Save to `.forge/sessions/<id>/brainstorm/notes.md` and `decisions.md`
+2. Read [../references/plan-routing.md](../references/plan-routing.md) and **proceed to OpenSpec propose** — do not ask for a plan mode
+3. Follow [plan-openspec.md](./plan-openspec.md) — **not** implementation until OpenSpec artefacts are approved
+
+```bash
+forge phase brainstorm
+# after OpenSpec propose:
+forge phase plan --plan-type openspec --openspec <name>
+```
+
+<HARD-GATE>
+Do NOT invoke implement phase or write production code until OpenSpec plan phase completes and user approves.
+</HARD-GATE>

package/vendor/skills/forge/phases/finish.md

@@ -0,0 +1,87 @@
+# Finish phase
+
+Before marking done, integrity must pass (or the user must approve an incomplete finish):
+
+```bash
+forge integrity-check    # spine + deferrals + product-loop / BLOCKED
+forge score              # preview L2 scorecard (optional)
+forge phase done         # runs integrity checks + writes scorecard.md/json
+# escape hatch only with an honest reason:
+# forge phase done --allow-incomplete "E2E blocked: no Compose in this environment"
+```
+
+`forge phase done|finish` always writes `.forge/sessions/<id>/scorecard.md` (and
+`.json`) — an L2 grade of session artifacts. Answer the **human ship-check**
+questions in that file for platform/async work (L3). See [usage.md](../../../docs/usage.md)
+§ Session success.
+
+## OpenSpec path (`planType: openspec`)
+
+1. Confirm all tasks complete in `tasks.md`.
+2. User runs or approves `/opsx:archive` / `openspec archive`.
+3. **ADR follow-up (optional):** if `.forge/config.json` has `adr.enabled: true`
+   (or the project uses ADRs), follow the **`archive-to-adr`** skill using
+   `adr.dir` / `adr.decisionsDoc`. If ADRs are disabled, skip.
+4. End with **Suggested commit** block (display only — do not commit).
+
+```bash
+forge phase done
+forge cleanup
+```
+
+## Specs path (`planType: specs`)
+
+1. Confirm all tasks complete in `<specsDir>/changes/<name>/tasks.md`.
+2. **Archive** (with user approval) — prefer the CLI:
+
+   ```bash
+   forge change archive <name>
+   # → <specsDir>/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+   Or move manually:
+
+   ```bash
+   git mv <specsDir>/changes/<name> <specsDir>/changes/archive/<YYYY-MM-DD>-<name>
+   ```
+
+   (plain `mv` if the dir is untracked).
+3. **ADR follow-up (optional):** same rule as OpenSpec — if `adr.enabled`,
+   follow **`archive-to-adr`** on the archived change; otherwise skip.
+4. End with **Suggested commit** block (display only — do not commit).
+
+```bash
+forge phase done
+forge cleanup
+```
+
+## Throwaway path (`planType: throwaway`)
+
+1. Confirm all tasks in `plan.md` checked off.
+2. Summarize what shipped.
+3. Mark session done and cleanup:
+
+```bash
+forge phase done
+forge cleanup
+```
+
+## Direct path (`planType: direct`)
+
+1. Confirm implementation matches brainstorm `notes.md` / `decisions.md`.
+2. Summarize what shipped.
+3. Mark session done and cleanup:
+
+```bash
+forge phase done
+forge cleanup
+```
+
+## Skipped path (`/forge:skip`)
+
+Session already at `phase: skipped`. No finish steps.
+
+## Hand-off
+
+Leave implementation files staged/unstaged per user preference. Never commit unless
+explicitly asked (project git policy).