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

package/docs/guides/SETUP.md

@@ -59,10 +59,16 @@ bunx forge setup --agents claude cursor
 bunx forge setup --all --quick
 bunx forge setup --path ./my-project --agents codex --dry-run
 bunx forge setup --merge smart --agents claude,cursor
+bunx forge setup --agents claude --skills-only
 ```
 
 Use `--agents`, not `--agent`.
 
+Use `--skills-only` (or its `--no-hooks` alias) when you want the Forge skill
+suite without installing Git hooks, Forge-native hook scripts, or Claude/Cursor
+native hook enforcement. The default `forge setup` behavior is unchanged, and
+the option is safe to re-run.
+
 ## Agent Notes
 
 Forge currently supports Claude Code, Codex, and Cursor. Hermes support is planned.
@@ -75,31 +81,25 @@ Exact generated files depend on selected agents and existing repository files. U
 
 ## Issue Backend
 
-Forge issue commands (`forge ready`, `forge show`, `forge claim`, `forge create`, `forge close`) use the built-in **kernel** backend by default. No install or initialization is required — a fresh clone can track issues immediately.
+Forge issue commands (`forge ready`, `forge show`, `forge claim`, `forge create`, `forge close`) use the built-in **kernel** backend. No install or initialization is required — a fresh clone can track issues immediately.
 
-## Beads (Opt-Out Backend)
+## Migrating From Beads
 
-Beads (`bd`) is an optional opt-out backend for teams that prefer Dolt-backed sync internals. Select it (precedence, highest first) with `--issue-backend beads`, `FORGE_ISSUE_BACKEND=beads`, or `issueBackend: beads` in `.forge/config.yaml`; only then is `bd` required. Prefer the current Beads installer documented by Beads itself and this repo's toolchain docs. On Windows, avoid stale global install examples if they hit EPERM or shim issues; use the PowerShell installer path described in [Toolchain](../reference/TOOLCHAIN.md).
+Beads is no longer a selectable backend: `--issue-backend beads`, `FORGE_ISSUE_BACKEND=beads`, and `issueBackend: beads` are rejected, and `bd` is never required. An existing `.beads` directory is import-only state.
 
-When Beads is selected, health checks:
+Import it once, then use the kernel issue commands:
 
 ```bash
-bd doctor
-bd dolt status
-forge sync
+forge migrate --from beads
 ```
 
-If a feature worktree reports `database "forge" not found on Dolt server`, diagnose in the root checkout before changing issue state. This applies only to the Beads backend.
-
 ## Deprecated GitHub Sync Cleanup
 
-To remove old generated GitHub/Beads sync files from an existing install:
-
-```bash
-bunx forge setup --sync
-```
-
-`forge setup --sync` is deprecated. It now removes old generated Beads/GitHub sync files instead of creating new sync workflows. Future GitHub issue sync belongs to Forge Kernel/server authority, not Beads runtime files or metadata commits.
+`forge setup` removes old generated GitHub/Beads sync files from an existing
+install automatically — there is no flag for it. Only files whose content
+matches a known generated template are removed, so files you have edited
+yourself are left alone. Future GitHub issue sync belongs to Forge Kernel/server
+authority, not Beads runtime files or metadata commits.
 
 ## Validate Setup
 

package/docs/reference/COMMANDS.md

@@ -53,20 +53,25 @@ forge plan "<feature description>"
 forge dev [--issue-id <id>] [--phase red|green|refactor]
 forge validate
 forge ship <feature-slug> [<title>] [--dry-run]
-forge status [--full] [--json]
-forge prime [--budget N] [--json]
+forge status [-v|--verbose] [--full] [--json]
+forge prime [--budget N] [--json]   # deprecated alias for `forge status -v`
 forge orient [--budget N] [--json]
 forge recap <issue> [--budget N] [--json]
 forge recall [query] [--limit N] [--all] [--json]
 forge remember <note> [--tag <label>]... [--json]
+forge skill for "<situation>" [--json]
+forge skill eval <skill> --full --tier <30|100|300> [--json]
 ```
 
 - `forge plan` creates the implementation plan, kernel issue, and feature branch/worktree from a researched feature description; it prints the created issue id, branch name, and the suggested next command.
 - `forge dev` runs the TDD development stage with RED/GREEN/REFACTOR phase guidance; `--issue-id` scopes it to a specific kernel issue and `--phase` overrides auto-detection.
 - `forge validate` runs the validation orchestration pipeline (conflict markers, type check, lint, security, tests) with no arguments — see also `bun run check` under Validation And Packaging.
 - `forge ship` creates the pull request from validated feature work (wraps `gh pr create`); `--dry-run` previews without creating a PR.
-- `forge status` is the one-glance orientation command: where you are, what to run next, and your active work; `--full` also shows blocked/stale/recently-completed issues.
-- `forge prime` emits the bounded session-entry orientation envelope agents read at the start of a session.
+- `forge status` is the one-glance orientation command: where you are, what to run next, and your active work; `--full` also shows blocked/stale/recently-completed issues. `-v`/`--verbose` prints the full session-entry briefing instead of the short pulse (git-status-v semantics).
+- `forge status -v` emits the bounded session-entry orientation envelope agents read at the start of a session; it leads with a bounded (<=20-line) **live-state** block — current stage, claimed issue(s), ready-work count, enabled gates/rails, and one progressive-adoption nudge — collected best-effort (never blocks, honest fallbacks) before the deterministic orientation.
+- `forge prime` is a **deprecated** alias for `forge status -v`. It still works and its stdout is byte-identical (session-start hooks consume it as context), but it prints a one-line deprecation notice on stderr.
+- `forge skill for "<situation>"` is the deterministic intent-to-skill router: it reads the canonical skill catalog and prints the best-fit Forge skill(s) plus why, as the reasoning fallback for harnesses without a SessionStart hook that auto-injects the `using-forge` dispatch skill. `--json` emits the machine-readable routing result.
+- `forge skill eval <skill> --full --tier <30|100|300>` runs the controlled four-arm behavioral protocol against the current PR head. It requires a live Kernel issue, an open PR at the exact local HEAD, and an isolated supported runtime. Tier 30 is instrumentation-only, tier 100 is the decision gate, and tier 300 is confirmation. Missing attribution, controls, usage, or reconstructable evidence returns `INCOMPLETE`; the command never authorizes merge.
 - `forge orient` emits bounded project orientation from deterministic source files (broader than `prime`, still token-budgeted via `--budget`).
 - `forge recap <issue>` is the issue-scoped counterpart to `forge orient`/`forge prime` — it summarizes a single issue from the same deterministic file assembly instead of the whole project. Requires an issue id; running it with no id (or `--help`) prints usage only.
 - `forge recall` retrieves project-memory notes from the kernel-backed memory store; omit `query` to list recent notes.

package/docs/reference/INSIGHTS_RECAP.md

@@ -1,6 +1,6 @@
 # Insights And Recap
 
-`forge insights` and `forge recap` summarize recurring local workflow evidence from existing Forge and Beads state.
+`forge insights` summarizes recurring local workflow evidence from Kernel and Forge state. `forge recap <issue>` renders a bounded, issue-scoped orientation envelope from the same Kernel issue record.
 
 ## Commands
 
@@ -11,24 +11,24 @@ 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
+forge recap <issue>
+forge recap <issue> --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.
+`--review-feedback` is a compatibility alias. It reads kernel events 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.
+- Kernel events (`kernel_events`, newest first): field changes and review/close outcome reasons. Interactions imported from a legacy Beads store are read here too, as `beads.interaction.<kind>` events.
+- Kernel issues (`forge issue list`): tokenized issue titles and descriptions for themes, plus statuses and timestamps.
 - `.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`.
+- 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.
+- Recent issue activity counts.
 - Whether history is too sparse for a useful suggestion.
 
 ## What It Cannot Infer
@@ -48,16 +48,5 @@ Ranked candidates:
   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.
+- Sparse kernel events or missing Forge audit logs reduce confidence.
 ```

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.0.11 Boundary
+## v0.1.0-beta.5 Boundary
 
-v0.0.11 is the public documentation and positioning package release. The release branch bumps package metadata to `0.0.11`; publish only after the release PR is merged, tagged, and validated.
+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.
 
 Keep these release steps explicit:
 
@@ -23,6 +23,8 @@ 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.
+
 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.
 
 ## Packaging Check
@@ -41,7 +43,7 @@ Release notes should include:
 - adapter compatibility
 - DeepWiki refresh checklist
 
-The v0.0.11 release notes live in [CHANGELOG.md](../../CHANGELOG.md).
+The v0.1.0-beta.5 release notes live in [CHANGELOG.md](../../CHANGELOG.md).
 
 ## Rollback
 

package/docs/reference/TOOLCHAIN.md

@@ -140,6 +140,14 @@ Forge project memory is a **kernel-backed** read model. `lib/project-memory.js`
 
 `forge remember` / `forge recall` route through this same `kernel_memories` table (via `lib/memory/router.js`), indexed by **FTS5** for token-AND BM25 recall: a `recall` query does full-text matching, and a no-query `recall` returns the newest notes plus a total count (never a full dump). Because the insights engine also writes `kernel_memories`, what it learns is recallable. Any legacy `.forge/memory/notes.jsonl` is imported once on first use, then retired. The opt-in **`graphiti`** backend is **experimental** — its config/doctor checks ship but the runtime write-through emitter is a fast-follow, so selecting it today still writes the local kernel floor. See [docs/guides/memory-backends.md](../guides/memory-backends.md).
 
+Claude Code setup and upgrade repair the existing Forge-owned `SessionStart` and `UserPromptSubmit` hook groups without replacing user hooks. `SessionStart` supplies a bounded project-memory digest; each submitted prompt can receive relevant FTS5-ranked memory as `additionalContext`. Other harnesses keep their documented CLI/rule/`AGENTS.md` fallback surfaces—Forge does not claim a native dynamic prompt hook where none is verified.
+
+Automatic recall is project-local. Forge derives scope from Git's canonical common directory so linked worktrees share one repository identity without crossing into another repository. Eligibility is applied before ranking: foreign scope, already-seen records, stale suggested records, and validly superseded records are excluded. Confirmed memories are authoritative project context; fresh suggested memories appear only under **Suggested memory — verify before relying**. Suggested memories outside the seven-day freshness window remain available to manual recall but are not injected automatically. User-global `.remember` data is not read because it has no authority-safe canonical project identity.
+
+Recall is bounded and fail-open: automatic prompt and session memory each have a 400-token budget, while default manual `forge recall` has a 1,200-token budget. Prompt recall has an internal 4.5-second deadline and SessionStart has a 9-second deadline, keeping them inside the 5-second and 10-second hook limits; an unavailable or slow store injects nothing rather than blocking the agent. Local 1,000-record holdouts enforce an FTS5 p95 of at most 250 ms. Linux CI timing acceptance is not claimed yet.
+
+The capped prompt shadow log stores aggregate candidate/injection counts and scores only—never prompt terms, session ids, selected memory ids, or memory bodies. The separate `memory.recall.observed` Kernel event likewise stores bounded outcomes, counts, selected ids, source/trust mixes, token estimates, elapsed time, and harness, with no prompt/query text, memory body/snippet, or correlation fingerprint.
+
 Typed memory helpers in `lib/memory/typed-api.js` add category and provenance conventions on top of the same kernel store; they do not create a new datastore. The supported categories are:
 
 | Category | Key prefix | Durable backend |

package/docs/reference/protected-state-surfaces.md

@@ -8,7 +8,7 @@ The committed manifest is `.forge/protected-paths.yaml`. Runtime enforcement is
 
 | Surface | Examples | Required write surface |
 | --- | --- | --- |
-| `beads_state` | `.beads/issues.jsonl`, `.beads/config.yaml` | `bd` or Forge issue commands |
+| `beads_state` | `.beads/issues.jsonl`, `.beads/config.yaml` | `forge migrate --from beads`, then Forge issue commands |
 | `forge_config` | `.forge/config.yaml`, `.forge/protected-paths.yaml` | Forge config/setup API |
 | `generated_harness` | `AGENTS.md`, `.claude/skills/`, `.codex/skills/`, `.cursor/rules/` | `forge setup` or harness generator |
 | `memory_projection` | `docs/sessions/`, `docs/memory/`, `.forge/memory/` | Forge memory projection writer |
@@ -23,13 +23,13 @@ The committed manifest is `.forge/protected-paths.yaml`. Runtime enforcement is
 
 - Direct edits, additions, modifications, renames, and deletions of protected files are blocked by `scripts/protected-state-check.js`.
 - Allowed Forge API writes must declare the matching required surface. For example, a Forge config writer must call the protected writer with `surface: "forge_config"` and `viaForgeApi: true`.
-- Forge-owned commands that intentionally stage generated protected changes can set `FORGE_PROTECTED_STATE_ALLOWED_SURFACES` to the comma-separated surfaces they own for that command invocation.
+- Surface-only environment declarations do not authorize protected changes. Forge-owned workflow commands must issue a content-bound Kernel capability for the exact actor, worktree, surface, path, and bytes.
 - Blocked decisions include actor, path, decision, required surface, reason, and repair hint.
-- Audit-ready events use kind `protected_state_write` and are recorded through Beads audit when available.
+- Audit-ready events use kind `protected_state_write` and are appended as JSON lines to `.forge/protected-state-audit.jsonl` (git-ignored, capped at the newest 500 records). This log is visibility-only and never authorizes a protected edit. Forge-owned workflow authorization uses one-time, content-bound Kernel events that the protected-state checker consumes; hand-written JSON cannot grant authority. The audit write remains best-effort for ordinary blocked checks, while the workflow generator rolls back its file transaction if its required audit or Kernel authorization write fails.
 
 ## Repair Hint
 
-Every blocked path prints a repair hint. A repair hint is specific guidance such as using `bd update` for `beads_state`, `forge setup` for generated harness files, or the package manager for `lockfiles`.
+Every blocked path prints a repair hint. A repair hint is specific guidance such as importing a legacy store with `forge migrate --from beads` for `beads_state`, `forge setup` for generated harness files, or the package manager for `lockfiles`.
 
 Example blocked output shape:
 

package/docs/reference/shepherd.md

@@ -6,13 +6,65 @@ polling / rerun / escalation loop a human otherwise runs by hand after
 the pre-merge gate (the embedded documentation-and-handoff gate in `/ship` and `/review`).
 
 ```bash
-forge shepherd <pr-number>
+forge shepherd daemon                      # singleton reconcile daemon: owns ALL open PRs
+forge shepherd <pr-number>                 # one bounded pass over a single PR
 forge shepherd <pr-number> --auto-rebase   # opt-in, default OFF
 forge shepherd <pr-number> --pull          # read-only: WHY it is blocked + what to fix
 forge shepherd <pr-number> --pull --json   # same payload as machine-readable JSON
 forge shepherd <pr-number> --bundle --json # read-only: the COMPLETE PR-state bundle
+forge shepherd watch <pr-number>           # single-PR constant monitor loop
+forge shepherd events <pr-number> --since <seq>  # read new journal events back
 ```
 
+## Daemon vs bounded pass (two modes, one verb)
+
+There are two ways to run the shepherd, both under the single `forge shepherd`
+verb:
+
+- **`forge shepherd daemon` — the singleton reconcile daemon, the default
+  ownership model.** It acquires the machine-wide shepherd lease for this repo
+  (exiting immediately as a clean no-op if a live daemon already owns it),
+  heartbeats, and converges the *entire* PR world every ~60s: self-registering
+  hand-opened PRs, restarting killed watchers, reaping verified orphan watchers,
+  converging CI check state into kernel verdicts, and retiring merged/closed PRs.
+  It **self-retires** — releases the lease, kills its verified children, exits —
+  once no PRs remain open. Forge wakes it automatically after a successful
+  supported session start, every successful push, and every successful
+  non-dry-run ship. These are the only automatic firing seams; ordinary commands
+  do not launch it. Once running, an agent does not poll: the daemon owns the
+  convergence loop.
+- **`forge shepherd <pr>` — one bounded pass.** Reads one PR's state, takes at
+  most one Tier-A action, exits. The point-in-time surface for a single PR (see
+  *Bounded-pass model* below).
+- **`forge shepherd watch <pr>` / `watch --adopt`** — foreground streaming watch of
+  one PR, or (`--adopt`) adopt every currently-open PR into the watcher set.
+- **`forge shepherd events <pr> --since <seq>`** — the event deltas for a PR since a
+  cursor; **`forge shepherd <pr> --pull --json` / `--bundle`** read the kernel verdict
+  + rollup without taking any action.
+
+Session start automatically wakes the daemon. When an embedding caller supplies
+an executable harness background-shell capability, Forge uses it so the process is reaped with the session;
+bare CLI use falls back to a detached launch from the stable common repository
+root, never a disposable worktree cwd. No liveness check is needed first — the
+O_EXCL singleton lease makes a duplicate start a clean no-op.
+
+Embedding boundary:
+
+```js
+hooks.handler(['session-start', '--harness', 'claude'], {}, projectRoot, {
+  harness: {
+    hasBgShell: true,
+    runBgShell: (argv, options) => host.backgroundShell(argv, options),
+  },
+});
+```
+
+The host must explicitly provide both `hasBgShell: true` and `runBgShell`;
+Forge never infers this capability from a harness name. The adapter receives
+the stable Git common-root as `options.cwd`; a missing or throwing adapter uses the contained detached fallback.
+(A `forge prime` open-PR + daemon-liveness line is a planned follow-up — W-S5 —
+not yet wired.)
+
 ## `--pull`: the actionable blocker payload
 
 `--pull` is a **strictly read-only** signal-gather. It computes the decision
@@ -67,22 +119,23 @@ up from there.
 a `/loop`) that re-invokes the bounded pass with a debounce of at least 60
 seconds and cancel-in-progress. The shepherd itself never waits in-process.
 
-## Auto-start on ship (`rail.auto_shepherd`)
+## Automatic singleton attachment (`rail.auto_shepherd`)
 
-`forge shepherd watch <pr>` is the constant, self-stopping local monitor loop
-(≈60 s jittered cadence; appends events to the per-PR NDJSON journal under
-`.forge/pr-monitor/<repo>-<pr>/`; self-stops on `PR_MERGED`/`PR_CLOSED`). On a
-successful `forge ship`, the new PR's watcher is **auto-started detached** so a
-shipped PR is tended without a manual trigger. The spawn is best-effort and
-**never fails ship** (a spawn or config-read error degrades to "not started"),
-and it is idempotent — the watch-lifecycle PID/journal lock prevents a second
-watcher for the same PR.
+Successful supported session start, push, and non-dry-run ship operations wake the
+repository-wide singleton. Push never requires a locally resolved PR number:
+the daemon owns GitHub enumeration, so even a push with no local open-PR match
+still fires and can adopt open or draft PRs created elsewhere. Push and ship no
+longer start separate per-PR detached watchers.
 
 This auto-start is governed by the default-ON, unlocked **`rail.auto_shepherd`**
 rail. Opt out with `forge gate disable rail.auto_shepherd` (re-enable with
-`forge gate enable rail.auto_shepherd`); when disabled, `forge ship` skips the
-auto-start. This keeps the behavior honestly toggleable through the same config
-surface as every other rail.
+`forge gate enable rail.auto_shepherd`). `FORGE_SHEPHERD_DISABLE=1` is the
+environment kill-switch. CI/test detection is deterministic and injectable via
+the trigger environment: `NODE_ENV=test`, `BUN_ENV=test`, or a set `CI`,
+`GITHUB_ACTIONS`, or `GITLAB_CI` disables automatic fire. These environment
+guards run before repository initialization, lease, Kernel-state, or process
+work; dry-run, uninitialized repositories, and a disabled rail are likewise
+zero-side-effect paths. The manual `forge shepherd` surface remains available.
 
 ## Surfacing events back to the agent (`forge hooks shepherd-events`)
 
@@ -139,17 +192,64 @@ same verb (or `forge shepherd events`) on its own cadence.
 - **Auth taxonomy.** 401 (expiry) pauses and surfaces; 403 insufficient-scope is
   a hard-stop; 403 with `Retry-After` honors the delay and resumes next pass.
 
+## GitHub Actions backstop — auto-updated heads re-trigger CI (`FORGE_PR_TOKEN`)
+
+The `pr-monitor.yml` Actions workflow can auto-update an otherwise-clean-but-behind
+PR branch (merge base into the head). That push must **re-trigger CI on the new
+head**, or the head sits with no required checks running and can never merge.
+
+GitHub deliberately does **not** start new workflow runs for events created with
+the default `GITHUB_TOKEN` — a `pull_request: synchronize` it produces lands in an
+*approval-required* state instead of running. So an auto-update authored by
+`GITHUB_TOKEN` leaves a **CI-dead head**. (Official rule:
+<https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow>.)
+
+**Fix (maintainer action required):** create a repository secret named
+**`FORGE_PR_TOKEN`** holding a fine-grained **PAT** (or GitHub-App installation
+token). The PAT's OWN permissions — not the workflow's `permissions:` block, which
+only governs the built-in `GITHUB_TOKEN` — must cover every call the step makes:
+
+| Permission | Why |
+| --- | --- |
+| **Contents: write** | push the update-branch merge to the head |
+| **Pull requests: write** | `PUT /pulls/{n}/update-branch` (the update-branch API) |
+| **Checks: write** | create the `forge/auto-update` marker check run |
+| **Workflows** | only if the base branch may change `.github/workflows/**` (the merge would carry it) |
+
+The auto-update-branch step uses the token and falls back to `GITHUB_TOKEN` when
+the secret is absent:
+
+```yaml
+GH_TOKEN: ${{ secrets.FORGE_PR_TOKEN || github.token }}
+```
+
+With the secret set, auto-updated heads re-run CI automatically. Without it, the
+workflow behaves exactly as before (no regression) — it just cannot auto-run CI on
+the updated head. Forge only wires the code path and reads the secret; **creating
+the secret is the maintainer's responsibility** — Forge never fabricates a token.
+
+## GitHub Actions PR-monitor summary
+
+The repository PR-monitor workflow writes detailed review-thread and check
+diagnostics to the Actions job summary (`GITHUB_STEP_SUMMARY`) and keeps the
+machine-readable view available through `forge shepherd <pr> --pull --json`.
+It projects that same canonical verdict onto exactly one `pr-verdict:*` label
+for a cheap agent-agnostic read. The label is visibility only: merge authority
+continues to use live protected required checks, the current head, and
+unresolved review threads. The workflow does not create PR comments or a
+neutral `forge/pr-monitor` check.
+
 ## Per-harness behavior
 
-- **Claude Code / Codex:** invoke `forge shepherd <pr>` directly; an external
-  scheduler may drive repeated bounded passes.
+- **Claude Code / Codex:** automatic session-start attachment wakes the singleton;
+  invoke `forge shepherd <pr>` directly for a bounded point-in-time read.
 - **Cursor:** manually-invoked only — run it from a terminal. No polling-loop
   affordance and no hook reliance on this surface.
 
 ## State
 
-Progress is durable in GitHub PR comments and labels plus `git`. The one local
-store is the constant monitor's per-PR journal under
+Progress is durable in the Actions job summary, the single verdict label, and
+`git`. The one local store is the constant monitor's per-PR journal under
 `.forge/pr-monitor/<repo>-<pr>/` (the append-only `events.ndjson` + snapshot and
 consumer cursors) — the delivery/replay surface for `forge shepherd watch` and
 `events --since`. The bounded shepherd pass itself keeps no separate local state.

package/lefthook.yml

@@ -21,6 +21,14 @@ pre-commit:
       stage_fixed: false
       tags: skills
       glob: "skills/**"
+    # Keep the D20 Beads call-site kill-list current with the census it audits.
+    # Self-gating: the script exits early unless a staged path actually counts toward
+    # the census, because those scan roots are resolved at run time (plugin manifests +
+    # .forge/sync-manifest.json) and a static glob here would drift from the gate.
+    sync-d20-audit:
+      run: node scripts/sync-d20-audit.js
+      stage_fixed: false
+      tags: release
     protected-state:
       run: node scripts/protected-state-check.js
       stage_fixed: false
@@ -50,6 +58,10 @@ pre-push:
         - run: node scripts/check-forge-token.js
 
     # 3. Test suite (cross-platform Node.js script detects package manager)
+    # `forge push --quick` sets FORGE_PUSH_LANE=quick on the git push it spawns;
+    # scripts/test.js honors that declaration and skips this job with a loud
+    # notice so the quick lane is lint-only end to end. Only this job reads it —
+    # branch protection and lint above always run, and CI runs the full matrix.
     tests:
       run: node scripts/test.js
       tags: tests

package/lib/activation/ensure-forge-home.js

@@ -11,11 +11,11 @@
  * bare repo stays untouched until the user actually changes state.
  *
  * "Bare-minimum" here is strictly LESS than `forge init --minimal`: this writes
- * ONLY `.forge/config.yaml` with every gate disabled (the `minimal` adoption
- * profile). It installs NO git hooks, NO lefthook.yml, NO protected-paths
- * manifest, NO `.mcp.json`, and NO scripts tree — those remain the opt-in
- * payload of `forge setup`, never forced. Progressive growth: heavier slices
- * initialize themselves on first use.
+ * ONLY `.forge/config.yaml` with Forge's canonical default enforcement posture.
+ * It installs NO git hooks, NO lefthook.yml, NO protected-paths manifest, NO
+ * `.mcp.json`, and NO scripts tree — those remain the opt-in payload of
+ * `forge setup`, never forced. Progressive growth: heavier slices initialize
+ * themselves on first use.
  *
  * @module activation/ensure-forge-home
  */
@@ -78,26 +78,33 @@ function isMutatingVerb(name, command) {
 }
 
 /**
- * Render the bare-minimum, gates-disabled config body.
+ * Render the bare-minimum config body with Forge's default enforcement posture.
  *
- * Reuses the canonical `minimal` adoption profile so the produced YAML is
- * schema-valid and identical in spirit to `forge init --minimal` (minus the
- * hooks/protected-paths side effects). Overridable via `deps.renderConfig` for
- * tests that don't want to depend on the profile renderer.
+ * Reuses the canonical `standard` adoption profile so the produced YAML is
+ * schema-valid and keeps default gates enabled. Overridable via
+ * `deps.renderConfig` for tests that don't want to depend on the profile
+ * renderer.
  *
  * @param {object} [deps]
  * @returns {string} config.yaml contents
  */
-function renderMinimalConfig(deps = {}) {
-  const render = deps.renderConfig || (() => renderAdoptionConfigYaml('minimal'));
+function renderDefaultConfig(deps = {}) {
+  const render = deps.renderConfig || (() => renderAdoptionConfigYaml('standard'));
   return render();
 }
 
+/**
+ * Backward-compatible export name for callers of the previously exported
+ * helper. New code should use `renderDefaultConfig`; lazy initialization no
+ * longer creates a minimal/disabled configuration.
+ */
+const renderMinimalConfig = renderDefaultConfig;
+
 /**
  * Idempotently create the bare-minimum `.forge/` skeleton for a mutating verb.
  *
- * No-clobber by construction: if `.forge/` already exists (inited repo, or a
- * partially-created home), this is a NO-OP and never touches the user's files.
+ * No-clobber by construction: an existing config is a NO-OP. A partial home
+ * whose `.forge/` directory exists without `config.yaml` is completed safely.
  * The kernel/issue store (`.forge/kernel/…`) is created lazily by the broker on
  * the mutating verb itself — this function only guarantees the config skeleton.
  *
@@ -123,13 +130,24 @@ function ensureForgeHome(projectRoot = process.cwd(), deps = {}) {
   }
 
   fsImpl.mkdirSync(forgeDir, { recursive: true });
-  fsImpl.writeFileSync(configPath, renderMinimalConfig(deps), 'utf8');
+  try {
+    fsImpl.writeFileSync(configPath, renderDefaultConfig(deps), {
+      encoding: 'utf8',
+      flag: 'wx',
+    });
+  } catch (error) {
+    if (error?.code === 'EEXIST') {
+      return { created: false, reason: 'config-exists', configPath };
+    }
+    throw error;
+  }
   return { created: true, configPath };
 }
 
 module.exports = {
   ensureForgeHome,
   isMutatingVerb,
+  renderDefaultConfig,
   renderMinimalConfig,
   MUTATING_VERBS,
 };

package/lib/adapters/greptile-review-adapter.js

@@ -86,7 +86,7 @@ function matchThreadsToCommitsWithGit(threads, projectRoot, opts = {}) {
   }
 
   const exec = opts._exec || ((cmd, args) => {
-    return execFileSync(cmd, args, { encoding: 'utf8' });
+    return execFileSync(cmd, args, { encoding: 'utf8', windowsHide: true });
   });
 
   let sinceCommit = opts.sinceCommit;