forge-workflow 0.0.9 → 0.1.0-beta.2

package/docs/reference/dependency-chain.md

@@ -0,0 +1,331 @@
+# Forge Workflow: Dependency Chain Research
+
+> Historical note: this file describes an older setup dependency map. Current user-facing setup guidance lives in [Setup Guide](../guides/SETUP.md) and [Command Reference](COMMANDS.md).
+> Known-stale content may appear below because this file is retained as research context for maintainers, not as current setup authority.
+
+**Date**: 2026-02-23
+**Branch**: feat/skills-restructure
+**Objective**: Map every dependency the Forge workflow installs, how it installs them, what their own prerequisites are, and how the user is informed throughout.
+
+---
+
+## 1. What Forge Installs — Complete Map
+
+### Quick Setup Flow (`bunx forge setup --quick`)
+
+```
+quickSetup()
+ ├── checkPrerequisites()
+ ├── Copy AGENTS.md
+ ├── setupCoreDocs()
+ ├── autoInstallLefthook()
+ ├── autoSetupToolsInQuickMode()
+ │    ├── autoSetupBeadsInQuickMode()
+ │    ├── initializeOpenSpec() (only if already installed)
+ │    └── initializeSkills() (only if already installed)
+ ├── loadAndSetupClaudeCommands()
+ ├── setupSelectedAgents()
+ ├── installGitHooks()
+ └── configureDefaultExternalServices()
+```
+
+### Every Tool — Install Method and Command
+
+| Tool | Install Method | Command Used | Platform Branch |
+|------|---------------|--------------|-----------------|
+| **Lefthook** | npm/bun devDep | `bun add -d lefthook` | No |
+| **Beads** | npm global | `npm install -g @beads/bd` | ⚠️ No Windows branch |
+| **OpenSpec** | Skip if missing | `openspec init` only if found | No |
+| **Skills** | Skip if missing | `skills init` only if found | No |
+| **Git hooks** | via lefthook | `lefthook install` → hooks from lefthook.yml | No |
+| **Context7 MCP** | npx/bunx at runtime | pin `@upstash/context7-mcp@2` in current examples | Auto for configured agents |
+| **Grep.app MCP** | npx at runtime | `npx -y @ai-tools-all/grep_app_mcp` | Auto for Claude Code, Continue |
+| **Agent config files** | File copy | Copies .claude/, .cursor/, .github/, etc. | Yes (path handling) |
+| **AGENTS.md** | File copy | from package | No |
+| **docs/forge/TOOLCHAIN.md / docs/forge/VALIDATION.md** | File copy | from package | No |
+
+---
+
+## 2. Dependencies of Each Tool
+
+### Beads (`@beads/bd`)
+
+- **Language**: Go binary (pre-compiled, ~114MB `.exe` on Windows)
+- **Runtime deps**: None — self-contained binary
+- **Install prerequisites**:
+
+| Install Path | Prerequisites | Works on Windows? |
+|-------------|--------------|-------------------|
+| `npm install -g @beads/bd` | npm/bun | ⚠️ Broken — Issue #1031, closed "not planned" |
+| `irm .../install.ps1 \| iex` | PowerShell 5+ | ✅ Recommended on Windows |
+| `curl .../install.sh \| bash` | bash, curl | ❌ Needs Git Bash or WSL |
+| `go install .../bd@latest` | Go 1.24+ | ✅ Works |
+| `brew install beads` | Homebrew | macOS/Linux only |
+
+- **Build-from-source deps** (only if no pre-compiled binary):
+  - macOS: `icu4c`, `zstd`
+  - Linux: `libicu-dev`, `libzstd-dev`
+  - Windows: Go 1.24+ (no ICU required — uses pure Go regex backend)
+
+- **What `bd init` creates**: `.beads/` directory with `issues.jsonl`, `metadata.json`, `config.yaml`, `README.md`, `.gitignore`
+
+- **Critical gap**: forge.js uses `npm install -g @beads/bd` on ALL platforms including Windows, where this is broken. The PowerShell installer (`install.ps1`) is never called.
+
+### OpenSpec (`@fission-ai/openspec`)
+
+- **Language**: Node.js (pure JS/TS, not a compiled binary)
+- **Runtime**: Node.js ≥ 20.19.0
+- **Own dependencies** (transitive, pulled on install):
+  - `@inquirer/core`, `@inquirer/prompts` — CLI prompts
+  - `commander` — CLI argument parsing
+  - `chalk` — terminal colors
+  - `fast-glob` — file pattern matching
+  - `ora` — **spinner** (ironically OpenSpec has a spinner, Forge doesn't)
+  - `yaml` — YAML parsing
+  - `zod` — schema validation
+  - `posthog-node` — analytics (sends usage telemetry)
+- **Install prerequisites**: Node.js 20+ only
+- **Works on Windows**: ✅ Yes — pure Node.js
+- **What `openspec init` creates**: `openspec/` directory with proposal templates
+- **Forge behavior**: Only initialized if already installed. Never force-installed. If not on machine, silently skipped.
+
+### Lefthook
+
+- **Language**: Go binary (same distribution model as Beads)
+- **Runtime deps**: None — zero dependencies
+- **Own npm dependencies**: Uses `optionalDependencies` for platform-specific binaries:
+  - `lefthook-darwin-arm64`, `lefthook-darwin-x64`
+  - `lefthook-linux-arm64`, `lefthook-linux-x64`
+  - `lefthook-win32-x64`, `lefthook-win32-arm64`
+- **Install prerequisites**: npm/bun only (binary bundled in npm package)
+- **Works on Windows**: ✅ Yes — ships Windows binary via npm optionalDependencies
+- **What lefthook installs** (via lefthook.yml): 3 git hooks:
+  - `commit-msg`: `bunx commitlint --edit {1}` — enforces conventional commits
+  - `pre-commit`: `node .forge/hooks/check-tdd.js` — TDD enforcement
+  - `pre-push`: branch protection + ESLint + test suite
+- **Pre-push hooks use bash syntax** (`if [ $? -ne 0 ]`) — ⚠️ breaks on Windows without Git Bash
+- **Transitive from hooks**: `commitlint` pulled via bunx at runtime (not pre-installed)
+
+### GitHub CLI (`gh`)
+
+- **Not installed by Forge** — must be pre-installed by user
+- **Checked in**: `checkPrerequisites()` — fatal error if missing
+- **Auth status**: checked as warning (not fatal)
+- **Download**: https://cli.github.com
+- **No version requirement specified** in forge.js
+
+### MCP Servers (Context7, Grep.app)
+
+- **Not pre-installed** — downloaded at runtime when agent first uses them
+- **Mechanism**: current examples pin `@upstash/context7-mcp@2`; older notes used on-demand `@latest`
+- **Prerequisites**: npx (comes with npm) or bunx
+- **Context7 own deps**: Historical note; current examples pin `@upstash/context7-mcp@2`.
+- **Grep.app own deps**: Unknown — no version pinned
+- **Version pinning gap**: Both use `@latest` — breaking changes can silently break research workflow
+- **Auto-configured for**: Claude Code (`.mcp.json`)
+- **Manual setup required for**: Cursor, Cline
+
+---
+
+## 3. Transitive Dependencies (What Each Tool Pulls In)
+
+```
+Forge setup triggers:
+│
+├── npm install -g @beads/bd
+│   └── Pre-compiled Go binary (no transitive npm deps)
+│
+├── bun add -d lefthook
+│   └── lefthook-win32-x64 (or platform binary) via optionalDeps
+│       └── No further deps
+│
+├── lefthook install (from lefthook.yml)
+│   ├── commit-msg hook → bunx commitlint (runtime, not pre-installed)
+│   │   └── @commitlint/cli + @commitlint/config-conventional (in devDeps ✓)
+│   ├── pre-commit hook → node .forge/hooks/check-tdd.js (local file)
+│   └── pre-push hook → bunx eslint (runtime)
+│       └── eslint (in devDeps ✓)
+│
+├── pinned Context7 MCP runtime (at agent runtime)
+│   └── Unknown — @latest, not audited
+│
+└── npx @ai-tools-all/grep_app_mcp (at agent runtime)
+    └── Unknown — no version pinned
+```
+
+**Key finding**: Beads and Lefthook have zero transitive npm dependencies (Go binaries). OpenSpec has ~8 transitive Node.js deps but all are benign utilities. The MCP servers are the unknown — they run as subprocesses with whatever deps they pull.
+
+---
+
+## 4. User-Facing Progress Reporting
+
+### What the user currently sees
+
+```
+[ASCII Banner]
+  Forge v1.6.0
+  Quick Setup
+
+Checking prerequisites...
+  ✓ git version 2.x
+  ✓ gh version 2.x
+  ✓ node v22.x
+  ✓ bun v1.x
+
+  Created: AGENTS.md (universal standard)
+
+📦 Installing lefthook for git hooks...
+  ✓ Lefthook installed
+
+📦 Installing Beads globally...
+  ✓ Beads installed globally
+📦 Initializing Beads...
+  ✓ Beads initialized
+
+[1/1] Setting up Claude Code...
+  ✓ ...
+
+Installing git hooks (TDD enforcement)...
+  ✓ Lefthook hooks installed (local)
+
+==============================================
+  Forge v1.6.0 Quick Setup Complete!
+==============================================
+
+Next steps:
+  1. Start with: /status
+  2. Read the current setup and command guides under docs/guides/ and docs/reference/
+```
+
+### What's MISSING from the UX
+
+| Missing Element | Impact |
+|----------------|--------|
+| No spinner/progress bar | User can't tell if it's hung or working |
+| No step counter in quick mode | "Step 3 of 6" would orient the user |
+| No post-install verification | "Beads installed" ≠ `bd version` actually works |
+| Silent skips for OpenSpec/Skills | User doesn't know they weren't installed |
+| No total time estimate | Network-heavy steps (beads download) feel like hangs |
+| No retry feedback | If npm fails, just says "run manually" with no context |
+| No success summary with versions | Should show: `bd 0.49.1 ✓`, `lefthook 1.10.x ✓` |
+
+### Interactive mode step counter (exists but only in agent setup)
+
+```
+[1/1] Setting up Claude Code...  ← This exists for agent files
+```
+
+But NOT for the tool installation steps (beads, openspec, lefthook).
+
+---
+
+## 5. Windows-Specific Gaps
+
+### What forge.js does detect on Windows
+- `process.platform === 'win32'` → uses `where.exe` instead of `which`
+- CRLF handling (line 85): `.split(/\r?\n/)` on path resolution
+- chmod skipped with warning (line 2886)
+
+### What forge.js does NOT do on Windows
+- Does NOT detect Windows and switch to `install.ps1` for beads
+- Does NOT warn about bash-syntax lefthook hooks
+- Does NOT check for Git Bash or WSL
+- Does NOT offer PowerShell alternative for beads
+
+### Windows failure sequence (current behavior)
+```
+1. forge.js runs npm install -g @beads/bd
+2. npm postinstall runs PowerShell Expand-Archive
+3. File locking error (EPERM) — bd.exe never lands
+4. forge.js catches error, prints "Run manually: npm install -g @beads/bd && bd init"
+5. User retries npm install → same EPERM → stuck in loop
+6. pre-push hook runs bash syntax → fails on Windows CMD
+7. User has lefthook installed but hooks don't fire correctly
+```
+
+### Correct Windows flow (not yet implemented)
+```
+1. Detect win32
+2. Run: powershell -Command "irm https://.../install.ps1 | iex"
+3. Verify: bd version
+4. Run: bd init
+5. For lefthook hooks: verify Git Bash is available, or use Node.js equivalents
+```
+
+---
+
+## 6. Full Flow — Zero to Working
+
+### macOS / Linux
+```bash
+# Prerequisites (manual)
+# - git (https://git-scm.com)
+# - gh (https://cli.github.com) + gh auth login
+# - Node.js 20+ (https://nodejs.org)
+# - bun (https://bun.sh)
+
+# Install Forge (triggers postinstall → copies AGENTS.md baseline)
+npx forge-workflow
+# OR add to project:
+bun add -d forge-workflow
+
+# Full setup (single command)
+bunx forge setup --quick
+
+# Verify
+bd version        # should show 0.49.x
+lefthook version  # should show 1.10.x
+bd ready          # should show open issues
+```
+
+### Windows (correct flow — not what forge currently does)
+```powershell
+# Prerequisites (manual)
+# - Git for Windows (https://git-scm.com) — includes bash
+# - gh CLI (https://cli.github.com) + gh auth login
+# - Node.js 20+ (https://nodejs.org)
+# - bun (https://bun.sh)
+
+# Install beads FIRST (before forge setup) — npm is broken on Windows
+irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 | iex
+
+# Then install Forge
+npx forge-workflow
+
+# Full setup
+bunx forge setup --quick
+
+# Verify
+bd version        # should work now (was pre-installed)
+lefthook version  # should work (ships Windows binary via npm)
+```
+
+---
+
+## 7. Key Gaps — Priority Order
+
+| Priority | Gap | Fix |
+|----------|-----|-----|
+| P0 | Beads npm install broken on Windows | Detect win32, use install.ps1 |
+| P0 | No post-install verification | Run `bd version` after install, fail loudly if not working |
+| P1 | OpenSpec/Skills silently skipped | Show clear message: "OpenSpec not found — install with: ..." |
+| P1 | lefthook.yml pre-push uses bash syntax | Replace `if [ $? -ne 0 ]` with cross-platform Node.js scripts |
+| P1 | Historical MCP server notes used `@latest` | Current examples pin `@upstash/context7-mcp@2` |
+| P2 | No spinner during installs | Add ora (already a dep of OpenSpec — ironic) |
+| P2 | No step counter in quick mode | "Step 3/6: Installing Beads..." |
+| P2 | No versions in success summary | Show installed versions at end |
+| P3 | Go not mentioned as Windows fallback | Document: if install.ps1 fails → go install |
+| P3 | OpenSpec telemetry (posthog-node) | Document/allow opt-out |
+| P3 | GitHub integration not set up post-install | Add `bd config set github.org/repo` prompt |
+
+---
+
+## Sources
+
+- [Beads Installation Docs](https://steveyegge.github.io/beads/getting-started/installation)
+- [npm install broken on Windows #1031](https://github.com/steveyegge/beads/issues/1031) — closed "not planned"
+- [OpenSpec GitHub](https://github.com/Fission-AI/OpenSpec)
+- [OpenSpec package.json](https://github.com/Fission-AI/OpenSpec/blob/main/package.json)
+- [Lefthook npm](https://www.npmjs.com/package/lefthook) — 0 dependencies, platform binaries via optionalDeps
+- [Lefthook Installation Docs](https://lefthook.dev/installation/node.html)
+- [Beads install.ps1](https://github.com/steveyegge/beads/blob/main/install.ps1)

package/docs/reference/forge-kernel-issue-command-contract.md

@@ -0,0 +1,161 @@
+# Forge Kernel Issue Command Contract
+
+**Status**: Contract slice for Kernel-backed issue commands.
+**Code contract**: `lib/kernel/issue-command-contract.js`.
+**Storage model**: [Forge Kernel storage model](FORGE_KERNEL_STORAGE_MODEL.md).
+
+## Purpose
+
+This document defines the stable command contract for the Forge Kernel issue surface before the full Beads execution path is replaced. The command schemas, error envelope, next-command hints, and exit behavior are the contract. Skills and harness files must wrap these CLI commands rather than inventing alternate behavior.
+
+This PR does not make every command Kernel-backed at runtime. Verified Beads-compatible passthroughs may remain during migration. Commands without a verified Beads equivalent, such as `forge release <id>`, are contract-defined for the Kernel backend and must not pretend to be supported through Beads.
+
+## Commands
+
+Read commands must support `--json` and return `next_commands`:
+
+```text
+forge issue ready --json
+forge issue list --json
+forge issue show <id> --json
+forge issue search <query> --json
+forge issue stats --json
+```
+
+Mutation commands must return the affected issue id, the resulting revision, and `next_commands`:
+
+```text
+forge issue create
+forge issue update
+forge issue close
+forge issue comment
+forge issue dep add
+forge issue dep remove
+forge claim <id>
+forge release <id>
+```
+
+The operation names behind those commands are stable:
+
+| Command | Operation | Mode |
+| --- | --- | --- |
+| `forge issue ready --json` | `ready` | read |
+| `forge issue list --json` | `list` | read |
+| `forge issue show <id> --json` | `show` | read |
+| `forge issue search <query> --json` | `search` | read |
+| `forge issue stats --json` | `stats` | read |
+| `forge issue create` | `create` | mutation |
+| `forge issue update` | `update` | mutation |
+| `forge issue close` | `close` | mutation |
+| `forge issue comment` | `comment` | mutation |
+| `forge issue dep add` | `dep.add` | mutation |
+| `forge issue dep remove` | `dep.remove` | mutation |
+| `forge claim <id>` | `claim` | mutation |
+| `forge release <id>` | `release` | mutation |
+
+## Success Envelopes
+
+All successful JSON responses use schema version `forge.issue.v1`.
+
+Single-issue reads return:
+
+```json
+{
+  "ok": true,
+  "schema_version": "forge.issue.v1",
+  "command": "forge issue show forge-123 --json",
+  "data": {
+    "id": "forge-123",
+    "title": "Define command contract",
+    "type": "task",
+    "status": "open",
+    "revision": 7
+  },
+  "next_commands": [
+    "forge claim forge-123",
+    "forge issue comment forge-123 \"<note>\""
+  ]
+}
+```
+
+List-style reads return `data.issues[]`, optional counts, and `next_commands`. `forge issue stats --json` returns `data.counts` plus ready, blocked, and claim counts when available.
+
+Mutations return:
+
+```json
+{
+  "ok": true,
+  "schema_version": "forge.issue.v1",
+  "command": "forge claim forge-123",
+  "data": {
+    "id": "forge-123",
+    "revision": 8,
+    "projection": {
+      "status": "pending",
+      "targets": ["beads"]
+    }
+  },
+  "next_commands": [
+    "forge issue show forge-123 --json",
+    "forge release forge-123"
+  ]
+}
+```
+
+## Error Envelope
+
+All command failures that render JSON use `forge.issue.error.v1`:
+
+```json
+{
+  "ok": false,
+  "schema_version": "forge.issue.error.v1",
+  "command": "forge issue show forge-missing --json",
+  "error": {
+    "code": "ISSUE_NOT_FOUND",
+    "message": "Issue not found: forge-missing",
+    "exit_code": 3,
+    "retryable": false
+  },
+  "next_commands": [
+    "forge issue search \"forge-missing\" --json"
+  ]
+}
+```
+
+`error.code` is stable for scripts. `error.message` is for humans. `error.details` may be present for structured diagnostics, but consumers must not require it.
+
+## Exit Codes
+
+| Exit code | Meaning |
+| --- | --- |
+| `0` | Success. |
+| `1` | Internal or unclassified command failure. |
+| `2` | Usage error, invalid flags, or missing required arguments. |
+| `3` | Requested issue, dependency, claim, or comment was not found. |
+| `4` | Revision conflict, claim conflict, or dependency-cycle conflict. |
+| `5` | Required backend, broker, projection target, or local filesystem authority is unavailable. |
+| `6` | Validation failure for command input or payload shape. |
+
+## Revision And Idempotency
+
+Kernel writes are guarded by `expected_revision` and idempotency at the broker boundary. The CLI owns both:
+
+- The CLI derives idempotency metadata from the command, normalized payload, actor/session/worktree context, and retry attempt.
+- The CLI fetches or refreshes the current issue revision before submitting a guarded mutation.
+- Skills must not hand-generate idempotency keys.
+- Skills must not require agents to supply `expected_revision` for normal commands.
+- A later escape hatch may expose an explicit revision flag for advanced repair flows, but that flag is not part of the agent happy path.
+
+Successful mutation responses expose the resulting `revision`; they do not require the caller to understand the broker event internals.
+
+## Beads Migration Boundary
+
+During migration, these verified Beads-compatible passthroughs may remain:
+
+- `ready`, `list`, `show`, `search`, and `stats`,
+- `create`, `update`, `close`, and `comment`,
+- `dep.add` and `dep.remove`,
+- legacy `claim` through `bd update --claim` until Kernel claim leases become the default.
+
+`release` is Kernel-only in this contract because no verified Beads release operation is documented by the current Beads help surface. Implementing real Kernel execution for `release` belongs to the follow-up broker command PR.

package/docs/reference/forge-kernel-schema.md

@@ -0,0 +1,72 @@
+# Forge Kernel Schema And Migrations
+
+**Status**: 0.0.20 schema slice reference.
+**Storage model**: [Forge Kernel storage model](FORGE_KERNEL_STORAGE_MODEL.md).
+
+## Purpose
+
+This document records the contract for the 0.0.20 Forge Kernel schema slice. It is a release reference for the schema registry, local migration plans, and storage-class metadata. It does not define the broker runtime, importer/exporter behavior, or conflict resolver behavior; those remain follow-up PRs.
+
+## Schema registry contract
+
+`lib/kernel/schema.js` is the source of truth for Kernel table definitions in this slice. The registry must keep table names, fields, primary keys, indexes, storage classes, and field authority metadata together so later broker and adapter work can consume one deterministic definition.
+
+The schema registry covers these Kernel surfaces:
+
+- issues,
+- dependencies,
+- comments,
+- priority events,
+- claims,
+- sessions,
+- worktrees,
+- stage runs,
+- evidence,
+- projections,
+- conflicts,
+- events,
+- outbox entries,
+- dead letters.
+
+Kernel events persist `expected_revision` alongside the idempotency key and payload. Conflict evaluators depend on that revision metadata to distinguish a true equivalent retry from a later intentional write that returns an entity to an earlier payload.
+
+Every table and field must declare a storage class and field authority that match [FORGE_KERNEL_STORAGE_MODEL.md](FORGE_KERNEL_STORAGE_MODEL.md). Drift guard failures should name the missing or invalid table or field.
+
+## Migration contract
+
+`lib/kernel/migrations.js` owns reversible local migration plans for this slice. Migration definitions must:
+
+- apply in declared order,
+- roll back in reverse order,
+- reject duplicate migration IDs,
+- produce deterministic SQL,
+- avoid introducing a database runtime dependency.
+
+Migration SQL generation should stay small and explicit. Runtime connection management, broker coordination, and remote execution are outside this slice.
+
+`expected_revision` on `kernel_events` is added by the additive `002_kernel_events_expected_revision` migration so existing local Kernel databases created by the initial schema migration gain the column during upgrade.
+
+## Storage-class contract
+
+Storage-class metadata must answer the storage model questions before a table or field lands:
+
+- 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?
+
+The valid classes and authority rules are inherited from [FORGE_KERNEL_STORAGE_MODEL.md](FORGE_KERNEL_STORAGE_MODEL.md). This schema reference links that model so changes to schema, migrations, or storage classification cannot drift into undocumented authority behavior.
+
+## Follow-up PRs
+
+This document intentionally limits 0.0.20 to schema, migration, and storage-class contracts. Follow-up PRs should cover:
+
+- broker read/write execution,
+- Beads import and export adapters,
+- conflict detection and resolution workflows,
+- projection delivery workers,
+- dead-letter repair operations,
+- team-mode server acceptance paths.

package/docs/reference/kernel-conflict-evaluators.md

@@ -0,0 +1,27 @@
+# Kernel Conflict Evaluators
+
+**Status**: 0.0.20 conflict quarantine slice.
+
+## Contract
+
+Kernel event writes are evaluated before projection. The evaluator can accept a write, return a prior accepted idempotency result, dedupe an equivalent write, or quarantine the write as a conflict.
+
+Quarantined writes insert `kernel_conflicts` records and do not enqueue projection outbox entries. This keeps Beads, GitHub, Linear, and other downstream projections from resolving authority conflicts.
+
+## Guarded Cases
+
+- Stale `expected_revision` values quarantine the write with the actual entity revision.
+- Duplicate idempotency keys return the original accepted event without creating a second event or projection.
+- Equivalent duplicate writes dedupe even when the retry uses a different idempotency key.
+- Dependency writes that would create a dependency cycle quarantine before projection.
+- Fixture cases cover import fidelity, priority ordering, dependency correctness, idempotency, and drift guard violations.
+
+## Broker Ordering
+
+The local broker remains dependency-free. Drivers provide the storage runtime and the broker enforces this order:
+
+1. Load the authority entity revision, prior events, and dependencies.
+2. Evaluate the event.
+3. Insert a conflict for quarantined writes and stop.
+4. Insert accepted events.
+5. Enqueue projection outbox rows only after event acceptance.

package/docs/reference/patch-md-format.md

@@ -0,0 +1,77 @@
+# patch.md Format
+
+`patch.md` records user patch intent against stable Forge anchors. It is a reviewable markdown file, not an upgrade engine. Later upgrade and rollback work can consume these records to explain conflicts, preserve local edits, or refuse unsafe operations with a clear hint.
+
+## Anchor Declaration
+
+Managed files declare stable anchors with HTML comments:
+
+```md
+<!-- forge-anchor:stage.validate -->
+```
+
+The anchor ID is the durable identity. File paths can change. When a file is renamed, Forge scans the workspace and resolves the record to the file that still declares the anchor.
+
+## Record Block
+
+Each patch intent record is a markdown block with YAML metadata and a unified diff:
+
+````md
+<!-- forge-patch-intent:v1
+id: patch_stage_validate_8f14e45fceea
+anchorId: stage.validate
+path: .claude/commands/validate.md
+createdAt: 2026-05-13T00:00:00.000Z
+source: git-diff
+status: active
+anchorLine: 3
+baseAnchorHash: sha256:72a7d2a11b2ef199
+-->
+```diff
+diff --git a/.claude/commands/validate.md b/.claude/commands/validate.md
+--- a/.claude/commands/validate.md
++++ b/.claude/commands/validate.md
+@@ -1,4 +1,4 @@
+ # Validate
+ <!-- forge-anchor:stage.validate -->
+-Run checks.
++Run checks carefully.
+```
+<!-- /forge-patch-intent -->
+````
+
+Record IDs are deterministic from the anchor ID and diff body. Recording the same diff replaces the same block instead of appending duplicates.
+
+## Example 1: Basic Edit
+
+1. A managed file declares `<!-- forge-anchor:stage.dev -->`.
+2. The user edits text below that anchor.
+3. `forge patch record --from-diff` writes a record whose `anchorId` is `stage.dev` and whose diff can be reapplied to recreate the edit.
+
+## Example 2: Rename
+
+If `.claude/commands/validate.md` moves to `.codex/skills/validate/SKILL.md` but keeps `<!-- forge-anchor:stage.validate -->`, Forge resolves the record as `renamed` with `currentPath: .codex/skills/validate/SKILL.md`. Later upgrade code can use that resolved path instead of treating the patch as lost.
+
+## Example 3: Orphan
+
+If a record references `stage.ship` and no file declares that anchor, `forge patch status` reports it as orphaned. Later upgrade work should refuse to apply that record automatically and tell the user to re-record or restore the anchor.
+
+## Config
+
+`.forge/config.yaml` may configure patch intent:
+
+```yaml
+patchIntent:
+  enabled: true
+  path: .forge/patch.md
+  anchorAliases:
+    stage.old-validate: stage.validate
+```
+
+- `enabled: false` disables `forge patch record --from-diff`.
+- `path` moves the record file.
+- `anchorAliases` lets renamed anchors resolve without editing historical records.
+
+## Later Upgrade and Rollback Safety
+
+Upgrade can use patch intent records to decide whether a local edit is anchored, moved, or orphaned before touching managed files. Rollback can use the same metadata to explain which user edits were intentionally preserved. This baseline does not implement upgrade application, rollback snapshots, self-heal, marketplace, or adapter behavior.