forge-workflow 0.1.0-beta.4 → 0.1.0-beta.6

package/docs/reference/shepherd.md

@@ -21,30 +21,57 @@ forge shepherd events <pr-number> --since <seq>  # read new journal events back
 There are two ways to run the shepherd, both under the single `forge shepherd`
 verb:
 
-- **`forge shepherd daemon` — the singleton reconcile daemon (W-S4b), the default
-  ownership model.** It acquires the machine-wide shepherd lease for this repo
+- **`forge shepherd daemon` — the singleton reconcile daemon, the default
+  coordinator.** It acquires the machine-wide election 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,
+  hand-opened PRs, recovering dead watcher generations, requesting cooperative
+  stops,
   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. Today it is started explicitly — in a harness
-  background shell at session start, or `forge shepherd daemon` — not run by hand
-  as a detached process; automatic per-command launch (W-S4c) is a planned
-  follow-up, not yet wired. 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).
+  It **self-retires** — releases the election lease and exits — once no PRs
+  remain open. Per-PR ownership is never stored in that lease. 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 convergence pass.** Runs local review
+  preflight, reads one PR's state, takes at most one Tier-A action, persists
+  bounded deltas/receipts, and 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.
+  one PR, or (`--adopt`) reserve owner rows and start watchers for every
+  currently-open PR.
 - **`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: if the repo has open PRs, start `forge shepherd daemon` in the
-harness background shell so it is reaped with the session. No liveness check is
-needed first — the O_EXCL singleton lease makes a duplicate start a clean no-op.
+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.
+
+The daemon never kills watcher PIDs. A stop is a generation-conditional
+`running -> stop_requested` transition in the Kernel; the matching watcher sees
+that state, exits its loop, and releases only its own generation. A dead watcher
+is recovered only after fresh PID and provider evidence is gathered outside the
+transaction and the exact owner-row snapshot still matches inside it.
+
+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.)
 
@@ -98,26 +125,37 @@ project's documented ergonomic — poll briefly, then stop and hand off. A pass
 that finds checks still pending returns `PENDING`; the next scheduled pass picks
 up from there.
 
+Before remote mutation, the plain pass consolidates a probed CodeRabbit CLI with
+strict lint, structural drift, Sonar parity, and affected tests. The result is
+returned as `localPreflight`; CodeRabbit absence/auth loss is explicitly
+`UNAVAILABLE`/`INCOMPLETE`, not green. Deterministic failure or actual local
+review findings makes the remote decision dry-run for that pass. A local
+checkout that is not the exact PR head is explicitly `NOT_APPLICABLE`. Output is
+bounded to 128 `deltas` plus receipt IDs and one outcome handoff: `review` for
+semantic feedback, explicit human-approved `merge` at `MERGE_READY`, or `verify`
+after merged evidence. Shepherd never resolves threads and never merges.
+
 `--watch`-style behavior, if desired, belongs in an external scheduler (cron, or
 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`)
 
@@ -146,6 +184,7 @@ same verb (or `forge shepherd events`) on its own cadence.
 | `MERGE_READY` | Required checks are green and the branch is up to date. The shepherd hands off — **a human merges in the GitHub UI.** |
 | `ESCALATE`    | A Tier-C condition (conflict, unreadable required set, persistent failure, oscillation, budget exhaustion). Context is posted to the PR. |
 | `PENDING`     | A Tier-A action was taken, or checks are still pending. Exit and await the next scheduled pass. |
+| `INCOMPLETE`  | Exact-head local review or durable convergence evidence is unavailable. Fail closed and retry after evidence is restored. |
 | `HARD_STOP`   | A permanent auth/scope failure that retrying cannot fix. Escalate to a human to widen token scope. |
 
 ## Action ladder
@@ -171,6 +210,13 @@ same verb (or `forge shepherd events`) on its own cadence.
 - **HEAD-changed abort.** Before any mutating action it re-reads the head SHA; if
   HEAD moved during the pass, the action aborts. The `shepherd:active` marker is
   advisory only — it is not mutual exclusion.
+- **One per-PR authority.** `kernel_pr_watch_owners` is the sole watcher owner
+  record. The daemon lease elects one reconciler but contains no watcher list;
+  journals and legacy PID/marker files cannot authorize a transition.
+- **Fail-closed evidence.** Kernel unavailability, corrupt owner rows, stale
+  generations, changed provider/PID/receipt evidence, and an incomplete legacy
+  migration gate block mutation and are retried. No unlocked or filesystem
+  fallback becomes authority.
 - **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.
 
@@ -210,17 +256,50 @@ workflow behaves exactly as before (no regression) — it just cannot auto-run C
 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
-`.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.
+The shared Kernel database stores one versioned `kernel_pr_watch_owners` row per
+canonical `(repo, pr)`. Its generation-conditional phases are `starting`,
+`running`, `stop_requested`, `terminal_pending`, `complete`, and `blocked`.
+Starts reserve a store-minted generation before spawning; the child binds its
+PID to that exact generation; heartbeats, stop requests, terminal receipts,
+recovery, release, and reopen are narrow compare-and-swap transitions. Provider,
+PID, and receipt checks happen outside the short SQLite transaction, followed by
+an exact snapshot check inside it.
+
+Public Memory and the per-PR journal under
+`.forge/pr-monitor/<repo>-<pr>/` remain durable delivery and replay surfaces for
+monitor events, verdicts, `forge shepherd watch`, and `events --since`; neither
+is watcher ownership authority. A terminal receipt first moves the owner row to
+`terminal_pending`; a later transaction completes it only after the watcher PID
+is confirmed dead and the receipt/provider evidence still matches.
+
+Upgrade from the retired filesystem model is fenced by the repository-local
+`kernel_pr_watch_migration_gate`. The importer publishes `quarantined`, obtains
+two identical bounded snapshots of the old lease/PID/marker evidence, binds that
+snapshot hash before importing one PR per transaction, durably rereads the rows
+and source, and then completes the exact gate/hash. Corrupt, changed, live-PID,
+or unmappable evidence stays fail-closed as `blocked` or `conflict`. After the
+gate is complete, legacy evidence is cleanup-only and never regains authority.
+
+For 0.1, no receipt grants continuing lease authority. Consequential paths
+re-probe live ownership, while canonical LeaseReceipt epoch/scope and the
+same-actor/session release-reclaim ABA fix remain explicitly deferred.

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,
 };