forge-workflow 0.0.9 → 0.1.0-beta.2

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.

package/docs/reference/HERMES_INTEGRATION.md

@@ -0,0 +1,118 @@
+# Hermes Integration
+
+> Roadmap lane: `forge-2agy.9.7.x` (Hermes adapter)
+
+This document defines how the **Hermes** harness integrates with a Forge
+project, and — most importantly — the boundary between **Forge Kernel state**
+(shared, authoritative, cited) and **Hermes-native memory** (private to a Hermes
+session or profile).
+
+The consumption contract that Hermes sessions follow lives in
+[skills/hermes-forge/SKILL.md](../../skills/hermes-forge/SKILL.md). The storage
+model Hermes reads against is described in
+[FORGE_KERNEL_STORAGE_MODEL.md](FORGE_KERNEL_STORAGE_MODEL.md), and the
+writeback surface in
+[forge-kernel-issue-command-contract.md](forge-kernel-issue-command-contract.md).
+
+## Why a boundary is needed
+
+Hermes carries its own conversational/profile memory. Forge carries the
+project's durable, provenance-tracked state. If Hermes were allowed to write its
+private memory into Forge state, the two would drift: Forge would accumulate
+Hermes-specific context that other harnesses (Claude Code, Codex, Cursor) cannot
+interpret, and the "single source of truth" guarantee behind `forge orient` /
+`forge recap` would erode.
+
+The integration therefore makes Forge state the authority and Hermes a
+**consumer** that writes back only through the same audited CLI surface it reads
+from.
+
+## The two memory tiers
+
+| | Forge Kernel state | Hermes-native memory |
+| --- | --- | --- |
+| **Owner** | Forge | Hermes |
+| **Scope** | The project — shared across all harnesses | One Hermes session / profile |
+| **Authority** | Source of truth | Convenience cache, never authoritative |
+| **Read path** | `forge orient` / `forge recap` (bounded, cited JSON) | Hermes' own store |
+| **Write path** | Forge CLI only (`forge comment`, `forge update`) | Hermes' own store |
+| **Contains** | Issues, decisions, evidence, design snapshots, claims, queues | Prompts, session scratch, user preferences, Hermes profile data |
+| **Provenance** | Every fact carries `{ path, source_kind, authority, role }` | Not part of the Forge provenance graph |
+
+### What lives in Forge Kernel state
+
+Anything that is a **project fact**: issue records, decisions, evidence,
+design-snapshot content, ready queues, and active claims — all written back
+exclusively through Forge CLI commands.
+
+Not all of that state is surfaced by the bounded `forge orient` / `forge recap`
+envelope. Today the envelope emits the project design snapshot, active-work
+artifacts (`docs/work`), and — for `forge recap <issue-id>` — an issue summary;
+ready queue and active claims currently appear as forward-looking kernel
+placeholders. Issue **evidence/comments are not in the envelope** — read them
+from the issue record itself (e.g. `forge show <id>`). Treat orient/recap as the
+bounded entry point, not the exhaustive store.
+
+### What lives in Hermes-native memory
+
+Anything that only matters to **Hermes**: conversational history, session
+scratchpads, per-user preferences, and the Hermes profile itself. None of this
+belongs in Forge Kernel state.
+
+## Authority rule
+
+Forge Kernel state is the single source of truth. When Hermes needs project
+state it MUST obtain it from `forge orient` / `forge recap` (JSON form) rather
+than reconstructing it from raw files or kernel internals. When two sources
+conflict, prefer the higher `authority` and surface the conflict instead of
+silently choosing.
+
+## Writeback rule
+
+Evidence and decisions discovered in a Hermes session flow back into the Forge
+Kernel **only** through Forge CLI commands:
+
+- `forge comment <id> <body...>` — attach evidence, a decision, or a note to an issue.
+- `forge update <id...> [flags]` — update issue state/fields.
+- `forge create [title] [flags]` — open a follow-up issue.
+
+(`forge audit` is verify-only — `forge audit verify` — and is not an
+evidence-append path; record evidence as an issue comment.)
+
+These writes land in the Forge Kernel issue store and become part of the issue's
+durable history. Note the read/write asymmetry: the bounded `forge orient` /
+`forge recap` envelope is assembled from project docs, `docs/work` artifacts, and
+the issue summary — it surfaces issue/design/decision state but does **not** echo
+individual issue comments back. Evidence added via `forge comment` lives in the
+issue history (reachable from the issue record), not necessarily in the next
+orient/recap payload.
+
+## The no-profile-write guard
+
+The hard boundary, enforced as a contract in the `hermes-forge` skill and
+guarded by tests:
+
+> **Hermes MUST NOT write Hermes profile state into Forge Kernel state.**
+
+Concretely, a Hermes session must never:
+
+- Persist Hermes profile or session memory into Forge Kernel storage.
+- Edit Forge state files (design, decision, issue stores) directly to record
+  Hermes-side context.
+- Use the Forge issue/evidence backend as a dumping ground for
+  Hermes-only data.
+
+If a piece of context only matters to Hermes, it stays in Hermes-native memory.
+If it is a project fact, decision, or evidence item, it is written through the
+Forge CLI so it becomes part of the shared, cited source of truth.
+
+## Token-budget & truncation expectations
+
+`forge orient` and `forge recap <issue-id>` emit the deterministically bounded
+envelope (default ~2000 estimated tokens, `chars_per_token: 4`). Truncation
+follows the published `token_budget.truncation_order`, marks trimmed sections
+with `[truncated deterministically by token budget]`, and sets `truncated: true`.
+Hermes treats truncated sections as incomplete and re-requests with a higher
+`--budget` when completeness matters. (Bare `forge recap` — no issue id —
+returns the legacy activity summary, which is not the bounded envelope.) See the
+skill for the full envelope and provenance model.

package/docs/reference/INSIGHTS_RECAP.md

@@ -0,0 +1,63 @@
+# Insights And Recap
+
+`forge insights` and `forge recap` summarize recurring local workflow evidence from existing Forge and Beads state.
+
+## Commands
+
+```bash
+forge insights
+forge insights --review-feedback
+forge insights --min-count 2 --limit 5
+forge insights --json
+forge insights accept <candidate-id> --note "why this is useful"
+forge insights reject <candidate-id> --note "why this is noise"
+forge recap
+forge recap --json
+```
+
+`--review-feedback` is a compatibility alias. In this MVP it reads Beads interactions and issue evidence; it does not infer external review-provider comments.
+
+## Evidence Sources
+
+- `.beads/interactions.jsonl`: field changes and review/close outcome reasons.
+- `.beads/issues.jsonl`: tokenized issue titles and descriptions for themes, plus statuses and timestamps for recap context.
+- `.forge/log.jsonl` and `.forge/audit.log`: optional audit event counts when present.
+- Beads-backed typed memory: accept/reject decisions are recorded through `lib/memory/typed-api.js`.
+
+## What It Can Infer
+
+- Repeated local workflow patterns.
+- Candidate follow-ups based on frequency, source diversity, and evidence count.
+- Recent issue activity and review outcome counts.
+- Whether history is too sparse for a useful suggestion.
+
+## What It Cannot Infer
+
+- Does not prove a workflow is correct.
+- Reviewer intent is not inferred from provider-specific systems.
+- Trusted executable skills are not installed.
+- It does not modify upgrade safety, lockfile/trust policy, patch intent internals, team dashboards, or issue sync surfaces.
+
+## Example Output
+
+```text
+Forge insights
+Sources: interactions=16, issues=260, audit=0
+Ranked candidates:
+- insight-interaction-status-closed-merged-and-verified (55): status changed to closed (merged-and-verified)
+  Next: Review interaction evidence and consider a local workflow skill only if the pattern is still useful.
+Limitations:
+- Insights are local workflow signals, not proof of correctness.
+```
+
+```text
+Forge recap
+Issues: 260 total, 94 open, 166 closed
+Review outcomes found: 4
+Recent work:
+- forge-besw.12: forge insights --review-feedback PoC (Week 1 deliverable) [open]
+Insight candidates:
+- insight-interaction-status-closed-merged-and-verified: status changed to closed (merged-and-verified)
+Limitations:
+- Sparse Beads interactions or missing Forge audit logs reduce confidence.
+```

package/docs/reference/INSTALL.md

@@ -0,0 +1,164 @@
+# Installing Forge
+
+Forge ships two ways to install:
+
+1. **Standalone binary** (this page) — a single compiled executable, no Node or
+   Bun runtime required. Best for a global CLI you run everywhere.
+2. **npm / npx** — the `forge-workflow` package, if you already live in Node and
+   want Forge as a project dev-dependency. See [npm / npx channel](#npm--npx-channel).
+
+Both deliver the same Forge. The binary bundles Forge's own JavaScript, but **not**
+its external prerequisites — see [Prerequisites](#prerequisites).
+
+---
+
+## One-line install
+
+### macOS / Linux
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/harshanandak/forge/master/scripts/install.sh | sh
+```
+
+Install a specific version:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/harshanandak/forge/master/scripts/install.sh | sh -s -- --version v1.2.3
+```
+
+The script detects your OS, CPU architecture and (on Linux) your libc, downloads
+the matching binary from the latest [GitHub Release](https://github.com/harshanandak/forge/releases),
+makes it executable, and installs it to `~/.local/bin/forge`. If that directory
+is not on your `PATH`, the script prints the line to add.
+
+### Windows (PowerShell)
+
+```powershell
+irm https://raw.githubusercontent.com/harshanandak/forge/master/scripts/install.ps1 | iex
+```
+
+Install a specific version (download the script, then run it with an argument):
+
+```powershell
+$s = irm https://raw.githubusercontent.com/harshanandak/forge/master/scripts/install.ps1
+& ([scriptblock]::Create($s)) -Version v1.2.3
+```
+
+This installs `forge.exe` to `%LOCALAPPDATA%\Programs\forge\` and prints how to
+add it to your `PATH`.
+
+After installing, run `forge setup` inside a git repository to wire Forge up for
+your agent.
+
+---
+
+## Supported platforms
+
+Each GitHub Release publishes these assets. The install scripts pick the right one
+automatically; the table is for manual downloads.
+
+| OS | Architecture | libc | Release asset |
+|----|--------------|------|---------------|
+| macOS | Apple Silicon (arm64) | — | `forge-darwin-arm64` |
+| macOS | Intel (x64) | — | `forge-darwin-x64` |
+| Linux | x64 | glibc | `forge-linux-x64` |
+| Linux | arm64 | glibc | `forge-linux-arm64` |
+| Linux | x64 | musl (e.g. Alpine) | `forge-linux-x64-musl` |
+| Linux | arm64 | musl (e.g. Alpine) | `forge-linux-arm64-musl` |
+| Windows | x64 | — | `forge-windows-x64.exe` |
+
+On an unsupported platform the install script fails with a clear message. Use the
+[npm / npx channel](#npm--npx-channel) instead.
+
+---
+
+## Manual download and run
+
+If you prefer not to pipe a script to your shell, download the asset for your
+platform directly from the [latest release](https://github.com/harshanandak/forge/releases/latest)
+and run it.
+
+Every release also publishes a `checksums.txt` (SHA-256) manifest. **Verify the
+asset before you run it** — the one-line install scripts do this automatically.
+
+### macOS / Linux
+
+```sh
+# Pick the asset for your platform from the table above (here: linux x64 glibc)
+curl -fsSL -o forge \
+  https://github.com/harshanandak/forge/releases/latest/download/forge-linux-x64
+
+# Verify integrity against the release manifest before running:
+curl -fsSL -o checksums.txt \
+  https://github.com/harshanandak/forge/releases/latest/download/checksums.txt
+grep ' forge-linux-x64$' checksums.txt | sha256sum -c -   # must print "forge-linux-x64: OK"
+
+chmod +x forge
+./forge --version
+# Optionally move it onto your PATH:
+mkdir -p ~/.local/bin && mv forge ~/.local/bin/forge
+```
+
+On macOS use `shasum -a 256 -c -` in place of `sha256sum -c -`.
+
+### Windows (PowerShell)
+
+```powershell
+irm https://github.com/harshanandak/forge/releases/latest/download/forge-windows-x64.exe -OutFile forge.exe
+
+# Verify integrity against the release manifest before running:
+irm https://github.com/harshanandak/forge/releases/latest/download/checksums.txt -OutFile checksums.txt
+$expected = ((Get-Content checksums.txt) -match ' \*?forge-windows-x64\.exe$') -replace '\s.*$',''
+if ((Get-FileHash -Algorithm SHA256 forge.exe).Hash -ieq $expected) { "OK" } else { throw "checksum mismatch" }
+
+.\forge.exe --version
+```
+
+A pinned version uses the same URLs with `download/<tag>/` instead of
+`latest/download/`, e.g.
+`https://github.com/harshanandak/forge/releases/download/v1.2.3/forge-linux-x64`.
+
+---
+
+## npm / npx channel
+
+If you already have Node.js, you can skip the binary entirely:
+
+```sh
+# Global install
+npm i -g forge-workflow
+forge --version
+
+# Or run once without installing
+npx forge-workflow status
+
+# Or as a project dev-dependency (recommended for teams)
+bun add -D forge-workflow   # or: npm install --save-dev forge-workflow
+bunx forge setup --agents claude --yes
+```
+
+The npm package and the standalone binary are the same Forge and stay in lockstep
+on every release.
+
+---
+
+## Prerequisites
+
+The binary bundles Forge's JavaScript, but relies on a few external tools being
+installed and on your `PATH`:
+
+- **git** — required for all repository operations.
+- **gh** (GitHub CLI) — required for the PR / review workflow.
+- **Git Bash** (Windows only) — Forge's helper-backed stage flows run under Git
+  Bash on Windows.
+
+These are runtime prerequisites checked by `forge`'s own health checks; the
+installer does not install them for you.
+
+---
+
+## Uninstall
+
+- Binary: delete the installed file (`~/.local/bin/forge`, or
+  `%LOCALAPPDATA%\Programs\forge\forge.exe` on Windows).
+- npm: `npm rm -g forge-workflow`.

package/docs/reference/KERNEL_TAXONOMY_VALIDATION.md

@@ -0,0 +1,161 @@
+# Kernel Taxonomy, Readiness, and Validation
+
+Reference for the Forge Kernel issue taxonomy collapse and its read-model/validation
+layer, implemented per **D18** (see
+[`docs/work/2026-06-06-kernel-backlog-memory-roadmap/decisions.md`](../work/2026-06-06-kernel-backlog-memory-roadmap/decisions.md))
+and roadmap items `forge-2agy.9.2.1`, `.9.2.2`, `.9.2.6`, `.9.2.7`, `.9.2.8`, `.9.2.9`.
+
+The four planning axes are kept **separate** (D5): stored **status**, parent/child
+**hierarchy**, sprint/release planning **bucket**, and workflow **stage** execution. A
+task can be in a sprint, have a parent epic, be derived-ready, and currently sit in the
+`validate` stage — these are not the same field.
+
+---
+
+## 1. Issue types (4) — `lib/kernel/taxonomy-validator.js`
+
+A type only earns existence if it changes Kernel behavior (routing, gates, board
+grouping, rollup). `feature`, `story`, `chore`, and `spike` are **labels**, not types.
+
+| Type | `canParent` | `claimable` | `blocksOthers` | `rollup` | Board group |
+| --- | --- | --- | --- | --- | --- |
+| `epic` | ✅ (only container) | ❌ | ❌ | ✅ | `roadmap` |
+| `task` | ❌ | ✅ | ❌ | ❌ | `backlog` |
+| `bug` | ❌ | ✅ | ❌ | ❌ | `backlog` |
+| `decision` | ❌ | ❌ | ✅ (gates dependents) | ❌ | `decisions` |
+
+`TYPE_BEHAVIORS` is the single source of truth for these mappings. Enums are enforced at
+the **validation layer**, not as DB constraints, so label-based extensibility and derived
+readiness stay outside the stored column set.
+
+## 2. Status lifecycle (5 stored)
+
+Stored statuses: `open`, `in_progress`, `review`, `done`, `cancelled`.
+
+```text
+open ──► in_progress ──► review ──► done
+ ▲           │             │
+ └───────────┘             │   (rework: review ──► in_progress, in_progress ──► open)
+open / in_progress / review ──► cancelled        (done, cancelled are terminal)
+```
+
+`STATUS_TRANSITIONS` encodes the legal moves. `validateStatusTransition(from, to)` throws
+a `TaxonomyValidationError` for illegal moves and unknown statuses; a same-status
+transition is treated as an idempotent no-op. `done` and `cancelled` are terminal — no
+transition leaves them.
+
+## 3. Derived readiness — `lib/kernel/readiness-model.js`
+
+`ready` and `blocked` are **derived read-model facts, never stored statuses** (D18). A
+blocker that clears makes the issue ready again in whatever stored status it held — there
+is no "preserve previous status" hack. `backlog` is the fallback summary state when an
+issue is neither terminal nor ready/blocked/gated/deferred/claimed/disabled — for example
+`open` with readiness conditions unmet, or a non-workable status such as `review`.
+
+`deriveReadiness(issue, context)` returns:
+
+```json
+{
+  "id": "forge-1",
+  "status": "open",
+  "ready": true,
+  "blocked": false,
+  "blocked_by": [],
+  "reasons": [],
+  "state": "ready"
+}
+```
+
+Readiness policy considers: blocking dependencies (upstream not in a terminal status —
+`done` and `cancelled` both clear, so a cancelled blocker never wedges a dependent),
+unresolved decision dependencies, projection **quarantine**/conflicts, required workflow
+**gates**, **defer** windows, **policy-disabled** work, and an **active conflicting
+claim** by another actor. Reason codes (`READINESS_REASONS`): `dependency` (carries a
+`decision: true` flag when the blocker is a decision issue), `quarantine`, `conflict`,
+`gate`, `claimed`, `deferred`, `policy_disabled`.
+
+**Acceptance-criteria and due-date readiness** are modeled through the generic `gates`
+input (an acceptance/definition-of-ready gate, or a due-window gate the caller supplies),
+not as separate hardcoded field checks — so the policy stays open to caller-defined gates
+without the read model owning every "definition of ready" rule.
+
+Summary `state` (precedence high→low): `closed` → `blocked` → `gated` → `deferred` →
+`claimed` → `disabled` → `ready` → `backlog`. `blocked` (dependencies/quarantine/conflict)
+always outranks softer not-ready reasons. Because the single `state` collapses multiple
+conditions, consumers picking next work should read the full `reasons[]` — e.g. a claim
+hidden behind a defer window is in `reasons[]` even when `state` reports `deferred`.
+Terminal issues are `closed` — neither ready nor blocked.
+
+`buildReadinessIndex({ issues, dependencies, claims, conflicts, gates, now, actor,
+policyDisabledIds })` computes readiness for a whole board, resolving each dependency's
+status from the issue set and returning a `readyQueue` ordered by authoritative numeric
+rank then id, plus the `blocked` id list. The ready-work queue excludes terminal,
+deferred, gated, policy-disabled, and claimed-by-other issues.
+
+## 4. Validation layer — `lib/kernel/taxonomy-validator.js`
+
+| Function | Enforces |
+| --- | --- |
+| `validateIssueTaxonomy(issue)` | type/status enum membership; rejects self-parent |
+| `validateStatusTransition(from, to)` | status lifecycle rules (throws) |
+| `findDependencyCycles(deps)` / `assertAcyclicDependencies(deps)` | dependency graph acyclicity (only `blocks` edges) |
+| `validateParentChild(issue, parent)` | parent exists, parent type `canParent`, no self-parent |
+| `findParentCycle(issuesById, startId)` | parent-chain cycle detection |
+| `validateClaim(claim, { now, issueType })` | actor present, valid claim state, claimable type, lease not expired |
+| `validateActiveClaimUniqueness(claims)` | at most one active claim per issue |
+
+These complement (do not replace) the broker/DB claim-lease invariants enforced
+elsewhere; the validation layer is the pure, storage-agnostic checker.
+
+## 5. Priority rank vs P0–P4 projection
+
+A single numeric rank is authoritative for ordering; **P0–P4 is a display projection
+only** (D18). `rankForPriorityLabel(label)` ingests a label/number to the authoritative
+rank; `priorityLabelForRank(rank)` projects a rank to a display label clamped to `P0..P4`;
+`normalizeRank(value)` coerces to a non-negative integer.
+
+## 6. Planning bucket entities — `lib/kernel/planning-buckets-schema.js`
+
+Sprint, release, and milestone are first-class Kernel entities (`forge-2agy.9.2.7`), not
+string fields on issues. Each table (`kernel_sprint`, `kernel_release`,
+`kernel_milestone`) carries `id`, `name`, `state`, `rank`, owner/goal, dates,
+`entity_revision`, and **read-model rollup counters** (`total_count`, `completed_count`).
+The schema reuses the shared `lib/kernel/schema.js` builders and passes
+`validateKernelSchema`; `getPlanningBucketsSchema()` is migration-renderable through the
+existing `buildSchemaMigration` renderer.
+
+State vocabularies:
+
+- Sprint: `planned`, `active`, `completed`, `cancelled`
+- Release: `planned`, `in_progress`, `released`, `cancelled`
+- Milestone: `planned`, `reached`, `missed`, `cancelled`
+
+The extended `kernel_issues` columns wire issues to these buckets and to hierarchy and
+stage: `parent_id` (self-referencing), `sprint_id`, `release_id`, `stage_state`,
+`labels`, `acceptance_criteria`, `estimate`.
+
+## 7. Board rank and mutation event model
+
+Frontend drag/drop and assignment operations must produce Kernel events carrying
+`expected_revision` and `idempotency_key` (`forge-2agy.9.2.6`). `BOARD_MUTATION_EVENT_TYPES`:
+
+- `issue.reordered` — board rank change. Per D18 there is a **single** authoritative
+  numeric ordering rank (`priority_rank`); P0–P4 is its display projection. There is no
+  separate board-only rank column.
+- `issue.status_changed`
+- `issue.sprint_assigned`
+- `issue.release_assigned`
+- `issue.blocked` / `issue.unblocked` — recorded transitions of the derived readiness
+  edge, emitted for audit; readiness itself remains computed, not stored
+- `issue.type_changed`
+
+Each event is validated optimistically against the entity's current revision and is
+idempotent on replay, consistent with the Kernel event/outbox contract.
+
+## Board views (frontend implications)
+
+- **Backlog board** — group by `type`, `priority`, `parent_id`, `release_id`.
+- **Sprint board** — group by `sprint_id` and status.
+- **Ready-work queue** — `buildReadinessIndex(...).readyQueue` (derived).
+- **Agent work view** — filter by claim actor, lease, worktree/session, and `stage_state`.
+- **Roadmap view** — group epics by release/milestone with child rollups.

package/docs/reference/PROTECTED_PATH_MANIFEST.md

@@ -0,0 +1,25 @@
+# Protected Path Manifest
+
+Forge uses `.forge/protected-paths.yaml` as the canonical protected-path contract for the schema and integrity rail.
+
+The manifest defines seven W1 categories:
+
+- `forge_core`: checksum-verified Forge runtime files.
+- `user_protocol`: user-facing protocol files that should be changed through Forge CLI surfaces.
+- `generated_artifacts`: generated harness files that should come from renderers.
+- `append_only_logs`: audit logs that must not be rewritten.
+- `secrets`: env and secret-bearing files.
+- `beads_state`: Beads state owned by `bd` or Forge issue adapters.
+- `immutable`: VCS/runtime internals owned by their tools.
+
+## Harness Enforcement
+
+Claude and Codex use native hook contracts for write/edit enforcement. Cursor fallback remains Forge CLI/pre-commit or file-watcher enforcement until a native Cursor hook surface is proven by fixture evidence.
+
+## Evidence Command
+
+```bash
+node scripts/spikes/protected-path-manifest.js
+```
+
+The command emits machine-readable JSON containing the manifest categories, per-harness enforcement mapping, validation result, and known issue for Cursor fallback.