forge-workflow 0.0.9 → 0.1.0-beta.2

package/docs/reference/ADAPTERS.md

@@ -0,0 +1,128 @@
+# Forge Adapters
+
+Forge adapters normalize provider-specific surfaces behind Forge-owned contracts. The bundled adapters are reference implementations; Forge owns the contract and authority rules.
+
+Current public support is narrow: Beads is the reference issue adapter, and review-adapter scaffolding supports review adapters with a Greptile-shaped starter template. Other adapter kinds are roadmap or internal design work until implemented and tested.
+
+## Issue Adapters
+
+Issue adapters expose issue tracking operations without making Beads, GitHub, Linear, Jira, or another provider the Forge API. The bundled reference adapter is `BeadsIssueAdapter`.
+
+### Issue Contract
+
+An issue adapter has `kind: "issue"` and implements these methods:
+
+- `list(args, context)`: list issues from the provider/backend.
+- `read(args, context)`: read a single issue. The Beads adapter maps this to `bd show`.
+- `create(args, context)`: create an issue.
+- `update(args, context)`: update issue fields.
+- `close(args, context)`: close an issue.
+- `comment(args, context)`: add an issue comment. The Beads adapter maps this to `bd comments add`.
+- `mapStatus(status, context)`: map provider status into the requested target state.
+- `decideAuthority(change, context)`: return the Forge authority decision for a field change.
+
+### Issue Authority
+
+GitHub owns shared team-visible fields: GitHub identity, URL, title, body, state, assignees, labels, milestone, and remote update timestamps.
+
+Forge owns workflow and project context: Forge issue id, dependencies, parent/child links, workflow stages, acceptance criteria, progress notes, stage transitions, decisions, memory, outbound projection bookkeeping, and drift diagnostics.
+
+Beads is the local/reference issue adapter and cache backend. Cache fields are derived and may be rebuilt. Unknown field paths are rejected until the authority model explicitly assigns ownership.
+
+### Conflict Behavior
+
+During pull/import, GitHub-owned remote fields overwrite local materialized shared fields and differences are recorded as drift diagnostics. Forge-owned fields are preserved locally and are not overwritten by GitHub import. Cache fields are rebuilt from the authoritative inputs.
+
+### Issue Non-Scope
+
+Issue adapters do not implement team dashboard UI, ReviewAdapter internals, GitHub Projects board automation, or full comment/discussion import. GitHub issue import must use the existing `lib/issue-sync/import-primitives.js` reconciliation path rather than a separate import contract.
+
+## Review Adapters
+
+Forge review adapters normalize provider-specific review feedback into one contract used by review tooling and offline fixture tests.
+
+### Review Contract
+
+A review adapter has `kind: "review"` and implements these methods:
+
+- `fetchThreads(context)`: fetch provider review threads. Live adapters may use GitHub, REST, GraphQL, or a provider SDK.
+- `parse(payload, options)`: normalize provider payloads into review thread objects.
+- `reply(context)`: post a reply to a provider review comment.
+- `resolve(context)`: mark a provider review thread resolved.
+- `score(threads, context)`: score or classify parsed threads, usually by checking local commits or fixture data.
+
+Normalized thread shape:
+
+```js
+{
+  id: 'provider-thread-id',
+  commentId: 123,
+  file: 'lib/example.js',
+  line: 42,
+  body: 'review text',
+  author: 'review-bot',
+  isResolved: false,
+  raw: {}
+}
+```
+
+### Review Lifecycle
+
+1. `fetchThreads` obtains raw provider data for live review runs.
+2. `parse` filters and normalizes the provider data.
+3. `score` decides whether local work appears to address each parsed thread.
+4. `reply` posts the resolution explanation.
+5. `resolve` closes the provider thread after a reply is recorded.
+
+The bundled `GreptileReviewAdapter` is the compatibility reference. Existing Greptile shell commands keep their public command names while the shared matching behavior is routed through the adapter implementation.
+
+### Review Scaffold
+
+Create a local review adapter starter:
+
+```bash
+forge new adapter coderabbit --kind=review --template=greptile
+```
+
+The scaffold is written to:
+
+```text
+.forge/adapters/review/coderabbit.js
+```
+
+Only review adapters and the Greptile-shaped starter template are supported in this foundation PR.
+
+### Review Fixture Replay
+
+Run adapter parsing and scoring offline:
+
+```bash
+forge adapter test greptile --fixture=fixtures/greptile-review.json
+```
+
+Fixture shape:
+
+```json
+{
+  "input": {
+    "data": {
+      "repository": {
+        "pullRequest": {
+          "reviewThreads": {
+            "nodes": []
+          }
+        }
+      }
+    }
+  },
+  "expect": {
+    "threads": 0
+  }
+}
+```
+
+Fixture replay must not make network calls. Live provider calls belong in `fetchThreads`, `reply`, and `resolve`.
+
+### Review Non-Scope
+
+Review adapters do not implement issue tracking, GitHub issue sync, or the full v3 reference adapter template catalog.

package/docs/reference/AGENT_SKILL_PARITY.md

@@ -0,0 +1,175 @@
+# Agent Skill Parity
+
+Forge treats cross-agent skill compatibility as one canonical capability rendered into each harness's native activation surface.
+
+This page documents the W0 metadata fixture only. It is not the full Forge extension parity model.
+
+For Week 3 planning, see [Week 3 Runtime Capability Packs](../work/2026-04-28-skeleton-pivot/week-3-runtime-capability-packs.md). That plan defines replaceable workflow packs, on-demand skill loading through MCP, runtime-enforced required skill policies, and per-project workflow composition.
+
+## Supported Surfaces
+
+Forge supports Claude Code, Codex, Cursor, and Hermes. Hermes is a **CLI-consumed**
+harness: it reads Forge project state through `forge orient` / `forge recap` and
+ships the `hermes-forge` skill (`.hermes/skills`), rather than consuming generated
+rule/MCP/hook files. The W0 metadata fixture below proves the file-surface metadata
+for Claude Code, Cursor, and Codex; Hermes is modeled in the capability matrix
+(`lib/harness-capability-matrix.js`) as CLI-consumed.
+
+| Harness | Forge fixture path | Activation metadata | Proof status |
+| --- | --- | --- | --- |
+| Claude Code | `.claude/skills/<name>/SKILL.md` | `description` in `SKILL.md` frontmatter | Proven by metadata fixture |
+| Cursor | `.cursor/rules/<name>.mdc` | `description`, blank `globs`, `alwaysApply: false` | Proven by metadata fixture |
+| Codex CLI | `.codex/skills/<name>/SKILL.md` | `name` and `description` in `SKILL.md` frontmatter | Proven by metadata fixture and Forge packaging helper |
+| Hermes | `.hermes/skills/<name>/SKILL.md` | `name` and `description` in `SKILL.md` frontmatter | CLI-consumed (forge orient/recap); not part of the W0 file-metadata fixture |
+
+The shared rule is: keep the skill name, description, and task body canonical, then generate the smallest native wrapper each harness needs.
+
+For Codex, this W0 fixture validates Forge's repository packaging surface (`.codex/skills`) plus the metadata needed for installed Codex skills. Codex's documented repo-scope discovery path is `.agents/skills` (scanned cwd → repo root); Forge now generates that mirror at setup and commits it, so a teammate who clones the repo WITHOUT running `forge setup` still gets Forge skills/stages auto-discovered.
+
+Cursor rules are included here because `forge-2si5` explicitly asked for `.cursor/rules/*.mdc` evidence. They are not the final Cursor skill target. The broader parity model must treat Cursor Agent Skills as the primary on-demand workflow surface and Cursor rules as the always-on or scoped-policy surface.
+
+## Required Follow-Up: Skills-First Stage Graph
+
+Tracked as `forge-wj36`.
+
+This follow-up now has a machine-readable contract in `lib/harness-capability-matrix.js`.
+Generate the current evidence artifact with:
+
+```bash
+node scripts/spikes/harness-capability-matrix.js
+```
+
+The output is JSON with three top-level contracts:
+
+- `harnesses[]`: Claude, Cursor, Codex, and Hermes capability support across instructions, skills, rules, MCP, hooks, commands, agents/subagents, stages, Beads, typed memory, patch overrides, marketplace trust, extension packs, and the native safety surfaces (tool permissions, AI read/index ignore boundary, execution sandbox).
+- `stageGraph`: canonical Forge workflow stages as skills-first super skills with addressable subskills, plus utility skills such as `status` outside workflow transitions.
+- `rendererContract`: the evidence a renderer must provide before Forge emits broad harness files.
+
+Forge stage parity is skills-first across all harnesses. Claude stage skills have
+**no command shim** — the legacy `.claude/commands/` surface was removed (A0d), so
+the stage skill is the authority. Cursor stage skill files are **generated** by
+Forge, though live auto-invocation is not yet proven. Hermes is CLI-consumed and
+reads the stage graph through `forge orient` / `forge recap` (no per-stage file).
+
+| Forge stage | Canonical surface | Claude render | Cursor render | Codex render |
+| --- | --- | --- | --- | --- |
+| `plan` | super skill with phases | `.claude/skills/plan/SKILL.md` | `.cursor/skills/plan/SKILL.md` (generated) | `.codex/skills/plan/SKILL.md` |
+| `dev` | super skill with TDD subskills | `.claude/skills/dev/SKILL.md` | `.cursor/skills/dev/SKILL.md` (generated) | `.codex/skills/dev/SKILL.md` |
+| `validate` | super skill with check subskills | `.claude/skills/validate/SKILL.md` | `.cursor/skills/validate/SKILL.md` (generated) | `.codex/skills/validate/SKILL.md` |
+| `ship` | super skill with PR subskills | `.claude/skills/ship/SKILL.md` | `.cursor/skills/ship/SKILL.md` (generated) | `.codex/skills/ship/SKILL.md` |
+| `review` | super skill with feedback subskills | `.claude/skills/review/SKILL.md` | `.cursor/skills/review/SKILL.md` (generated) | `.codex/skills/review/SKILL.md` |
+| `verify` | super skill with post-merge subskills | `.claude/skills/verify/SKILL.md` | `.cursor/skills/verify/SKILL.md` (generated) | `.codex/skills/verify/SKILL.md` |
+
+Pre-merge is not a skill or a workflow stage — it is a documentation-and-handoff gate embedded in the `ship` and `review` skills, so it has no parity row.
+
+`status` remains a utility skill, not a workflow stage. The stage graph exposes it in `utilitySkills[]` so renderers can still generate status affordances without adding invalid workflow transitions.
+
+The legacy `.claude/commands/` surface was removed (A0d): the canonical workflow lives in stage skills and subskills, and the stage skill — not a command shim — is the workflow authority.
+
+The super-skill structure should follow the same pattern as rich local skills such as `impeccable`: one top-level skill handles routing and context, while individual subskills or references handle specific phases. For Forge, that means examples like:
+
+```text
+plan/
+  SKILL.md
+  phases/
+    intent_capture/SKILL.md
+    research/SKILL.md
+    critics/SKILL.md
+    synthesis/SKILL.md
+    final_lock/SKILL.md
+```
+
+## Full Extension Parity Scope
+
+The full Forge extension parity model must cover more than skills:
+
+| Capability | Canonical Forge source | Claude | Cursor | Codex | Required evidence |
+| --- | --- | --- | --- | --- | --- |
+| Project instructions | structured `AGENTS.md` sections | `CLAUDE.md` shim or generated file | `AGENTS.md` (native) + `.cursor/rules/*.mdc` for scoped policy | `AGENTS.md` | semantic section comparison |
+| Skills/playbooks | agentskills.io-compatible `SKILL.md` | `.claude/skills` | `.cursor/skills` | `.codex/skills` packaging source (global `$CODEX_HOME` install) + committed `.agents/skills` repo-local discovery | generated file and trigger metadata |
+| Rules/policies | Forge rule manifest (`rules/<name>.md`) | `AGENTS.md` instruction projection (no always-on `.claude/rules/*` policy bloat) | `.cursor/rules/*.mdc` (rendered from `rules/`) | `AGENTS.md` section | rule target and unsupported-surface notes |
+| MCP tools/resources | Forge MCP manifest | Claude MCP config | `.cursor/mcp.json` | Codex MCP config | config render and server probe |
+| Hooks | Forge hook manifest | Claude hook adapter if supported | unsupported unless verified | Codex hook adapter if supported | supported/unsupported matrix |
+| Commands | Forge stage-skill manifest | `.claude/skills/<stage>` (legacy `.claude/commands` removed in A0d) | stage skills if supported | CLI docs or skill backstop | stage skill is the authority |
+| Agents/subagents | Forge agent role spec | Claude subagents | Cursor agent/subagent config if supported | Codex skill/agent backstop | role mapping or known issue |
+| Marketplace/extensions | `extension.yaml` plus lock metadata | plugin/skills/commands/hooks | skills/rules/`.cursor/mcp.json` config | skills/MCP/hooks | lockfile, SHA, trust, generated targets |
+
+The machine-readable matrix intentionally separates similar-looking surfaces:
+
+- Skills are on-demand workflows: `.claude/skills/<skill>/SKILL.md`, `.cursor/skills/<skill>/SKILL.md`, and for Codex the `.agents/skills/<skill>/SKILL.md` repo-local discovery mirror (Codex scans it cwd → repo root). All are generated from the canonical `skills/` source; the `.claude`/`.cursor`/`.codex`/`.hermes` mirrors are gitignored and populated at `forge setup`, while `.agents/skills` is committed (kept byte-identical to `skills/` by a pre-commit hook + drift gate) so a fresh clone gets discovery without setup. The global `$CODEX_HOME/skills` install is likewise generated from `skills/`; no committed `.codex/skills` mirror is kept.
+- Rules are policy/context projections rendered from one canonical `rules/<name>.md` source: only Cursor has a first-class native rule surface (`.cursor/rules/<rule>.mdc`); Claude, Codex, and Hermes receive the same policy through their `AGENTS.md` instruction projection (adding always-on `.claude/rules/*` policy files would triple-deliver the same context as token bloat).
+- Commands are removed, not shims: the legacy `.claude/commands/` and `.cursor/commands/` surfaces were removed in A0d. The canonical workflow lives in stage skills (`.claude/skills/<stage>`, `.codex/skills/<stage>`); Codex/Hermes fall back to the stage skill, not a command file.
+- MCP is config plumbing: each harness gets native MCP config only when the matrix records a target path and probe evidence.
+- Hooks are lifecycle adapters: Claude and Codex have native hook targets; Cursor remains a known issue until a hook surface is proven.
+- Distribution is not a skill directory dump: Codex can use plugins and marketplaces; Forge extension packs must carry lock/trust metadata before installation.
+
+No broad renderer should be added until its capability has a matrix entry, target path contract, activation metadata contract, machine-readable evidence, and a known-issue record for any unproven harness.
+
+## External Compatibility Pattern
+
+The current ecosystem pattern is a canonical payload with native harness renderers:
+
+- Claude Code documents skills as `SKILL.md` files whose `description` controls automatic loading, and notes that commands and skills can both expose slash affordances.
+- Cursor documents `.cursor/rules/*.mdc` as persistent scoped context with `description`, `globs`, and `alwaysApply`; Cursor skills are treated by Forge as the on-demand workflow target, while rules remain the policy target.
+- Codex documents skills as reusable workflow packages under `.agents/skills` for repository scope (checked in for the team, scanned cwd → repo root), uses description-based implicit invocation, and uses plugins/marketplaces to distribute reusable skills, MCP servers, hooks, and apps. Forge emits `.codex/skills` packages for the global `$CODEX_HOME` install and now also generates + commits the repo-local `.agents/skills` mirror at setup.
+- AGENTS.md remains the shared instruction projection for agents that read repository instructions directly.
+
+Forge adopts that pattern by keeping one canonical Forge capability and rendering the smallest verified native wrapper per harness. It does not duplicate every feature blindly into every directory.
+
+Week 3 expands that into a runtime capability registry. The registry must cover skills, commands, hooks, MCPs, ACPs, books/docs, agents, memory policies, protected paths, marketplace metadata, and workflow stages. Harness files should be generated projections from the active project workflow, not the authority.
+
+Invocation policy is part of parity. Required skills must be loaded by Forge runtime at stage or gate boundaries; expensive, dangerous, or long-running skills must remain gated, hidden, or execution-only until the user or runtime explicitly requests them.
+
+Parity is not accepted until an evaluator cross-checks the resolved workflow graph against generated harness projections and either passes, blocks, or records a known issue with evidence. The evaluator must also propose minimal repair diffs when a customer-installed workflow pack changes the active stage implementation.
+
+## Evidence Command
+
+Run the W0 parity fixture from the repository root:
+
+```bash
+node scripts/spikes/skill-auto-invoke-parity.js --json
+```
+
+The JSON output includes:
+
+- `harnesses[].passed`
+- `harnesses[].target`
+- `harnesses[].sourceLabel`
+- `sources[]`
+- `proofBoundary`
+- `knownIssues[]`
+
+Run the broader capability matrix evidence from the repository root:
+
+```bash
+node scripts/spikes/harness-capability-matrix.js
+```
+
+The JSON output includes:
+
+- `harnesses[].capabilities`
+- `stageGraph.stages[].subskills`
+- `stageGraph.stages[].renderTargets`
+- `rendererContract.rendererFamilies`
+- `sources[]`
+
+## Proof Boundary
+
+This fixture proves deterministic metadata-surface parity. It does not launch closed-source agent sessions or claim that a live model selected a skill in a proprietary runtime. For Codex specifically, it validates the Forge canonical skill source and metadata (and the committed `.agents/skills` repo-local discovery mirror), not live auto-invocation inside the Codex runtime.
+
+If a future release needs live invocation proof, add a separate transcript-producing eval for Claude Code, Cursor, and Codex and keep this fixture as the fast CI gate.
+
+## Known Issues
+
+No harness-specific metadata issue is known for this fixture. Live proprietary-agent auto-invocation is intentionally outside this deterministic test and is reported in `proofBoundary`.
+
+Known gaps intentionally left for follow-up. Tier-2 work is tracked under kernel epic `90f2f631` (Cross-agent parity Tier 2):
+
+- Cursor Agent Skill files ARE generated by Forge at setup (`.cursor/skills`), so the matrix marks Cursor skills/stages `native`; live auto-invocation is simply not asserted by the W0 metadata fixture. `.cursor/rules` remains the policy target.
+- Claude stage distribution is skills-first: the legacy `.claude/commands/` surface was removed (A0d) and the stage skill (`.claude/skills/<stage>`) is the authority — the stage graph no longer emits a command shim.
+- **Hooks (`988ae187`)**: NO harness-native hook file is rendered for ANY harness — all lifecycle enforcement is delivered via Lefthook git hooks. The matrix marks Claude/Codex hooks `contract-only` and Cursor hooks `not-delivered` (Cursor 1.7+ exposes `.cursor/hooks.json`, not yet rendered). Native hook renderers are the deliverable.
+- **Agents/subagents (`802aa4d8`)**: the whole domain is unimplemented — no renderer, manifest, wiring, or tests for any harness. The matrix marks every harness `not-delivered`/`unsupported`. A subagent renderer is the deliverable.
+- **Typed memory (`dce9da46`)**: typed memory is WRITE-ONLY (`insights.js`); no generator projects a memory section into any instruction/rule file. All four typedMemory rows are marked `not-delivered`. A memory-projection renderer is the deliverable.
+- **Codex paths (`55dfeccf`)**: `.codex/skills` is a setup-generated, gitignored local mirror; skills install to the global `$CODEX_HOME/skills`, generated at setup from the canonical `skills/` source. Codex's repo-local discovery path `.agents/skills` is generated from `skills/` and committed (kept byte-identical by a pre-commit hook + drift gate) so a fresh clone gets discovery without `forge setup` (this closes the skills/stages half of `55dfeccf`). Codex MCP remains global-config-only (`$CODEX_HOME/config.toml`), so `(mcp, codex)` is still `not-delivered` at project setup.
+- **Safety domains (`1e68255c`)**: the native safety surfaces are now modeled as three capability rows (`permissions`, `ignore`, `sandbox`) rendered by the `safety` renderer family. `forge setup` auto-writes safe project-local defaults via the tested `lib/safety-config-renderer.js`: Claude tool permissions (`.claude/settings.json` `permissions` — allow the forge/dev workflow, deny `rm -rf`/force-push/secret reads, ask for history-rewrites) and Cursor `.cursorignore` (secrets/`.env`/`node_modules`/build artifacts). Both use read → merge → write, preserving user entries and backing up an unparseable file rather than clobbering it. Defaults are ON but opt-out-able with `FORGE_SKIP_SAFETY_DEFAULTS`. The Claude `ignore` row is `projection` (its read boundary is delivered as `permissions.deny Read(...)` rules; Claude has no `.claudeignore`). **Global-scope-deferred**: Codex `permissions`/`sandbox` are `not-delivered` — `approval_policy`/`sandbox_mode` live in `config.toml` but a project-local `.codex/config.toml` is honored only when the project is trusted in the GLOBAL `$CODEX_HOME/config.toml` (`projects.<path>.trust_level`), which Forge cannot grant during project-local setup (matches the Codex MCP finding, `#311`). Cursor `permissions` and Hermes safety surfaces are `unsupported` (IDE/global-only and CLI-consumed respectively).
+- MCP is now auto-wired project-local for both Claude (`.mcp.json`) and Cursor (`.cursor/mcp.json`) via the tested `lib/mcp-config-renderer.js`. Beads/patch-override state, marketplace trust, and extension packs remain as the matrix records them.

package/docs/reference/COMMANDS.md

@@ -0,0 +1,205 @@
+# Command Reference
+
+This reference documents commands verified against the current package and CLI surfaces. Stage names beginning with `/` are agent workflow stages, not automatically standalone `forge` CLI commands.
+
+For stage skills, command projections, and the skills-first roadmap, see [Skills and command projections](SKILLS.md) and [Workflow templates](../guides/WORKFLOW_TEMPLATES.md).
+
+## Package Entrypoints
+
+The package exposes:
+
+```text
+forge
+forge-workflow
+forge-preflight
+```
+
+Use `bunx forge ...` for first-run examples. Bare `forge ...` works when the package bin is available on PATH. Command-specific `--help` output is still uneven in the current CLI, so treat this reference as the canonical command list for v0.0.11 docs.
+
+## Setup And Adoption
+
+```bash
+forge init [--profile minimal|standard|full] [--classification critical|standard|refactor] [--harness claude,cursor,codex] [--yes] [--force] [--dry-run]
+forge setup --agents codex --yes
+forge setup --agents claude,cursor
+forge setup --agents claude cursor
+forge setup --all --quick
+forge setup --path ./repo --dry-run
+forge setup --agents claude,cursor
+```
+
+Use `--agents`, not `--agent`.
+
+## Local State
+
+```bash
+forge board --json
+forge options lint
+forge options diff
+forge options why <key>
+forge options stages
+```
+
+`forge options` inspects the runtime graph and `.forge/` adoption config created by `forge init`.
+
+`forge status` (full flags below) also supports workflow-state and issue-state inputs used by tests and stage recovery.
+
+## Core Workflow Loop
+
+These are the CLI commands behind the default agent workflow template (`/plan -> /dev -> /validate -> /ship`, then the `/review` skill) plus the session-orientation and memory commands agents run alongside it. Verified against `lib/commands/<name>.js` and `forge <cmd> --help`.
+
+```bash
+forge plan "<feature description>"
+forge dev [--issue-id <id>] [--phase red|green|refactor]
+forge validate
+forge ship <feature-slug> [<title>] [--dry-run]
+forge status [--full] [--json]
+forge prime [--budget N] [--json]
+forge orient [--budget N] [--json]
+forge recap <issue> [--budget N] [--json]
+forge recall [query] [--limit N] [--all] [--json]
+forge remember <note> [--tag <label>]... [--json]
+```
+
+- `forge plan` creates the implementation plan, kernel issue, and feature branch/worktree from a researched feature description; it prints the created issue id, branch name, and the suggested next command.
+- `forge dev` runs the TDD development stage with RED/GREEN/REFACTOR phase guidance; `--issue-id` scopes it to a specific kernel issue and `--phase` overrides auto-detection.
+- `forge validate` runs the validation orchestration pipeline (conflict markers, type check, lint, security, tests) with no arguments — see also `bun run check` under Validation And Packaging.
+- `forge ship` creates the pull request from validated feature work (wraps `gh pr create`); `--dry-run` previews without creating a PR.
+- `forge status` is the one-glance orientation command: where you are, what to run next, and your active work; `--full` also shows blocked/stale/recently-completed issues.
+- `forge prime` emits the bounded session-entry orientation envelope agents read at the start of a session.
+- `forge orient` emits bounded project orientation from deterministic source files (broader than `prime`, still token-budgeted via `--budget`).
+- `forge recap <issue>` is the issue-scoped counterpart to `forge orient`/`forge prime` — it summarizes a single issue from the same deterministic file assembly instead of the whole project. Requires an issue id; running it with no id (or `--help`) prints usage only.
+- `forge recall` retrieves project-memory notes from the kernel-backed memory store; omit `query` to list recent notes.
+- `forge remember` persists a project-memory note to the kernel-backed memory store; repeat `--tag` to attach multiple labels.
+
+## Issue Wrappers
+
+These commands delegate to the Kernel by default. Beads is used only when explicitly selected — precedence (highest first): the `--issue-backend beads` flag, then `FORGE_ISSUE_BACKEND=beads`, then the `.forge/config.yaml` key `issueBackend: beads`, otherwise the Kernel default. The stable Kernel-era JSON contract is defined in [Forge Kernel issue command contract](forge-kernel-issue-command-contract.md).
+
+```bash
+forge ready
+forge list
+forge show <id>
+forge issue ready --json
+forge issue list --json
+forge issue show <id> --json
+forge issue search <query> --json
+forge issue stats --json
+forge create --title "Title"
+forge update <id>
+forge claim <id>
+forge release <id>
+forge close <id>
+forge issue dep add <issue-id> <blocks-issue-id>
+forge issue dep remove <issue-id> <blocks-issue-id>
+forge issue ...
+forge issues ...
+forge sync
+```
+
+`forge release <id>` is a Kernel command contract and does not have a verified Beads passthrough in this slice.
+
+`forge sync` runs Beads/Dolt pull and push behavior when configured. `forge setup --sync` is deprecated and removes old generated GitHub-Beads sync files; future GitHub issue sync belongs to Forge Kernel/server authority.
+
+## Worktrees
+
+```bash
+forge worktree create <slug> --branch <branch-name>
+forge worktree remove <slug>
+forge clean --dry-run
+```
+
+Slugs must not contain `..`, `/`, or `\`.
+
+## Adapters
+
+```bash
+forge new adapter <name> --kind=review --template=greptile
+forge adapter list
+forge adapter test <name> --fixture=<path>
+forge adapter enable <name>
+forge adapter disable <name>
+```
+
+Only review adapters and the Greptile-shaped starter template are currently safe to present as supported.
+
+## Validation And Packaging
+
+```bash
+bun run typecheck
+bun run lint
+bun run check
+bun test --timeout 15000
+npm pack --dry-run
+```
+
+`bun run check` is the project validation pipeline.
+
+## Other Registered CLI Surfaces
+
+These commands exist as current CLI surfaces, but many are specialized and should be checked with source or tests before using them in public examples:
+
+```text
+forge audit
+forge explain
+forge docs
+forge doctor
+forge test
+forge push
+forge upgrade
+forge migrate
+forge recommend
+forge add
+```
+
+`forge migrate` is dry-run oriented in the current public docs. Do not present it as a migration executor.
+
+## Doc Gate
+
+`forge doc-gate` inspects a repository's documentation structure and enforces that code changes ship with a documentation update. It is a thin CLI wrapper over the validated doc-gate detector and gate.
+
+```bash
+forge doc-gate detect [--json]
+forge doc-gate check --base <ref> --head <ref> [--skip] [--json]
+```
+
+- `detect` runs the repo-structure detector against the current working directory and prints a human-readable summary — detected source surface, toolchain, CI provider, CHANGELOG, and AGENTS.md, plus an overall verdict — or a structured object with `--json`. Any verdict, including `ESCALATE→agent` or `MANUAL-CONFIG`, exits 0; it exits non-zero only on a real error (not a git repository, or no commits yet).
+- `check` compares the `--base` and `--head` refs and **fails when a code change lands without an accompanying documentation update**. A `pass` or `abstain` decision exits 0; a hard `fail` exits 1. Use `--skip` to record an explicit skip without supplying refs.
+
+Both subcommands require a git working tree with at least one commit (`HEAD`). The related `forge doc-gate init` (scaffold a doc-gate declaration file) and `forge doc-gate okf` (OKF bundle generation) subcommands are also registered; run `forge doc-gate` with no arguments for full usage.
+
+## Kernel Filesystem Safety
+
+The Forge Kernel stores its SQLite database under `.git/forge/kernel.sqlite`. SQLite WAL mode corrupts when a cloud-sync client (OneDrive, Dropbox, Google Drive, iCloud) or a network filesystem (UNC / SMB / NFS / mapped drive) rewrites the database mid-write. A default-on gate in `broker.initialize()` therefore **refuses** to initialize the kernel on those filesystems — the throw happens *before* any database file is created, so nothing is written to the unsafe location.
+
+```bash
+forge doctor          # human summary, exits non-zero on a refuse-class path
+forge doctor --json   # machine-readable report (schemaVersion 1)
+```
+
+`forge doctor` resolves the exact kernel database path the gate guards and reports its filesystem class **without creating any file**:
+
+| Class | Risk tier | Behavior |
+|-------|-----------|----------|
+| `local-ok` | safe | proceed silently |
+| `wsl-cross`, `unknown` | warn | proceed with a warning (fail-open) |
+| `onedrive`, `dropbox`, `gdrive`, `icloud`, `network-unc`, `mapped-network-drive` | refuse | block kernel init |
+
+**Escape hatch:** set `FORGE_KERNEL_ALLOW_UNSAFE_FS=1` to downgrade every `refuse` to a warning and proceed at your own risk (intended for reliable network homes, CI sandboxes, and incident recovery). It does not affect `safe`/`warn` classes. On Windows, mapped-drive detection **fails safe**: any probe failure is treated as `unknown` (warn), never silently allowed.
+
+## Agent Workflow Stages
+
+The default agent workflow template is:
+
+```text
+/plan -> /dev -> /validate -> /ship -> /review -> /verify
+```
+
+These are stage skills and installed agent workflows. They are intentionally documented separately from current `forge` CLI commands. The workflow is core to Forge, but it is packaged through agent harness files and skills rather than through one CLI command per stage. Pre-merge is not one of these numbered stages or a `/premerge` command; it is a documentation-and-handoff gate embedded in the `/ship` and `/review` stages that finishes docs and confirms CI before merge.
+
+Do not document these as current CLI commands unless the matching `lib/commands/<name>.js` file exists:
+
+```text
+forge review
+forge verify
+```

package/docs/reference/DECISION_DRIFT_GUARDS.md

@@ -0,0 +1,97 @@
+# Decision Drift Guards
+
+**Status**: Planning reference for the Forge Kernel authority reset.
+**Canonical decision registry**: [Project design and decision registry](../PROJECT_DESIGN.md).
+**Historical decision log**: [Locked decisions](../work/2026-04-28-skeleton-pivot/locked-decisions.md).
+
+## Purpose
+
+Forge has moved from a Beads/Dolt-centered plan to a Forge Kernel authority plan. This document defines the checks that keep future PRs from accidentally drifting back to the old architecture. Current accepted direction is tracked in `docs/PROJECT_DESIGN.md`; historical work-folder decisions are evidence unless promoted there or accepted by Kernel decision event.
+
+## Non-Negotiable Rules
+
+1. Forge Kernel is the issue authority.
+2. Beads is import/export compatibility only.
+3. Local mode uses local SQLite WAL broker authority.
+4. Team mode requires server authority.
+5. GitHub/Linear are projections only.
+6. Harness files are generated projections only.
+7. Skills, MCPs, agents, commands, hooks, scripts, docs/context packs, and extensions are capability providers.
+8. Forge-owned check commands are the policy engine; agent hooks, Lefthook, and CI are adapters/enforcement surfaces.
+9. Users configure provider/stage bindings; Forge validates and records them.
+10. Conflicts are quarantined in Forge before projection.
+11. Raw prompts/tool logs remain local-only by default.
+
+## Required Doc Updates
+
+Any PR changing authority, storage, workflow config, provider loading, issue commands, team sync, Beads migration, or external projections must update:
+
+- [PROJECT_DESIGN.md](../PROJECT_DESIGN.md) when accepted/current project direction changes
+- [Architecture index](../architecture/index.md) or scoped `docs/architecture/**` records when architecture-significant behavior is changed or discovered
+- [forge-kernel-authority-control-plane.md](../work/2026-04-28-skeleton-pivot/forge-kernel-authority-control-plane.md)
+- [locked-decisions.md](../work/2026-04-28-skeleton-pivot/locked-decisions.md)
+- [release-plan.md](../work/2026-04-28-skeleton-pivot/release-plan.md)
+- [FORGE_KERNEL_STORAGE_MODEL.md](./FORGE_KERNEL_STORAGE_MODEL.md)
+- the implementation-specific guide/reference doc for the changed surface
+
+## Evaluator Checklist
+
+Before a release PR can be considered ready, run or manually answer these checks:
+
+```text
+Authority:
+  - Does any path make Beads, GitHub, Linear, D1, or a harness file authoritative?
+  - Do issue commands write through Forge Kernel?
+
+Storage:
+  - Is each new field classified as authority, cache, projection, archive, or config?
+  - Is local-only sensitive data protected from server upload by default?
+
+Team mode:
+  - Are claim/start/close/stage-transition writes blocked when server authority is unavailable?
+  - Are stale/reclaimable states visible and auditable?
+
+Providers:
+  - Are external skills/MCPs/agents/commands/hooks declared as provider capabilities?
+  - Are required providers validated before stage execution?
+  - Are unknown providers prevented from becoming required without evidence/evaluator support?
+
+Projections:
+  - Does projection failure leave Forge Kernel state intact?
+  - Are dead letters visible with repair actions?
+
+Docs:
+  - Did the PR update the authority plan, storage model, and release gates if behavior changed?
+  - Did the PR update or explicitly leave unchanged docs/PROJECT_DESIGN.md for accepted decision changes?
+  - Did the PR answer architecture impact and add/update docs/architecture/** records for architecture-significant changes or discoveries?
+```
+
+## Forbidden Drift Patterns
+
+- Direct `.beads/issues.jsonl` reads as current state authority.
+- `bd` commands as the canonical write path after Kernel command routing lands.
+- GitHub or Linear webhook payloads overwriting Forge-owned fields.
+- D1 reads deciding claims or lease state.
+- Generated Claude/Cursor/Codex files being edited as source of truth.
+- Lefthook or any agent-specific hook treated as the policy source of truth instead of Forge-owned checks plus CI/Kernel gates.
+- Agents using `git commit --no-verify`, `git push --no-verify`, `HUSKY=0`, `LEFTHOOK=0`, `git -c core.hooksPath=...`, script-mediated hook bypasses, or hook removal to bypass Forge workflow gates without explicit audited authorization recorded as Forge/Kernel-compatible evidence.
+- Required skills loaded by prompt discretion instead of WorkflowGraph policy.
+- Silent projection failures.
+- Accepted project direction living only in a work folder, chat transcript, Beads memory, generated summary, or agent prompt without a `docs/PROJECT_DESIGN.md` entry.
+- Architecture-significant behavior, domain rules, constraints, or subsystem facts discovered during work but not captured as an architecture record, ADR, work evidence, or KnowledgeStore proposal.
+- Fixed heartbeat spam as the main liveness signal.
+
+## Release Gate
+
+Each Kernel-era release must include a short evaluator note with:
+
+```text
+Authority score:
+Storage score:
+Provider/config score:
+Projection score:
+Security/privacy score:
+Known drift risks:
+```
+
+Target score is 100/100. Anything below 100 needs a documented follow-up or a deliberate locked decision.

package/docs/{EXAMPLES.md → reference/EXAMPLES.md}

@@ -1,5 +1,7 @@
 # Forge Workflow Examples
 
+> Historical examples. These transcripts are illustrative, not current setup or timing guarantees. Use [Quickstart](../../QUICKSTART.md), [Workflow templates](../guides/WORKFLOW_TEMPLATES.md), and [Command reference](COMMANDS.md) for current behavior.
+
 Real-world examples showing how to use Forge for different scenarios.
 
 ---
@@ -17,7 +19,7 @@ Real-world examples showing how to use Forge for different scenarios.
 
 **Task**: Add a health check endpoint
 
-**Estimated Time**: 15 minutes
+**Estimated Time**: Historical example only; do not treat as a guarantee.
 
 **Workflow**: Tactical
 
@@ -88,7 +90,7 @@ git commit -m "feat: add health check endpoint"
 # URL: https://github.com/you/project/pull/42
 ```
 
-**Result**: Feature shipped in 15 minutes with tests and documentation.
+**Result**: Historical transcript showing the intended flow with tests and documentation. Do not treat the timing or output as a current guarantee.
 
 ---
 
@@ -473,10 +475,10 @@ forge sync
 
 ## Next Steps
 
-📚 **New to Forge?** → [QUICKSTART.md](../QUICKSTART.md)
+📚 **New to Forge?** → [QUICKSTART.md](../../QUICKSTART.md)
 
-📖 **Learn workflow** → [AGENTS.md](../AGENTS.md)
+📖 **Learn workflow** → [AGENTS.md](../../AGENTS.md)
 
-🛠️ **Setup tools** → [SETUP.md](SETUP.md)
+🛠️ **Setup tools** → [SETUP.md](../guides/SETUP.md)
 
 💬 **Questions?** → [GitHub Discussions](https://github.com/harshanandak/forge/discussions)