forge-workflow 0.0.10 → 0.1.0-beta.2

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)

package/docs/reference/FORGE_KERNEL_STORAGE_MODEL.md

@@ -0,0 +1,135 @@
+# Forge Kernel Storage Model
+
+**Status**: Planning reference for the Forge Kernel authority reset.
+**Canonical design**: [Forge Kernel authority control plane](../work/2026-04-28-skeleton-pivot/forge-kernel-authority-control-plane.md).
+
+## Purpose
+
+This document defines where Forge Kernel state lives, what is authoritative, what is cached, what is projected, and what is archived. It exists to prevent future implementation work from drifting back into Beads-first, GitHub-first, or harness-first storage.
+
+## Storage Layers
+
+```text
+Authority
+  Local mode: local SQLite WAL broker
+  Team mode: Cloudflare Durable Object per project
+
+Read model
+  Local mode: SQLite query tables
+  Team mode: D1 query tables
+
+Projection state
+  Beads export/import status
+  GitHub/Linear projection delivery status
+  dead letters and repair state
+
+Repository exports
+  Explicit Kernel projection snapshots for clone/bootstrap/review only
+  Not the durability channel for routine local or team writes
+
+Archive
+  Local evidence archive
+  R2 for server-side large evidence/log/artifact bundles
+
+Configuration
+  .forge/workflow.yaml
+  .forge/providers/*.yaml
+  .forge/providers.lock later
+  generated harness files as projections only
+```
+
+## Authority Rules
+
+1. Forge Kernel owns issue, claim, stage, run, and projection state.
+2. Beads is import/export compatibility only.
+3. GitHub and Linear are server-side projections only.
+4. Harness files are generated projections only.
+5. D1 is a read model, not the claim authority.
+6. Queues retry projection work, not core issue mutations.
+7. R2 stores large evidence and archives, not hot authority fields.
+8. Routine close/verify state is never made durable by committing tracker metadata to the protected default branch.
+9. Repository exports are explicit projection artifacts, not the write-ahead log for normal work.
+
+## Local Mode
+
+Local mode is for one user working across one or more local worktrees.
+
+Local SQLite WAL broker stores:
+
+- issue graph,
+- dependencies and blockers,
+- comments,
+- priorities,
+- claims and stale/reclaim state,
+- stages and substages,
+- worktrees,
+- sessions,
+- runs,
+- event log,
+- local outbox,
+- projection/import/export status.
+
+Local mode may work without a server. It must still prevent two local worktrees from double-claiming the same issue.
+
+Local mode is intentionally local-only. Closing an issue, recording a run, updating a claim, or saving project knowledge in local mode must not require a Git commit or push. If the user wants another machine or teammate to see that state, Forge must use team mode server authority or an explicit export/import operation.
+
+### SQLite Runtime Driver
+
+Forge Kernel local mode uses a builtin SQLite runtime driver. Driver selection must feature-detect `bun:sqlite` first and backup-capable `node:sqlite` second, and must not add a native-compile SQLite package as the default install path.
+
+The selected driver must pass conformance checks for WAL mode, `busy_timeout`, transactions, WAL checkpointing, backup creation, and FTS5 before Forge claims real local SQLite authority behavior.
+
+## Team Mode
+
+Team mode requires server authority.
+
+Cloudflare components:
+
+- Worker API validates auth, project membership, and routes requests.
+- Durable Object serializes issue mutations and claims for a project.
+- D1 stores queryable read models for dashboards and reports.
+- Queues run retryable Beads/GitHub/Linear projections.
+- R2 stores optional large evidence, validation artifacts, and archived session bundles.
+
+Team mode must block claim/start/close/stage-transition writes when the server cannot accept them.
+
+Team mode is the only shared write authority. Cross-machine and multi-user close/verify state must be accepted by the server before Forge reports it as shared truth. Projection workers may update GitHub, Linear, Beads, or explicit export artifacts after acceptance, but projection failure never rolls back the accepted server event.
+
+## Local Versus Server Matrix
+
+| Data | Local mode | Team mode | Rule |
+| --- | --- | --- | --- |
+| Issue identity/title/body/type | SQLite authority | Durable Object authority + D1 read model | Server acceptance required in team mode. |
+| Priority/order | SQLite authority | Durable Object authority + D1 read model | Deterministic reorder events. |
+| Dependencies/blockers | SQLite authority | Durable Object authority + D1 read model | Ready queue depends on this. |
+| Comments | SQLite authority | Durable Object authority + D1 read model | Sensitive local-only notes allowed only in local mode. |
+| Claims/leases | SQLite authority | Durable Object authority | Team claims are never offline-authoritative. |
+| Worktree path | SQLite full path | Redacted/normalized server record | Avoid leaking full local paths by default. |
+| Session state | SQLite | Durable Object + D1 read model | Required for team visibility. |
+| Stage/substage state | SQLite | Durable Object + D1 read model | Source for gates and workflow progress. |
+| Run events | SQLite | Durable Object + D1 read model | Raw details may be summarized before upload. |
+| Evidence metadata | SQLite | D1 metadata + optional R2 object | Store pointers and hashes. |
+| Raw prompts/tool logs | Local only by default | Optional redacted R2 archive | Never push by default. |
+| Provider manifests | Project files + local cache | Optional server hash/copy | Required providers need revision agreement. |
+| Workflow config | Project files + local cache | Server copy/hash in team mode | Team writes require config revision agreement. |
+| Beads import source | Local archive | Not uploaded by default | Upload only migration summary if needed. |
+| Beads export output | Local projection | Projection status only | Export failure never rolls back Kernel state. |
+| Kernel repository export | Explicit local export | Explicit server export/projection | Repository files are reviewable snapshots, not hot authority. |
+| GitHub/Linear projection | Local status cache | Server outbox/projection table | Server workers own external projection. |
+| Dead letters/conflicts | SQLite | Durable Object/D1 dead-letter state | Must be visible before release readiness. |
+
+## Drift Guard
+
+Any PR that changes storage, authority, sync, projections, issue commands, workflow configuration, or provider loading must answer:
+
+```text
+What is authoritative?
+What is cached?
+What is projected?
+What is archived?
+What remains local-only?
+What requires server acceptance?
+What happens when projection fails?
+```
+
+If those answers change, update this document, the authority plan, and locked decisions.