forge-workflow 0.1.0-beta.5 → 0.1.0-beta.7

package/AGENTS.md

@@ -118,6 +118,10 @@ Task 2: Validation logic
   ✓ Quality review: ✅
 ```
 
+**Flaky tests:** a test that changes result without the code changing gets
+quarantined and an issue filed — never retried until green. Register it in
+`test/QUARANTINE.md`. Reviewers reject a "re-run CI" as a fix.
+
 ## State Management (Single Source of Truth)
 
 **Current implementation**: The Forge Kernel is the sole issue-state authority — every issue command reads and writes the kernel store, with no backend to select. Beads exists only as an inbound migration path: `forge migrate --from beads` imports an existing Beads store into the kernel once, and no Forge command depends on Beads at runtime. **Direction (D45)**: the Kernel owns issue/workflow/run authority outright; Beads is retired as a live feature. New authority work must follow [docs/work/2026-04-28-skeleton-pivot/forge-kernel-authority-control-plane.md](docs/work/2026-04-28-skeleton-pivot/forge-kernel-authority-control-plane.md) and [docs/reference/FORGE_KERNEL_STORAGE_MODEL.md](docs/reference/FORGE_KERNEL_STORAGE_MODEL.md).

package/CHANGELOG.md

@@ -7,6 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 > **Note**: `/check` was renamed to `/validate` and `/merge` was renamed to `/premerge` in v0.0.3. Historical entries below may use the old names.
 
+## [0.1.0-beta.7] - 2026-09-11
+
+### Changed
+
+- **A clean full validation is reused by the next unchanged `forge push`.** Forge stores a one-hour, signed local receipt bound to the canonical worktree, exact HEAD, clean state, Forge, Bun, and Node runtimes, and complete nonzero gate results. Branch protection and lint still run; invalid or stale evidence falls back to the full suite, while raw Git pushes and CI remain independent.
+- **A local full suite no longer reruns its already-included E2E directory.** Targeted E2E execution is unchanged, while full validation avoids an exact duplicate. (issue `4aed2cc8-57eb-451b-bb3a-02bbdd93af49`)
+- **The shared public contract package is now `@forge/contracts`.** The product-neutral name replaces the former unpublished Memory-qualified name before beta.7, and all three scoped packages explicitly publish as public MIT packages linked to the public Forge repository. (issue `4d41ffb7-8793-4a17-a30b-92130db69672`)
+
+### Fixed
+
+- **The npm package now includes every internal runtime workspace.** Root runtime imports use the `@forge/memory`, `@forge/contracts`, and `@forge/flow` package boundaries, and npm bundles those unpublished workspaces into `forge-workflow`. The installed-package smoke accepts npm 10 lifecycle output before its JSON payload, so Node 22 verifies the same package correctly. A fresh packed install now runs `forge --version` and `forge setup --quick --yes`, preventing the `MODULE_NOT_FOUND` failure in v0.1.0-beta.6. (issue `95372af8-da00-42e0-af64-0111ddab3405`)
+
+## [0.1.0-beta.6] - 2026-09-11
+
+### Added
+
+- **Optional repository-scoped GitHub account context.** Adds clone-local `github.account` binding, native GitHub CLI named-account retrieval, live identity verification, child-only credential scoping across Forge GitHub routes, and concurrent launcher isolation without changing global authentication, Git authorship, or transport configuration. (#554, issue `ee4869d5-77af-4959-909c-190e99b3ada0`)
+- **Dormant Shepherd owner-authority foundation.** Adds the composite-key Kernel schema, migration gate, and bounded transactional owner API without changing any production watcher, daemon, lease, monitor, or command caller. The atomic caller cutover remains isolated in the dependent PR. (#540, issue `ca693a15-c430-404b-9e97-7de59b529eee`)
+- **Atomic Shepherd watcher-authority cutover.** Routes direct, adopt, child, and daemon watcher lifecycles through the Kernel owner row and exact-complete migration gate; reduces the singleton lease to election only; and removes persisted PID, lease-watcher, generation-marker, cleanup-marker, and in-memory authority writers. (#541, issue `700c07c3-e06d-48ed-9b24-229cd7872069`)
+- **Public receipt-bound PR lifecycle authority.** `@forge/memory` now issues exact-head WorkPackets, authenticates RunReceipts, durably links exact `pr.opened` evidence through public Kernel provider seams, requires and rechecks live session-bound ownership and authoritative readiness, preserves Kernel ready order, and fails closed on replay conflicts, stale evidence, unsafe paths, provider loss, and unbounded operations. External merge and terminal `pr.merged` linkage remain owned by the guarded Forge merge path; canonical LeaseReceipt epochs remain explicitly deferred for 0.1. (issue `c2a3c655-ade2-4156-a8dc-e6b4ee2827ad`)
+- **Human-gated legacy claim repair.** Adds a fixed-time, privacy-safe claim preflight, separately restored SQLite backup proof, and exact-digest `BEGIN IMMEDIATE` repair with terminal precedence, null-expiry preservation, CAS drift rejection, idempotent receipts, and interruption rollback. The operator-only script is never run at startup. (PR #528, issue `0fd8b8c1-686c-4808-8d99-f9ed5b9571de`)
+- **Memory recall and session-attention stabilization.** Typed recall now filters before limits, superseded notes hide by default but remain recoverable, Claude read-attention injects only fenced path-matched notes, and session-summary reminders remain current and idempotent. (#504, issue `0874844f-9c0c-449a-994e-a804fe3fc3a5`)
+- **Frozen beta.5 compatibility evidence.** Adds a content-hashed v0.1.0-beta.5 contract and state corpus, privacy-safe inventory, isolated backup/restore proof, and deterministic non-mutating migration dry-run results for Windows and Linux-safe paths. (#498, issue `5dad8dbf-1c49-444d-a407-a48583537817`)
+- **Forge 0.1.0 control-plane foundations.** Adds executable issue-readiness contracts, dead-run claim reconciliation, issue-scoped approval receipts, Kernel-authoritative plan snapshots, fail-closed risk-to-test selection, and distinct npm beta, RC, and stable release channels. (#497; issues `4ee7f9a9-4fa0-42c1-bd96-96638cc9feff`, `9b69a551-f5a0-4057-9d9f-96fb0d744fd3`, `b977b0a2-11f6-40d7-a230-8e2ff5f79115`, `b811a974-a866-47e0-8f83-3f5d2423aded`, `7a6a3fb3-c82c-48e7-86ee-630c171b924c`, `3e46debd-11c3-4b1c-b59a-17304c37cb03`)
+- **Deterministic Bun lockfile ownership.** Protected-state validation can approve a staged root `bun.lock` only when pinned Bun reproduces its exact bytes from captured staged package manifests: first from the committed lock, then from a clean no-lock state only after an exact byte mismatch. Index races, tampering, unsafe paths/configuration, tool drift, and environment-seam hiding fail closed. (issue `a6c52ac8-6f80-4f2d-8d3c-d83eb92becbd`)
+
+### Fixed
+
+- **Legacy claim repair now compares exact Windows file identities and timestamps.** BigInt filesystem metadata prevents rounded device/inode collisions from treating distinct files as aliases, while nanosecond timestamps keep recovery-state drift checks fail closed. (#556, issue `7e164066-4d41-4d14-90ef-1b7ee14e2b73`)
+- **Dep-guard apply-decision tests no longer contend with shared Windows subprocess shards.** The process-heavy suite now uses the existing exclusive resource lane, with exact scheduler coverage and no timeout increase or exemption. (issue `762ae565-0059-4827-9c3d-b4249f2b3364`)
+- **Bun workflow proof tests no longer contend with shared full-suite shards.** The process-heavy commit-boundary proof now uses the existing exclusive resource lane, with exact scheduler coverage and no timeout increase or exemption. (#552, issue `2daab8c0-34d6-4378-8cf4-dce6fdbfb86b`)
+
+- **The protected-state pre-commit check is now merge-aware.** While a merge is in progress (per-worktree `MERGE_HEAD`), a staged protected path is exempt only when its full staged index entry (mode, object type and object id) is identical to that path's entry on `HEAD`, or on a `MERGE_HEAD` contained in the repository's canonical upstream ref (the base remote — `upstream` preferred over `origin`, the same resolution `/ship` uses to pick a PR base, then that remote's default branch) — content already published on the official base rather than on a contributor's fork. The base-remote resolver now lives in `lib/base-remote.js` and is shared with `/ship`, so a change merged from a fork's default branch but never published upstream stays blocked — content already published on the line this repo integrates into, carried in by the merge rather than edited. A local-only branch, an untrusted contributor remote, or a hand-created `refs/remotes/*` ref earns no exemption, an unresolvable `HEAD` grants no exemption context at all, `bun.lock` still requires its regeneration proof, paths differing from every trusted revision stay blocked, the non-merge path is unchanged, and any failed git query fails closed. (issue `f6d43eb1-249d-4d81-b679-32502ffa28c2`)
+- **Worktree dependency repair now covers Bun workspace shapes and reused worktrees.** Workspace discovery accepts array and object-form manifests plus wildcard and exact paths, reused worktrees revalidate dependencies before returning, and full-suite stderr tails redact complete lines before bounded retention. (#550, issue `465f7e62-1928-4bcf-97a5-c2db05504a7e`)
+- **Validation and dependency recovery gates are reproducible and fail closed.** The protected-state hook now accepts either an exact pinned-Bun transition from the committed lock or an exact clean no-lock regeneration after that transition mismatches; the regenerated lock clears all dependency advisories, every active Bun execution surface is pinned to 1.4.2, and `forge validate` gives the full suite measured capture headroom while distinguishing numeric skipped-test counts from an entirely skipped check. (#551; issues `95ed6f9c-6f23-41f4-9bc4-13177a96ccf2`, `1f7baefc-c9cc-4acf-9cad-e98c53f308ba`, `cfffed63-51dd-4145-acb2-a18f41ef2846`)
+- **Bare conditional merge no longer blocks on intentionally skipped optional checks.** `checks_green` now partitions the authoritative protected context/application set from optional check runs: protected and explicit `only` checks remain strict `SUCCESS`, while terminal optional `NEUTRAL` and `SKIPPED` results no longer block. Missing, malformed, unsafe, and nonterminal evidence still fails closed. (#549, issue `fa805e7e-e718-438f-a776-bd860c80e99a`)
+- **The full-suite worker budget now weights subprocess workers by real process cost.** A subprocess-lane worker owns two Windows processes (its own bun runtime plus the `bun.exe` grandchild its tests spawn), so granting three of them on a 4-vCPU runner oversubscribed the box and produced wall-clock-only failures. Grants are now made against the budget by cost (subprocess/exclusive = 2 units on `win32`, 1 elsewhere; unit = 1), the strongest lane always keeps one worker so the schedule can never stall at zero, and the plan log prints the *granted* concurrency plus the cost and budget instead of the nominal lane concurrency. Non-Windows scheduling is unchanged. (issue `9b8dfa31-4a76-4ef2-b7e9-331d248e3850`)
+- **`forge push` no longer kills a passing full test suite.** The pre-push test run is budgeted from the shared full-suite budget in `scripts/test.js` instead of a hardcoded 120s cap, and that shared budget is raised from 10 to 25 minutes — the previous default sat *below* the measured healthy runtime (602.43s for 8038 tests on Windows), so it SIGKILLed good runs. The ceiling now carries >2x headroom because it exists to catch an indefinite hang, not to bound normal runtime; `FORGE_TEST_TIMEOUT_MS` still overrides. A run terminated by a timeout, signal, or spawn error now reports what happened instead of failing with no summary. (issue `e26dbb91-0443-4e53-946e-a9941ec30ca3`)
+- **The targeted PR lane's full-suite fallback now uses the lane-aware runner.** When the execution planner returns `mode=full`, the follow-up job runs `scripts/test-full-suite.js` instead of a raw `bun test test/`, so subprocess-heavy files get resource-lane separation and the worker budget the full matrix already had — closing the Windows-only spawn failures that hit only this lane.
+- **Full-suite validation now respects the computed worker budget.** Resource-aware lanes share the reserved worker pool by default, and `forge validate` uses that runner when available, preventing mixed unit and subprocess shards from oversubscribing Windows runners. (PR #545, issue `8cb52d50-24ea-4c69-8579-b30a0f1ee467`)
+- **Windows legacy-claim repair now preserves owner-only ACL guarantees without PowerShell transport stalls.** The operator-only repair path uses bounded, privacy-safe Windows security-descriptor verification, exact owner/DACL replacement, Unicode-safe targets, transaction-isolated async hardening, and fail-closed timeout cleanup. (#538, issue `eb2c56e8-5054-4542-8f02-3f9fe635fd2d`)
+- **Local full-suite validation is deterministic under Windows process pressure.** Resource-aware lanes, runtime-balanced subprocess shards, isolated coordination state, direct commitlint execution, batched Flow-monitor replay, and exact failure attribution remove rotating shared-state and child-process flakes without weakening timeouts or gates. (#538; issues `51672736-3387-4d0f-950d-4ae6e5e2c13e`, `9eb98ac0-ebe1-4604-a57a-5fefadad6682`)
+- **PR lifecycle acceptance fails closed at its authority and privacy boundaries.** Every opened linkage write now proves exact live claim ownership, timed-out persistence reconciles only through bounded durable trace evidence, and bare POSIX user-home paths are rejected before WorkPacket publication. (#530, issue `50571aa3-b1cd-42f4-9c50-2c7576d1b0d4`)
+- **Official skill-mirror writes retain protected-state authority.** The canonical `.agents/skills` sync now uses one-time, actor/path/content/source-HEAD/worktree-bound authorization and completion receipts, verifies byte equality with `skills/`, and continues to deny direct, stale, replayed, or foreign writes. (issue `209d80bc-f521-4947-9953-e5b5bf7020f6`)
+- **Workspace lockfile proofs are path-independent.** Bun regeneration now receives the isolated proof root explicitly, preventing temporary proof paths from leaking into workspace keys. (issue `3eb1db42-eaa3-4847-9878-7b77310d1beb`)
+- **Windows lockfile proofs canonicalize temporary roots.** Native path resolution prevents 8.3 TEMP aliases from changing regenerated lock bytes. (issue `3eb1db42-eaa3-4847-9878-7b77310d1beb`)
+- **Linked-worktree lockfile proofs no longer mutate shared Git configuration.** Internal proof Git commands discard inherited repository-local Git environment variables while preserving the host toolchain environment. (issue `93cb615f-2e6e-45ff-90c1-6c98e47f0fff`)
+
 ## [0.1.0-beta.5] - 2026-08-09
 
 ### Added

package/CLAUDE.md

@@ -1,13 +1 @@
-# Project Instructions
-
-Forge uses **[AGENTS.md](AGENTS.md)** as the single source of truth for all agent
-instructions: the workflow template, change classification, detailed stage
-instructions, git hooks and push workflow, build/shell/MCP toolchain, issue
-tracking, project learnings, and session completion. This file intentionally
-holds no content of its own — it only loads AGENTS.md.
-
 @AGENTS.md
-
-> **IMPORTANT**: Read [AGENTS.md](AGENTS.md) using the Read tool at the start of
-> every session to load the current Forge workflow contract. AGENTS.md is
-> authoritative; do not duplicate its content here.

package/CODING_STANDARDS.md

@@ -0,0 +1,72 @@
+# Coding Standards (read at review time)
+
+This file is **not** loaded every turn. It is read by the review step — the
+`/review` stage, the `code-review` skill, and any human or bot reviewing a diff —
+and nowhere else. Everything here is a property a reviewer can check **by reading
+the diff**. Rules about how an agent shapes its turn (arm the shepherd, work in a
+worktree, don't stall, don't poll on a fixed timer while waiting) live in
+[AGENTS.md](AGENTS.md), because no diff shows them.
+
+**How to add to it:** when you catch an agent (or yourself) doing something wrong
+in a change, add one line here, stated positively, with an evidence tag naming
+where the evidence came from — `[mined: <cluster> ×N]` for the transcript-mining
+counts, `[git: <pattern>]` for repository history, `[incident: <what happened>]`
+for a single concrete failure. No rule without evidence; delete a rule when its
+evidence stops recurring.
+
+---
+
+## Scope
+
+1. Every file in the diff is one the originating issue or design doc named; an
+   unrelated fix found along the way gets its own issue and its own PR.
+   `[mined: scope creep — unrelated fixes into the PR ×6]`
+2. A follow-up noted in the diff cites a kernel issue id, not a bare `TODO` or
+   `FIXME`. `[mined: discussed work not filed as kernel issue ×3]`
+
+## Gates and tests
+
+3. A failing check is fixed at its cause; the diff does not raise a timeout,
+   add a skip, loosen a threshold, or replace a real assertion with a vacuous
+   one to get green. `[mined: weakening gates/tests to pass ×3]`
+4. Tests synchronize on an observable condition (poll until true, await the
+   event), never on a fixed sleep or timer duration.
+   `[mined: waiting a fixed 10 min when reviewers already settled ×2]`
+5. A new or moved source path that needs targeted tests lands in both the
+   targetability checks in `scripts/test.js` and the `DIRECT_TEST_CANDIDATES`
+   mapping in `lib/commands/test.js`, so it does not silently fall into the
+   full-suite lane.
+   `[mined: slow test/CI lanes accepted as normal ×3]` `[git: 13 fix commits touch scripts/test.js]`
+
+## Generated artifacts and single source of truth
+
+6. Skills are edited in the canonical `skills/` tree and mirrors are regenerated
+   by `scripts/sync-agent-skills.js`; the diff never hand-edits `.agents/skills/`
+   or another generated mirror.
+   `[mined: duplicating skills per agent instead of skill-CLI generation ×4]`
+   `[incident: recurring skills-sync-drift failures]`
+7. Adding, deleting, or renaming a `lib/commands/*.js` file includes the
+   regenerated command manifest (`scripts/gen-command-manifest.js`) in the same
+   diff. `[git: 24 fix commits touch bin/forge.js, 15 touch lib/commands/setup.js]`
+
+## Product boundary
+
+8. Issue authority reads and writes go through the kernel; the diff adds no code
+   path that treats Beads or Dolt as a live backend.
+   `[mined: treating beads as live backend ×5]` `[decision: D45 retires Beads as a live feature]`
+9. Shipped code discovers its own paths and config; no maintainer machine path,
+   local username, or personal directory appears in a committed file.
+   `[incident: hardcoded C:\Users\<user>\Downloads\forge in .claude/settings.json]`
+10. A new runtime asset the installed package needs is added to the `files`
+    allowlist in `package.json` in the same diff.
+    `[incident: protected-paths.yaml missing from the npm files allowlist]`
+11. PR-monitoring capability is wired into the substrate — a hook, the ship
+    path, or a gate — not left as a step someone must remember to invoke.
+    `[mined: shepherd not armed/auto-attached on ship ×10]`
+
+## Repository hygiene
+
+12. Machine-local runtime state (per-session caches, saved PR diffs, symlinks
+    into worktrees, stray shell artifacts, and transient kernel .export.lock /
+    .tmp-* files) is gitignored, never committed. Deterministic .forge/kernel/
+    JSONL and manifest projections are tracked export/import artifacts. `[git: triage 2026-08-15 found NUL, gw/, .hermes/, .forge/kernel/, pr*.diff untracked at repo root]`

package/bin/forge.js

@@ -1696,6 +1696,13 @@ function ensureDirWithNote(dir, purpose) {
 
 // Setup core documentation and directories
 function setupCoreDocs() {
+  // Review skills reference this root contract in every installed repository.
+  // It is a consumer-owned extension point after creation, so setup never overwrites it.
+  const codingStandardsDest = path.join(projectRoot, 'CODING_STANDARDS.md');
+  if (!fs.existsSync(codingStandardsDest)) {
+    copyFile(path.join(packageDir, 'CODING_STANDARDS.md'), 'CODING_STANDARDS.md');
+  }
+
   // docs/planning/ and docs/research/ are created lazily on first use
   // by /plan Phase 1 and Phase 2 respectively, via ensureDirWithNote().
   // TEMPLATE.md and PROGRESS.md are also deferred to first use.
@@ -2354,6 +2361,9 @@ function parseFlags() {
   for (let i = 0; i < args.length;) {
     const arg = args[i];
 
+    // Everything after the explicit launcher delimiter belongs to the child.
+    if (arg === '--' && args[0] === 'github' && args[firstPositionalIndex(args, 1)] === 'run') break;
+
     if (arg === '--quick' || arg === '-q') {
       flags.quick = true;
       i++;
@@ -3480,8 +3490,9 @@ function dryRunSetup(agents) {
     }
   }
 
-  // AGENTS.md
+  // Root policy files
   addFileAction('AGENTS.md', 'Copy workflow documentation');
+  addFileAction('CODING_STANDARDS.md', 'Install Forge coding standards');
 
   // Per-agent planned actions
   for (const agentKey of agents) {

package/docs/guides/MIGRATION.md

@@ -1,6 +1,6 @@
 # Migration Guide
 
-Use this guide when moving older Forge docs, habits, or installed scaffolding toward the v0.1.0-beta.5 public framing.
+Use this guide when moving older Forge docs, habits, or installed scaffolding toward the v0.1.0-beta.7 public framing.
 
 ## What Changed
 
@@ -39,8 +39,8 @@ forge setup --agents claude,cursor
 
 ## Version Labels
 
-- `0.1.0-beta.5` is the current prerelease package version.
-- `0.1.0-beta.4` is the previous prerelease package version.
+- `0.1.0-beta.7` is the current prerelease package version.
+- `0.1.0-beta.6` is the previous prerelease package version, but its npm tarball omits required runtime workspaces; upgrade directly to beta.7.
 - Internal labels such as `0.0.19` or `v3` describe roadmap slices or historical codenames. Do not present them as current package versions.
 
 ## Safe Upgrade Path

package/docs/reference/FORGE_KERNEL_STORAGE_MODEL.md

@@ -79,6 +79,10 @@ Forge Kernel local mode uses a builtin SQLite runtime driver. Driver selection m
 
 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.
 
+Legacy claim contradictions are handled only by the explicit, human-gated
+[legacy claim repair](./LEGACY_CLAIM_REPAIR.md). The broker never starts or applies
+that repair automatically.
+
 ## Team Mode
 
 Team mode requires server authority.

package/docs/reference/INSTALL.md

@@ -155,6 +155,10 @@ installed and on your `PATH`:
 These are runtime prerequisites checked by `forge`'s own health checks; the
 installer does not install them for you.
 
+Using personal and work GitHub accounts together? See the optional
+[per-clone GitHub account guide](github-accounts.md). Ordinary single-account
+setup is unchanged.
+
 ---
 
 ## Uninstall

package/docs/reference/LEGACY_CLAIM_REPAIR.md

@@ -0,0 +1,112 @@
+# Legacy Claim Repair
+
+This is an explicit operator tool for the one-time pre-0.1.0 reconciliation of
+legacy Kernel claim rows. It is not called by setup, startup, broker migrations,
+claim acquisition, or any background process.
+
+## Safety contract
+
+- Always use an explicit, file-backed database path and a different backup path.
+- The observation time is mandatory and must be one canonical UTC instant. Reuse
+  that literal time for approval and apply.
+- Dry-run does not mutate Kernel authority. It creates a separate SQLite backup,
+  restores that backup into an isolated temporary database, and requires the
+  restored snapshot digest to equal the source preflight digest. On POSIX
+  systems, both the temporary and final backup are forced to owner-only `0600`
+  permissions before the backup is accepted. On Windows, inherited access is
+  removed and a private DACL for the current operator is applied and verified.
+- The digest covers the complete Kernel database schema and every row in every
+  authority table, while the report exposes only the digest and aggregate claim
+  counts. Any intervening Kernel write invalidates approval.
+- Preflight fails closed on integrity, foreign-key, schema/index, duplicate-row,
+  state, timestamp, read faults, or active claims attached to unclaimable issue
+  types.
+- Apply requires the human-approved exact digest and the verified backup. It
+  acquires `BEGIN IMMEDIATE`, re-reads the complete repair snapshot, rejects any
+  digest drift, and compare-and-swaps every exact row before committing one
+  privacy-safe receipt.
+- Terminal issue state wins over expiry: its active claim becomes `released`.
+  An expired active claim on nonterminal work becomes `reclaimable`. Valid
+  unexpired leases and historical null-expiry leases remain active.
+- Replaying the same approved digest returns the original receipt without another
+  mutation. Any interruption before receipt commit rolls back the whole repair.
+
+## Dry-run and approval
+
+Choose the observation time once; do not substitute a moving clock between steps.
+
+```powershell
+bun scripts/legacy-claim-repair.js --dry-run `
+  --database <absolute-kernel.sqlite> `
+  --backup <absolute-separate-backup.sqlite> `
+  --at <YYYY-MM-DDTHH:mm:ss.sssZ>
+```
+
+```bash
+bun scripts/legacy-claim-repair.js --dry-run \
+  --database <absolute-kernel.sqlite> \
+  --backup <absolute-separate-backup.sqlite> \
+  --at <YYYY-MM-DDTHH:mm:ss.sssZ>
+```
+
+Every dry-run requires a new, unused `--backup` path. Repeating a dry-run with
+the same path fails closed instead of overwriting the immutable backup.
+
+Review the privacy-safe counts, `preflight.digest`, `preflight.after_digest`, and
+backup proof. Approval must name the exact `preflight.digest`.
+
+## Apply (human-gated)
+
+Do not run this command until the exact dry-run digest is explicitly approved.
+
+```powershell
+bun scripts/legacy-claim-repair.js --apply `
+  --database <absolute-kernel.sqlite> `
+  --backup <absolute-separate-backup.sqlite> `
+  --at <same-literal-observation-time> `
+  --approved-digest <approved-preflight-digest> `
+  --actor <operator-id>
+```
+
+```bash
+bun scripts/legacy-claim-repair.js --apply \
+  --database <absolute-kernel.sqlite> \
+  --backup <absolute-separate-backup.sqlite> \
+  --at <same-literal-observation-time> \
+  --approved-digest <approved-preflight-digest> \
+  --actor <operator-id>
+```
+
+If an apply process is forcibly terminated, it may leave empty blocker
+directories named `<backup>-wal`, `<backup>-shm`, and `<backup>-journal`. After
+confirming that no repair process is still running, remove those stale
+directories before verifying or reusing that backup. An already committed
+receipt can still be replayed without this cleanup.
+
+`CLAIM_REPAIR_BACKUP_POSTCOMMIT_DRIFT` means the repair and receipt committed,
+but the named backup changed during commit. Do not discard the
+`details.recovery_path` copy: it is the independently retained verified backup.
+Fence writers and investigate the named path before any restore. Repeating the
+same approved apply returns the committed receipt without mutating rows again.
+
+A successful first apply also reports `receipt.recovery_path`, and its durable
+receipt stores a privacy-safe `recovery_ref` suffix so a retry with the same
+`--backup` path reconstructs the retained artifact after response loss. The
+tool never automatically unlinks this owner-only independent copy after commit
+because no final check can make a later unlink race-free. Keep it until the
+named backup and receipt have been independently verified. A human may then
+remove that exact reported recovery path after confirming that no repair
+process is running.
+
+On POSIX the recovery file and its parent directory entry are synced before the
+authority transaction commits. Every receipt replay reopens the retained copy,
+reapplies owner-only permissions, and verifies its exact digest and identity
+before reporting success.
+
+## Restore boundary
+
+Restore is deliberately not automated. Fence every Kernel writer, stop Forge
+processes, and close all database handles first. Preserve the failed database and
+its `-wal`/`-shm` sidecars for diagnosis, then restore the separately verified
+backup to a new path and run the same fixed-time dry-run there before replacing
+authority. Never overwrite a live or open SQLite database.

package/docs/reference/RELEASE.md

@@ -2,9 +2,9 @@
 
 This page documents release readiness. Package publishing still requires the explicit publish step after merge.
 
-## v0.1.0-beta.5 Boundary
+## v0.1.0-beta.7 Boundary
 
-v0.1.0-beta.5 is the current prerelease boundary. The release branch declares `0.1.0-beta.5`; publish only after the release PR is merged, tagged, and validated on that exact SHA.
+v0.1.0-beta.7 is the current prerelease boundary. The release branch declares `0.1.0-beta.7`; publish only after the release PR is merged, tagged, and validated on that exact SHA.
 
 Keep these release steps explicit:
 
@@ -23,7 +23,7 @@ bun run check
 npm pack --dry-run
 ```
 
-The trusted npm workflow is generated through `forge release generate-npm-workflow`; direct workflow edits remain blocked. On a release event, the workflow resolves the tag once, runs the complete supported repository suite on that immutable commit, and allows publication only when the attributable suite receipt, verification checkout, and publish checkout all name the same SHA. Missing or mismatched evidence fails closed.
+The trusted npm workflow is generated through `forge release generate-npm-workflow --expect-head "$(git rev-parse HEAD)"`; the full expected SHA must match the current checkout, and direct workflow edits remain blocked. The generated authorization is bound to that SHA, actor, worktree, path, and exact content, so moving HEAD before staging also fails closed. On a release event, the workflow resolves the tag once, runs the complete supported repository suite on that immutable commit, and allows publication only when the attributable suite receipt, verification checkout, and publish checkout all name the same SHA.
 
 For docs-heavy changes, also run a Markdown link check if available. If no docs checker exists and adding one would broaden the PR, create a follow-up issue instead.
 
@@ -43,7 +43,7 @@ Release notes should include:
 - adapter compatibility
 - DeepWiki refresh checklist
 
-The v0.1.0-beta.5 release notes live in [CHANGELOG.md](../../CHANGELOG.md).
+The v0.1.0-beta.7 release notes live in [CHANGELOG.md](../../CHANGELOG.md).
 
 ## Rollback
 

package/docs/reference/github-accounts.md

@@ -0,0 +1,134 @@
+# Optional GitHub accounts per clone
+
+Use this when you keep personal and work GitHub accounts signed in at the same
+time. It is off by default. Installing Forge or running `forge setup` does not
+select an account. Unbound projects keep native account selection.
+
+## Sign in once, select per clone
+
+From a normal terminal outside any previously launched account session, run:
+
+```sh
+gh auth login --hostname github.com --web --skip-ssh-key
+```
+
+Complete the browser flow for one account, then repeat for the other account.
+Choose the intended browser account each time. Keep your existing Git transport
+choice and decline Git credential-helper changes unless you deliberately want
+them. GitHub CLI owns login and credential storage; Forge does not create another
+credential store. Native `gh` normally uses the system credential store, but can
+fall back to a plaintext file when that store is unavailable. See
+[GitHub CLI login](https://cli.github.com/manual/gh_auth_login).
+
+Do not paste tokens into chat, commands, project files, shell profiles, or `.env`
+files. You do not need to export or persist `GH_TOKEN` for this workflow. If your
+normal terminal already supplies GitHub token variables, remove those overrides
+from that session before interactive login; do not print their values.
+
+Inside the work clone:
+
+```sh
+forge github use WORK_LOGIN
+forge github status
+forge github run -- codex
+```
+
+Inside the personal clone, in another terminal:
+
+```sh
+forge github use PERSONAL_LOGIN
+forge github status
+forge github run -- t3
+```
+
+Replace the uppercase labels with your GitHub logins. Both sessions can remain
+open together. Substitute any installed, trusted CLI harness or shell for `codex`
+or `t3`, such as `claude`, `pwsh`, or `bash`.
+
+`use` verifies the named stored account and repository access, then writes only
+`git config --local github.account`. It does not log in, switch the globally
+active account, or modify another clone. Linked Git worktrees normally share this
+clone-local configuration; use separate clones when you need separate bindings.
+
+Supported GitHub-dependent Forge commands use the binding automatically. To give
+the same identity to a harness's own `gh` calls, start that harness with
+`forge github run --`. Already-running terminals and harnesses are not changed.
+
+The launcher deliberately gives its child GitHub authority through transient
+environment variables. Only launch programs you trust with that account. Forge
+does not persist the token, but the launched program can access it. Harnesses or
+tools using their own credentials instead of the inherited `gh` environment are
+outside this guarantee.
+
+## Check or undo
+
+```sh
+forge github status --json
+forge github unset
+```
+
+Status reports the selected and verified login, clone-local binding source,
+effective Git author, origin transport, helper classification, and repository
+access. It does not print tokens, raw remote URLs, or raw credential-helper
+commands. Treat author and account labels as personal information when sharing
+diagnostics.
+
+`unset` is safe to repeat. It removes only the clone binding, not either stored
+login. It does not revoke authority from a running child: close that session and
+start a new one after changing or removing a binding.
+
+## Three separate identities
+
+| Identity | Controlled by |
+| --- | --- |
+| GitHub API account used by supported Forge routes | Clone-local `github.account` |
+| Commit author | Git `user.name` and `user.email` |
+| Fetch/push authentication | SSH configuration or the HTTPS credential helper |
+
+Forge does not change your author, origin, SSH keys, or credential helper.
+Existing SSH keys and host aliases remain valid; custom aliases must resolve to
+`github.com` for Forge's repository-access check. HTTPS and SSH GitHub.com origins
+are supported; insecure HTTP/Git transports and Enterprise hosts are not V1 targets.
+
+HTTPS has one important coupling: if Git uses `gh auth git-credential` as its
+helper, Git commands inside the explicitly launched session may use that session's
+selected token too. Other HTTPS helpers and SSH key selection remain independent.
+For native multi-account transport, keep separate SSH keys/aliases or configure
+your HTTPS credential manager to distinguish repository URLs (`useHttpPath`).
+These are optional Git choices, not Forge setup steps; see
+[GitHub's multi-account transport guide](https://docs.github.com/en/account-and-profile/how-tos/account-management/managing-multiple-accounts).
+
+## Platforms and recovery
+
+The command syntax is the same on Windows, macOS, and Linux. Windows executable
+and `.cmd` launchers are supported; quote paths or arguments containing spaces.
+Everything after `run --` belongs to the child, including `--help`, `--version`,
+and `--path`. Git Bash is still required for Forge's existing Windows Bash helpers.
+
+- **Account missing or expired:** run the browser login again from a normal
+  terminal, then retry `use` or `status`. Forge never starts login automatically.
+- **Account mismatch:** stop and check the clone with `forge github status`.
+  Reauthenticate the intended account, or explicitly bind the correct login.
+  A failed `use` leaves the prior binding intact.
+- **Repository access denied:** check organization membership, SSO authorization,
+  and the intended repository with its administrator. Account identity alone does
+  not grant repository access.
+- **Git push still uses the wrong account:** check the separate transport and
+  commit-author configuration above; changing the Forge API binding does not
+  replace SSH or credential-manager setup.
+- **Unsupported GitHub CLI:** upgrade `gh` to a version supporting named-account
+  token retrieval. Unbound projects do not need that capability.
+- **Program not found:** install the harness and check its executable name/PATH.
+
+The supported workflow entrypoints are `forge`, `forge-workflow`, and the compiled
+Forge executable. Direct developer invocation of `node bin/forge-cmd.js` is an
+internal legacy utility, not an account-isolated V1 entrypoint.
+
+## CuraPod adoption
+
+Only after this Forge feature is merged, the merged build is installed, and its
+acceptance checks pass: open each intended CuraPod clone, run
+`forge github use WORK_LOGIN`, verify `forge github status`, then launch the
+chosen harness with `forge github run --`. Keep personal clones separately bound
+to `PERSONAL_LOGIN`. This example does not discover or modify existing CuraPod
+repositories, remotes, keys, or accounts automatically.