@aperant/framework 0.13.0-next.0 → 0.15.0

package/skills/apt-setup/SKILL.md

@@ -199,7 +199,7 @@ AskUserQuestion([
 
 **Routing:**
 - "Verification" → jump to **Step 2** (Batch 1 + Batch 2 only), then skip to **Step 4** (mapping) and **Step 5** (write)
-- "Pipeline" → jump to **Step 3** (Batch 2: auto-branch, code review, TDD, PR Review Auto-Suggest, **Sparring Auto-Fire**) AND **Step 3b** (Batch 3 only, including Diagram Mode), then skip to **Step 4** and **Step 5**
+- "Pipeline" → jump to **Step 3** (Batch 2: auto-branch, code review, TDD, PR Review Auto-Suggest, CI Watcher, **Sparring Auto-Fire**) AND **Step 3b** (Batch 3 only, including Diagram Mode), then skip to **Step 4** and **Step 5**
 - "Orchestration" → jump to **Step 3c** (Batch 4 only), then skip to **Step 4** and **Step 5**
 - "Team Collaboration" → jump to **Step 3d** (Batch 5 only), then skip to **Step 4** and **Step 5**
 - "Visibility" → jump to **Step 3e** (Batch 6 only), then skip to **Step 4** and **Step 5**
@@ -412,6 +412,16 @@ AskUserQuestion([
       { label: "Ask me", description: "Prompt [Y/n] each time — choose per-PR." },
       { label: "Never", description: "Silent. Run /apt:pr-review manually if needed." }
     ]
+  },
+  {
+    question: "After /apt:ship opens a PR, run the post-ship CI watcher? It polls checks, auto-fixes the first red check and pushes, and can auto-merge once CI is green.",
+    header: "CI Watcher",
+    multiSelect: false,
+    options: [
+      { label: "Watch & auto-fix (Recommended)", description: "Ship auto-arms the watcher: it polls CI, fixes the first red check + pushes, then stops at green for you to merge. Ticks automatically on cron-capable hosts (Claude Code/Pi); elsewhere you advance ticks manually with /apt:watch-ci --tick." },
+      { label: "Watch, fix & auto-merge on green", description: "Same as above, plus auto-merges the PR (squash) once CI is green, then suggests /apt:close-task. Fully hands-off run." },
+      { label: "Off", description: "Ship does not arm the watcher. Watch CI and merge yourself, or run /apt:watch-ci manually." }
+    ]
   }
 ])
 ```
@@ -728,8 +738,8 @@ AskUserQuestion([
     options: [
       { label: "Auto", description: "Best available for your CLI" },
       { label: "Agent Team", description: "Uses Claude Code agent teams (requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)" },
-      { label: "Sub-Agents", description: "Spawns 6 parallel sub-agents for review (available on Claude Code and Codex)" },
-      { label: "Sequential", description: "Runs 6 review passes inline, one at a time — works on any CLI" }
+      { label: "Sub-Agents", description: "Spawns 6-8 parallel sub-agents for review (available on Claude Code and Codex)" },
+      { label: "Sequential", description: "Runs 6-8 review passes inline, one at a time — works on any CLI" }
     ]
   },
   {
@@ -1378,6 +1388,13 @@ Map the user's selections to config values:
 - "Ask me" → `pr_review.suggest_after_ship: "ask"`
 - "Never" → `pr_review.suggest_after_ship: "never"`
 
+**CI Watcher (post-ship):** maps to the SHARED `.aperant/config.json` `ci_watch` block (team policy — NOT a per-device AUDIT-001 field, so it stays in shared `config.json`):
+- "Watch & auto-fix (Recommended)" → `ci_watch.after_ship: "auto"`, `ci_watch.auto_merge_on_green: false`
+- "Watch, fix & auto-merge on green" → `ci_watch.after_ship: "auto"`, `ci_watch.auto_merge_on_green: true`
+- "Off" → `ci_watch.after_ship: "never"`, `ci_watch.auto_merge_on_green: false`
+
+The existing `ci_watch.merge_method` key (default `"squash"`) is preserved untouched — this question does not change it. On non-cron hosts, `after_ship: "auto"` still creates the watcher state and ship prints manual-tick instructions; the host-capability fallback already lives in `apt-ship/SKILL.md` §7.2, so the value is safe to store as team policy regardless of the setup-runner's host.
+
 **Sparring Auto-Fire (FRAMEWORK-RFC-001):**
 - Phase 1 "No" → `spar.enabled: false`, ask Phase 3 (hint sub-picker)
 - Phase 1 "Yes" → `spar.enabled: true`, ask Phase 2 (partner picker)
@@ -1522,6 +1539,7 @@ Display:
 | Auto Branch          | {Yes/No}                     |
 | Code Review          | {Yes/No}                     |
 | TDD Iron Law         | {Yes/No}                     |
+| CI Watcher           | {Off / Watch & fix / Watch, fix & auto-merge} |
 | Sparring Auto-Fire   | {Off / On (codex), On (claude), On (gemini)} (hint: {Yes/No}) |
 | Date Format          | {DD-MM-YY / MM-DD-YY / YY-MM-DD} |
 | Time Format          | {24h / 12h}                  |

package/skills/apt-ship/SKILL.md

@@ -20,6 +20,7 @@ gates:
   - constitution-read
   - verify-approved
   - review-clean
+  - followups-adjudicated
   - consistency-check
   - r-persona-alignment
   - gitignore-in-sync
@@ -149,15 +150,18 @@ Capture `remote_tip_sha_pre_rebase` now — §6's lease uses it.
   ```
   Proceed to §1. §6's push will use `--force-with-lease=refs/heads/<branch>:$remote_tip_sha_pre_rebase` because history was rewritten.
 
-- **`behind > 0` AND `mergeable === false`** → STOP. Emit a structured error with the conflict preview verbatim:
-  ```
-  [APT:ship] Cannot ship — task branch is behind origin/{base_branch} and the rebase would conflict.
-  Conflicts preview:
-    - {path1}
-    - {path2}
-  Resolve manually (rebase or merge in the worktree), then re-run /apt:ship.
-  ```
-  Exit the skill — do NOT auto-resolve, do NOT proceed to §5 or §6.
+- **`behind > 0` AND `mergeable === false`** → the rebase would conflict. Default behavior is a hard STOP; AI resolution is **opt-in** via `pipeline.resolve_merge_conflicts` (default false) in `.aperant/config.json`.
+
+  - **Resolution opted in (`pipeline.resolve_merge_conflicts === true`)** → hand off to **`/apt:merge-conflict-resolution`** (`--base origin/{base_branch}`). That skill drives the rebase, resolves the conflicted files inline (reading the markers via `apt-tools merge markers`), and re-probes mergeability. On success it returns here — proceed to §1 with `--force-with-lease=refs/heads/<branch>:$remote_tip_sha_pre_rebase` (history was rewritten). On its non-convergence STOP, it aborts to a clean tree and hands back; fall through to the manual-STOP message below.
+  - **Resolution NOT opted in (default)** → STOP. Emit a structured error with the conflict preview verbatim:
+    ```
+    [APT:ship] Cannot ship — task branch is behind origin/{base_branch} and the rebase would conflict.
+    Conflicts preview:
+      - {path1}
+      - {path2}
+    Resolve manually (rebase or merge in the worktree) or enable pipeline.resolve_merge_conflicts to use /apt:merge-conflict-resolution, then re-run /apt:ship.
+    ```
+    Exit the skill — do NOT auto-resolve, do NOT proceed to §5 or §6.
 
 - **`mergeable === null` AND `audit_warning === "git-version-too-old"`** → STOP with a friendlier message:
   ```
@@ -175,8 +179,8 @@ Capture `remote_tip_sha_pre_rebase` now — §6's lease uses it.
 **Autonomy gating.** Read the active task's autonomy level from `.aperant/state.json` (`active_tasks[{task-id}].autonomy`, falling back to `autonomy.default`):
 
 - **Autonomy 0–1 (step / guided)** — print the audit envelope to the operator and ask `Rebase now? [Y/n]` before executing the `git rebase` line. On `N`, exit the skill (user can rebase manually and re-invoke).
-- **Autonomy 2 (auto-chain)** — proceed silently on the clean-rebase branch; STOP on conflict regardless.
-- **Autonomy 3 (YOLO)** — same as 2: silent on clean, STOP on conflict. Auto-resolution of conflicts is explicitly out of scope (see spec §Out of Scope).
+- **Autonomy 2 (auto-chain)** — proceed silently on the clean-rebase branch; on conflict, hand off to `/apt:merge-conflict-resolution` when `pipeline.resolve_merge_conflicts` is enabled, else STOP.
+- **Autonomy 3 (YOLO)** — same as 2: silent on clean; on conflict, AI-resolve via `/apt:merge-conflict-resolution` when opted in, else STOP. Even at YOLO the resolved branch still flows through PR → review → CI — apt:ship never auto-merges.
 
 The captured `remote_tip_sha_pre_rebase` and `behind` integer are referenced verbatim in §6's push command. Treat them as read-only state for the remainder of the skill.
 
@@ -380,11 +384,21 @@ The body structure below is the full-pipeline template — unchanged from the pr
 
 {If no review: "No code review was run for this task."}
 
+## Follow-ups
+
+{Read `{task_dir}/followups.json` and enumerate EVERY open/dispositioned row VERBATIM — never a count. One line per row:}
+
+- [{status}] {title} — {adjudication.verdict ?? 'unadjudicated'} → {disposition.kind ?? 'pending'}
+
+{If no followups.json: "No follow-ups recorded for this task."}
+
 ---
 
 Built with [Aperant Framework](https://github.com/Mikalsen-AI/aperant-cloud-desktop/tree/main/packages/framework)
 ```
 
+Counts hide work; the verbatim row list is the visibility contract (ID-16). The `followups-adjudicated` gate (Section 0) has already guaranteed every open row is adjudicated and every load-bearing row is fixed before you reach this section.
+
 ## 4. Determine Ship Mode
 
 Read `.aperant/config.json` for `project_type`.
@@ -520,8 +534,15 @@ Review: logic={n} security={n} quality={n} architecture={n} performance={n}
 Commits: {count}
 Review findings: {count by severity or "none"}
 Decisions traced: {count}
+
+Follow-ups:
+{Enumerate EVERY open/dispositioned row from {task_dir}/followups.json VERBATIM,
+one per line — `- [{status}] {title} — {verdict} → {disposition.kind ?? 'pending'}`.
+Never a count. "none" only when followups.json is absent or has zero rows.}
 ```
 
+The report's Follow-ups block mirrors the PR-body `## Follow-ups` section (ID-16) — rows verbatim, never counts.
+
 ### 7.1 Post-ship /apt:pr-review hint
 
 After printing the ship summary, conditionally emit a tip suggesting `/apt:pr-review` for a deep multi-agent review of the freshly-opened PR. The hint is controlled by `pr_review.suggest_after_ship` in `.aperant/config.json` (tri-state: `always` | `ask` | `never`; default when absent: `always`).

package/skills/apt-terminal/SKILL.md

@@ -97,6 +97,14 @@ The response is JSON to stdout. On success:
 
 `depth` is the new terminal's level (caller_depth + 1). Record `sessionId` in your task notes.
 
+The worktree the spawned terminal opens in already has the project's stored env
+blobs materialized (the per-project encrypted env store, #354) — worktree-create
+copies each `.env*` blob verbatim (traversal-guarded, best-effort) so the sibling
+terminal's CLI runs with the real env instead of crashing in no-cloud mode. If a
+long-lived worktree's stored env later drifts, re-copy on demand with
+`node packages/framework/bin/apt-tools.mjs worktree sync-env <dir> --task <id>`
+(the store is the source of truth — sync-env overwrites, never merges).
+
 ## 4. Recognise the graceful-degrade error envelopes
 
 These are **expected** error shapes — do not retry blindly. Each one tells you exactly which obligation discharged:

package/skills/apt-triage/SKILL.md

@@ -49,6 +49,10 @@ OUT-OF-SCOPE.md sub-files ported from
 - An inbound task / bug / feature request needs status assignment
 - Periodic review of `needs-triage` tasks
 - Re-triage when new info arrives on a `needs-info` task
+- A `new-task` follow-up disposition (G45) — `/apt:close-task` files an open
+  follow-up as a fresh task and enters it here at `needs-triage` via
+  `apt-tools triage init` (the configured backend mirrors it). This is a normal
+  entry point; the chained-task depth marker rides `triage.json` `extra.followups_chain`.
 
 ## When NOT to Use
 

package/skills/apt-verify/SKILL.md

@@ -266,6 +266,30 @@ for ITERATION in 1 2 3 4:
 
 **Exhaustion:** If issues remain after 4 iterations, mark them in `qa_signoff.json` and report them. The verdict should reflect the remaining issues.
 
+## 6.5 Follow-ups Adjudication (mandatory — G45)
+
+This pass is **mandatory** on every full-pipeline verify. It is the owner of follow-up adjudication: `apt:verify` always runs in the pipeline (`apt:run` = plan → execute → verify → review), whereas `apt:verify-proof` is opt-in and therefore cannot be the sole owner. (When `verify-proof` runs later it MAY overwrite an adjudication with stronger evidence, `by: 'verify-proof'`.)
+
+Run the deterministic check first:
+
+```bash
+node packages/framework/bin/apt-tools.mjs followups check . --task-id {task-id}
+```
+
+The envelope returns `missing_expected[]` — the derived expected universe (parsed `## Out of Scope` bullets ∪ raw review rows ∪ qa findings, `status !== 'fixed'`) that the ledger does not yet cover. Create/sync `{task_dir}/followups.json` rows **mechanically** from those payloads:
+
+- Append one row per `missing_expected[]` entry: `{ id, title, origin, class_proposed: <class_hint>, files: [], outcome_refs: [], status: 'open' }`. `class_proposed` is only a PROPOSAL (ID-03) — the verdict below is the authority; never let the class self-certify a deferral.
+- Voluntary rows (origin `discuss | execute | ci`) may also be present; they are adjudicated the same way.
+
+Then **adjudicate every open row**. For each, answer the single question:
+
+> "Would the feature satisfy its stated `## User Outcomes` right now WITHOUT this follow-up?"
+
+- If NO → `adjudication: { verdict: 'load-bearing', by: 'verify', outcome_ref: '<O-n>' }`. A load-bearing row blocks ship until it is fixed (flip `status: 'fixed'` once the work lands in this PR's fix loop) or bypassed via `--force --reason`.
+- If YES → `adjudication: { verdict: 'deferrable', by: 'verify', outcome_ref: '<O-n> | null' }`. `outcome_ref` is the `O<n>` id (from `parseUserOutcomes`) the row relates to; it is nullable for refactor-only specs that declare no outcomes.
+
+Re-run `followups check` until it is **derivation-clean** (exit 0 — no `missing_expected`, no `invalid_outcome_refs`, no `schema_errors`) BEFORE writing `qa_signoff.json`. The `followups-adjudicated` ship gate will block the PR otherwise.
+
 ## 7. Write QA Sign-off
 
 Create `qa_signoff.json` using the `ScoredQASignoff` format (see `packages/framework/src/types/qa-scoring.ts`):

package/skills/apt-watch-ci/SKILL.md

@@ -125,7 +125,9 @@ When `action === 'fix'` (or `diverged-rebased`/`diverged-bailed`):
 5. **Emit event.** `apt-tools event append . --type ci-watch.fix-pushed --data '{pr, attempts, commit_sha}'`.
 6. **Reschedule** per §3 step 4.
 
-For `diverged-rebased`: the cmd already returned the verb; the orchestrator runs `git -C {worktree} fetch && git rebase origin/{base}` BEFORE the fix step. On conflict the action becomes `diverged-bailed` and the watcher exits with a PR comment summarizing the conflict.
+For `diverged-rebased`: the cmd already returned the verb; the orchestrator runs `git -C {worktree} fetch && git rebase origin/{base}` BEFORE the fix step. On conflict the action becomes `diverged-bailed`.
+
+For `diverged-bailed`: default behavior is to exit with a PR comment summarizing the conflict. Self-heal is **opt-in** via `ci_watch.resolve_merge_conflicts` (default false) in `.aperant/config.json`. When enabled, instead of bailing, hand off to **`/apt:merge-conflict-resolution`** (`--base origin/{base}`) for the worktree; it resolves the rebase conflict inline and re-probes mergeability. On success, continue to the §5 fix-and-push step (`git push origin {branch}`) and reschedule per §3 — the watcher keeps running. On its non-convergence STOP (it aborts the rebase to a clean tree first), fall back to the bail-with-PR-comment path. The resolved branch still goes through CI; the watcher never auto-merges except via the existing config-gated `gh pr merge --auto`.
 
 ---
 

package/src/cli/commands/audit-branch-current.mjs

@@ -42,7 +42,7 @@ import { err, ok } from '../util/result.mjs'
  * @param {string} cwd
  * @param {string[]} args
  */
-function gitTry(cwd, args) {
+export function gitTry(cwd, args) {
 	try {
 		const stdout = execFileSync('git', args, {
 			cwd,
@@ -94,7 +94,7 @@ function parseBaseFlag(extraArgs) {
  * @param {string} stdout
  * @returns {string[]}
  */
-function parseConflictPaths(stdout) {
+export function parseConflictPaths(stdout) {
 	const paths = new Set()
 	for (const rawLine of stdout.split('\n')) {
 		const line = rawLine.replace(/\0/g, '')
@@ -125,7 +125,7 @@ function parseConflictPaths(stdout) {
  * @param {string} stderr
  * @returns {boolean}
  */
-function isGitVersionTooOld(stderr) {
+export function isGitVersionTooOld(stderr) {
 	return /unknown option|did you mean|usage: git merge-tree/i.test(stderr)
 }
 

package/src/cli/commands/event.mjs

@@ -8,9 +8,9 @@ import { join, resolve } from 'node:path'
 import { readLifecycleEventsForDay } from '../coordination/event-log.mjs'
 import { validateConductorEvent } from '../coordination/event-schema.mjs'
 import { createCoordinationStore } from '../coordination/store.mjs'
-import { detectWorktree } from '../git/worktree-detect.mjs'
 import { parseFlags } from '../util/args.mjs'
 import { err, ok } from '../util/result.mjs'
+import { resolveMainRepoRoot } from '../util/state-paths.mjs'
 
 // QUA-003 / PRF-002 — single source of truth for valid event types.
 // VALID_EVENT_TYPES is the authoritative list; CI_WATCH_EVENT_TYPES is the O(1)
@@ -88,9 +88,11 @@ export function cmdEvent(subcommand, projectDir, extraArgs) {
 	if (!projectDir) return err('Usage: apt-tools event ' + subcommand + ' <project-dir> [flags]')
 
 	const targetDir = resolve(projectDir)
-	// Use shared event dir (coordinates across worktrees via git common dir, same as locks)
-	const wt = detectWorktree(targetDir)
-	const eventsBase = wt.is_worktree && wt.main_repo_root ? wt.main_repo_root : targetDir
+	// Use shared event dir (coordinates across worktrees, same as locks). This is
+	// a SEPARATE policy wrapper over the shared resolveMainRepoRoot mechanism
+	// (state-fork-fix ID-03) — events do NOT follow resolveStateDir's Phase-2
+	// home relocation, so the resolution stays distinct from resolveStateDir.
+	const eventsBase = resolveMainRepoRoot(targetDir)
 	const eventsDir = join(eventsBase, '.aperant', 'events')
 	mkdirSync(eventsDir, { recursive: true })
 

package/src/cli/commands/fan-out.mjs

@@ -14,6 +14,7 @@ import { existsSync, readFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import { parseFlags } from '../util/args.mjs'
 import { err, ok } from '../util/result.mjs'
+import { resolveMainRepoRoot } from '../util/state-paths.mjs'
 
 const ID_PATTERN = /^[a-z0-9_-]+$/i
 
@@ -35,7 +36,8 @@ function parseIdList(raw) {
 }
 
 function readState(targetDir) {
-	const statePath = join(targetDir, '.aperant', 'state.json')
+	// state-fork-fix: ephemeral state read resolves to the main board.
+	const statePath = join(resolveMainRepoRoot(targetDir), '.aperant', 'state.json')
 	if (!existsSync(statePath)) return null
 	try {
 		return JSON.parse(readFileSync(statePath, 'utf-8'))

package/src/cli/commands/features-audit.mjs

@@ -30,6 +30,7 @@ import { loadDocsPolicy, matchSurfaceToPolicy } from '../docs-audit/policy.mjs'
 import { applyStubPatches, auditFeatureRegistry } from '../features/registry-audit.mjs'
 import { parseFlags } from '../util/args.mjs'
 import { err, ok } from '../util/result.mjs'
+import { resolveMainRepoRoot } from '../util/state-paths.mjs'
 
 const TERMINAL_PHASES = new Set(['completed', 'cancelled', 'closed', 'shipped', 'merged'])
 
@@ -138,7 +139,11 @@ function isWorktreeRoot(projectDir) {
 }
 
 function readActiveTasks(projectDir) {
-	const statePath = join(projectDir, '.aperant', 'state.json')
+	// state-fork-fix: read the AUTHORITATIVE main board — readActiveTasks finds
+	// each task's worktree_path for the BUG-025b feature-write redirect, so it
+	// MUST read main or the redirect-target lookup itself forks. (The feature
+	// WRITE path / resolveWriteRoot stays untouched.)
+	const statePath = join(resolveMainRepoRoot(projectDir), '.aperant', 'state.json')
 	if (!existsSync(statePath)) return {}
 	try {
 		const parsed = JSON.parse(readFileSync(statePath, 'utf-8'))

package/src/cli/commands/followups.mjs

@@ -0,0 +1,303 @@
+/**
+ * commands/followups.mjs — `apt-tools followups` (G45).
+ *
+ * The deterministic surface for the per-task follow-ups ledger
+ * ({task_dir}/followups.json). Three subcommands:
+ *
+ *   apt-tools followups check <project-dir> --task-id <id>
+ *     Derive the expected candidate universe (Out of Scope ∪ raw review rows ∪
+ *     qa findings) and report what the ledger is missing / unadjudicated /
+ *     unfixed / undispositioned. Exits 1 when the story is dishonest.
+ *
+ *   apt-tools followups disposition <project-dir> --task-id <id> --row <row-id>
+ *       --kind <filed_task|executed_commit|parked_note|dropped_by_user> --ref <ref>
+ *       [--reason <text>]
+ *     Flip a row to `dispositioned` with the validated disposition record
+ *     (atomic write). `dropped_by_user` additionally requires --reason.
+ *
+ *   apt-tools followups policy <project-dir> --task-id <id>
+ *     Return the effective disposition policy (ask | file | chain +
+ *     max_chain_depth) from config.followups when set, else autonomy-derived.
+ *
+ * Shared-root resolution + taskDir + taskRecord + config all come from
+ * buildGateContext so a worktree-resident invocation reads/writes the same
+ * followups.json the gates read (the L5 worktree concern, plan-approval.mjs).
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+import { parseUserOutcomes } from '../coverage-check/user-outcomes.mjs'
+import {
+	computeMissingExpected,
+	deriveExpectedCandidates,
+	validateOutcomeRefs,
+} from '../followups/derive.mjs'
+import {
+	DISPOSITION_KINDS,
+	listLoadBearingUnfixed,
+	listUnadjudicatedOpen,
+	listUndispositioned,
+	parseFollowups,
+} from '../followups/schema.mjs'
+import { buildGateContext } from '../gate/context.mjs'
+import { parseFlags } from '../util/args.mjs'
+import { atomicWriteJson, readJsonIfExists } from '../util/io.mjs'
+import { err, exitWith, ok } from '../util/result.mjs'
+
+const SUBCOMMANDS = new Set(['check', 'disposition', 'policy'])
+
+function readTextIfExists(path) {
+	if (!existsSync(path)) return null
+	try {
+		return readFileSync(path, 'utf-8')
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Entry: `apt-tools followups <subcommand> <project-dir> [flags]`.
+ */
+export function cmdFollowups(subcommand, projectDir, extraArgs) {
+	if (!subcommand || !SUBCOMMANDS.has(subcommand)) {
+		return err(
+			'Usage: apt-tools followups <check|disposition|policy> <project-dir> --task-id <id> [...]',
+			1,
+			{ command: 'followups' },
+		)
+	}
+	if (!projectDir) {
+		return err('project-dir is required', 1, { command: `followups-${subcommand}` })
+	}
+	const absProjectDir = resolve(projectDir)
+	if (!existsSync(absProjectDir)) {
+		return err(`project directory not found: ${absProjectDir}`, 1, {
+			command: `followups-${subcommand}`,
+		})
+	}
+
+	const flags = parseFlags(extraArgs ?? [])
+	const taskId = flags.get('task-id')
+	if (typeof taskId !== 'string' || taskId.trim() === '') {
+		return err('--task-id <id> is required', 1, { command: `followups-${subcommand}` })
+	}
+
+	let ctx
+	try {
+		ctx = buildGateContext(absProjectDir, taskId)
+	} catch (e) {
+		return err(`task not found: ${taskId} (${e?.message ?? String(e)})`, 1, {
+			command: `followups-${subcommand}`,
+		})
+	}
+
+	if (subcommand === 'check') return doCheck(ctx)
+	if (subcommand === 'disposition') return doDisposition(ctx, flags)
+	return doPolicy(ctx)
+}
+
+/**
+ * `followups check` — the deterministic adjudication-readiness envelope (AC5).
+ */
+function doCheck(ctx) {
+	const followupsPath = join(ctx.taskDir, 'followups.json')
+	const specPath = join(ctx.taskDir, 'spec.md')
+	const reviewPath = join(ctx.taskDir, 'review.json')
+	const qaPath = join(ctx.taskDir, 'qa_signoff.json')
+
+	const specContent = readTextIfExists(specPath)
+	const review = readJsonIfExists(reviewPath)
+	const qa = readJsonIfExists(qaPath)
+
+	const candidates = deriveExpectedCandidates({ specContent, review, qa })
+	const ledgerDoc = readJsonIfExists(followupsPath)
+	const ledger_present = ledgerDoc !== null
+
+	const parsed = parseFollowups(ledgerDoc ?? { rows: [] })
+	const parsedOutcomes = parseUserOutcomes(specContent ?? '')
+
+	const missing_expected = computeMissingExpected(candidates, parsed.rows)
+	const invalid_outcome_refs = validateOutcomeRefs(parsed.rows, parsedOutcomes)
+	const unadjudicated_open = listUnadjudicatedOpen(parsed)
+	const load_bearing_unfixed = listLoadBearingUnfixed(parsed)
+	const undispositioned = listUndispositioned(parsed)
+
+	// Exit 1 when the ledger is absent while candidates exist (adoption forcing
+	// function), or when derivation/schema/outcome-ref validation fails. The
+	// unadjudicated / load-bearing / undispositioned lists are reported but do
+	// NOT fail `check` directly — those are gate concerns (ship gate / close
+	// gate) so an in-progress verify pass can iterate without `check` flapping.
+	const derivationFailure =
+		(!ledger_present && candidates.length > 0) ||
+		missing_expected.length > 0 ||
+		invalid_outcome_refs.length > 0 ||
+		parsed.schema_errors.length > 0
+
+	const envelope = {
+		status: derivationFailure ? 'fail' : 'ok',
+		command: 'followups-check',
+		task_id: ctx.taskId,
+		ledger_present,
+		expected_total: candidates.length,
+		ledger_rows: parsed.rows.length,
+		schema_errors: parsed.schema_errors,
+		missing_expected,
+		invalid_outcome_refs,
+		unadjudicated_open: unadjudicated_open.map(rowSummary),
+		load_bearing_unfixed: load_bearing_unfixed.map(rowSummary),
+		undispositioned: undispositioned.map(rowSummary),
+	}
+	return exitWith(envelope, derivationFailure ? 1 : 0)
+}
+
+/**
+ * `followups disposition` — flip a row to dispositioned (AC7).
+ */
+function doDisposition(ctx, flags) {
+	const rowId = flags.get('row')
+	if (typeof rowId !== 'string' || rowId.trim() === '') {
+		return err('--row <row-id> is required', 1, { command: 'followups-disposition' })
+	}
+	const kind = flags.get('kind')
+	if (!DISPOSITION_KINDS.has(kind)) {
+		return err(`--kind must be one of: ${[...DISPOSITION_KINDS].join(', ')}`, 1, {
+			command: 'followups-disposition',
+		})
+	}
+	const ref = flags.get('ref')
+	if (typeof ref !== 'string' || ref.trim() === '') {
+		return err('--ref <ref> is required (non-empty)', 1, { command: 'followups-disposition' })
+	}
+	const reasonRaw = flags.get('reason')
+	const reason = typeof reasonRaw === 'string' ? reasonRaw : null
+	if (kind === 'dropped_by_user' && !reason) {
+		return err('--kind dropped_by_user requires --reason "<text>"', 1, {
+			command: 'followups-disposition',
+		})
+	}
+
+	const followupsPath = join(ctx.taskDir, 'followups.json')
+	const ledgerDoc = readJsonIfExists(followupsPath)
+	if (ledgerDoc === null) {
+		return err(`followups.json not found for ${ctx.taskId}`, 1, {
+			command: 'followups-disposition',
+		})
+	}
+	const parsed = parseFollowups(ledgerDoc)
+	// Fail closed on schema errors: the write-back below re-serializes only the
+	// validated `parsed.rows`, so a single malformed row elsewhere in the ledger
+	// would be silently dropped when dispositioning a different row. Refuse and
+	// surface the errors so the operator fixes them first (no silent data loss).
+	if (parsed.schema_errors.length > 0) {
+		return err(
+			`followups.json has ${parsed.schema_errors.length} malformed row(s) — fix them before dispositioning (a write-back would drop them)`,
+			1,
+			{ command: 'followups-disposition', schema_errors: parsed.schema_errors },
+		)
+	}
+	const target = parsed.rows.find((r) => r.id === rowId)
+	if (!target) {
+		return err(`unknown row id: ${rowId}`, 1, {
+			command: 'followups-disposition',
+			known_rows: parsed.rows.map((r) => r.id),
+		})
+	}
+
+	// Atomic flip: re-serialize the full validated row set with the target's
+	// status + disposition updated. The on-disk shape is `{ rows: [...] }`.
+	const disposition = { kind, ref, ...(reason ? { reason } : {}) }
+	const nextRows = parsed.rows.map((r) =>
+		r.id === rowId ? { ...r, status: 'dispositioned', disposition } : r,
+	)
+	atomicWriteJson(followupsPath, { rows: nextRows })
+
+	return ok({
+		status: 'ok',
+		command: 'followups-disposition',
+		task_id: ctx.taskId,
+		row: rowId,
+		disposition,
+	})
+}
+
+/**
+ * `followups policy` — effective disposition policy (AC8 / ID-11).
+ */
+function doPolicy(ctx) {
+	const followupsCfg = ctx.config?.followups ?? {}
+	const explicit = followupsCfg.after_close
+
+	// Resolve the autonomy level: task record first, then config default, else 1.
+	const autonomy =
+		typeof ctx.taskRecord?.autonomy === 'number'
+			? ctx.taskRecord.autonomy
+			: typeof ctx.config?.autonomy?.default === 'number'
+				? ctx.config.autonomy.default
+				: 1
+
+	let after_close
+	let source
+	if (explicit === 'ask' || explicit === 'file' || explicit === 'chain') {
+		after_close = explicit
+		source = 'config'
+	} else {
+		after_close = autonomy <= 1 ? 'ask' : autonomy === 2 ? 'file' : 'chain'
+		source = 'autonomy'
+	}
+
+	// max_chain_depth: default 1; clamp values > 1 to 1 with a warning (v1).
+	let max_chain_depth = 1
+	let clamp_warning = null
+	const rawDepth = followupsCfg.max_chain_depth
+	if (typeof rawDepth === 'number' && Number.isFinite(rawDepth)) {
+		if (rawDepth > 1) {
+			clamp_warning = `max_chain_depth ${rawDepth} clamped to 1 (v1 supports depth-1 only)`
+		} else if (rawDepth >= 1) {
+			max_chain_depth = 1
+		} else {
+			// depth < 1 means no chaining; degrade chain → file.
+			max_chain_depth = 0
+		}
+	}
+
+	// Anti-perpetual-motion: degrade chain → file when the CURRENT task's
+	// triage.json marks it as already a chained descendant at/over the cap.
+	const triagePath = join(ctx.taskDir, 'triage.json')
+	const triage = readJsonIfExists(triagePath)
+	const chainDepth = triage?.extra?.followups_chain?.depth
+	let degraded = false
+	if (after_close === 'chain' && typeof chainDepth === 'number' && chainDepth >= max_chain_depth) {
+		after_close = 'file'
+		degraded = true
+	}
+	// A 0 max_chain_depth (depth < 1 config) also degrades chain → file.
+	if (after_close === 'chain' && max_chain_depth < 1) {
+		after_close = 'file'
+		degraded = true
+	}
+
+	const envelope = {
+		status: 'ok',
+		command: 'followups-policy',
+		task_id: ctx.taskId,
+		after_close,
+		max_chain_depth,
+		source,
+		autonomy,
+	}
+	if (clamp_warning) envelope.warning = clamp_warning
+	if (degraded) envelope.degraded_from_chain = true
+	return ok(envelope)
+}
+
+function rowSummary(r) {
+	return {
+		id: r.id,
+		title: r.title,
+		status: r.status,
+		class_proposed: r.class_proposed,
+		verdict: r.adjudication?.verdict ?? null,
+		disposition_kind: r.disposition?.kind ?? null,
+	}
+}

package/src/cli/commands/health-check.mjs

@@ -9,6 +9,7 @@ import { fileURLToPath } from 'node:url'
 import { getSharedLockDir } from '../util/project.mjs'
 import { err, ok } from '../util/result.mjs'
 import { readSkillInstallState } from '../util/skill-installs.mjs'
+import { resolveMainRepoRoot } from '../util/state-paths.mjs'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
@@ -70,7 +71,8 @@ export function cmdHealthCheck(projectDir) {
 	}
 
 	// 2. Check for stale active_task in state.json
-	const statePath = join(aperantDir, 'state.json')
+	// state-fork-fix: state.json is EPHEMERAL — resolve to the main board.
+	const statePath = join(resolveMainRepoRoot(targetDir), '.aperant', 'state.json')
 	if (existsSync(statePath)) {
 		try {
 			const state = JSON.parse(readFileSync(statePath, 'utf-8'))