@aperant/framework 0.13.0-next.0 → 0.15.0

package/src/cli/gate/gates/followups-adjudicated.mjs

@@ -0,0 +1,158 @@
+/**
+ * @internal
+ * G45 followups-adjudicated — blocking gate for `apt:ship` (full-pipeline only).
+ *
+ * The deterministic part the deferring agent can't talk past: shipping is
+ * blocked until every open follow-up row carries an adjudication and every
+ * load-bearing row is fixed. The ledger derivation also forces adoption —
+ * a spec.md with `## Out of Scope` bullets but no followups.json fails.
+ *
+ * Fails when:
+ *   (a) spec.md has Out of Scope bullets but followups.json is absent
+ *       (adoption forcing function),
+ *   (b) the derived expected universe has rows missing from the ledger,
+ *   (c) any `status: 'open'` row lacks `adjudication`,
+ *   (d) any `verdict: 'load-bearing'` row has `status !== 'fixed'`.
+ *
+ * Skips when:
+ *   - spec.md is absent, OR
+ *   - there are no expected candidates AND no ledger.
+ *
+ * Fast Path Guarantee (ID-12): `applies_to_profile` gates this to
+ * full-pipeline (QUICK/DEBUG → lite → skip). The exemption is regression-
+ * locked by followups-quick-exempt.test.ts (ST7).
+ *
+ * Bypass: only the existing audited `--force --reason` (G42 Phase 1 pattern).
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { parseOutOfScope } from '../../consistency/parse-spec.mjs'
+import { computeMissingExpected, deriveExpectedCandidates } from '../../followups/derive.mjs'
+import {
+	listLoadBearingUnfixed,
+	listUnadjudicatedOpen,
+	parseFollowups,
+} from '../../followups/schema.mjs'
+import { readJsonIfExists } from '../../util/io.mjs'
+import { registerGate } from '../registry.mjs'
+
+function rowSummary(r) {
+	return {
+		id: r.id,
+		title: r.title ?? null,
+		status: r.status ?? null,
+		verdict: r.adjudication?.verdict ?? null,
+	}
+}
+
+const gate = {
+	id: 'followups-adjudicated',
+	description:
+		'followups.json covers every derived candidate, every open row is adjudicated, and every load-bearing row is fixed (skipped if spec.md absent or no candidates + no ledger)',
+	severity: 'blocking',
+	skills: ['ship'],
+	applies_to_profile: (ctx) => ctx.profile === 'full-pipeline',
+	async check(ctx) {
+		const specPath = join(ctx.taskDir, 'spec.md')
+		const followupsPath = join(ctx.taskDir, 'followups.json')
+		const reviewPath = join(ctx.taskDir, 'review.json')
+		const qaPath = join(ctx.taskDir, 'qa_signoff.json')
+		const inputs = [specPath, followupsPath, reviewPath, qaPath]
+
+		if (!existsSync(specPath)) {
+			return {
+				status: 'skip',
+				reason: 'spec.md not present — skipping followups-adjudicated',
+				inputs,
+			}
+		}
+
+		let specContent
+		try {
+			specContent = readFileSync(specPath, 'utf-8')
+		} catch (err) {
+			// existsSync passed but the read failed (TOCTOU race, permission
+			// error). Return a structured fail like the sibling gates
+			// (review-clean, verify-approved) rather than throwing out of the
+			// gate runner — important in the concurrent-worktree environment.
+			return {
+				status: 'fail',
+				reason: `spec.md could not be read: ${err.message}`,
+				inputs,
+			}
+		}
+		const oosBullets = parseOutOfScope(specContent)
+		const review = readJsonIfExists(reviewPath)
+		const qa = readJsonIfExists(qaPath)
+		const candidates = deriveExpectedCandidates({ specContent, review, qa })
+		const ledgerDoc = readJsonIfExists(followupsPath)
+		const ledgerPresent = ledgerDoc !== null
+
+		// Skip when there is nothing to track and no ledger to validate.
+		if (candidates.length === 0 && !ledgerPresent) {
+			return {
+				status: 'skip',
+				reason: 'no expected follow-up candidates and no ledger — nothing to adjudicate',
+				inputs,
+			}
+		}
+
+		// (a) Out of Scope bullets exist but no ledger — adoption forcing function.
+		if (oosBullets.length > 0 && !ledgerPresent) {
+			return {
+				status: 'fail',
+				reason: `spec.md has ${oosBullets.length} Out of Scope bullet(s) but followups.json is absent — run \`apt-tools followups check\` and seed the ledger`,
+				evidence: { out_of_scope_bullets: oosBullets.map((b) => b.text) },
+				inputs,
+			}
+		}
+
+		const parsed = parseFollowups(ledgerDoc ?? { rows: [] })
+
+		// (b) Missing expected rows.
+		const missing = computeMissingExpected(candidates, parsed.rows)
+		if (missing.length > 0) {
+			return {
+				status: 'fail',
+				reason: `${missing.length} expected follow-up row(s) missing from followups.json`,
+				evidence: {
+					missing_expected: missing.map((m) => ({ id: m.id, title: m.title, origin: m.origin })),
+				},
+				inputs,
+			}
+		}
+
+		// (c) Open rows lacking adjudication.
+		const unadjudicated = listUnadjudicatedOpen(parsed)
+		if (unadjudicated.length > 0) {
+			return {
+				status: 'fail',
+				reason: `${unadjudicated.length} open follow-up row(s) lack adjudication`,
+				evidence: { unadjudicated_open: unadjudicated.map(rowSummary) },
+				inputs,
+			}
+		}
+
+		// (d) Load-bearing rows not fixed.
+		const loadBearing = listLoadBearingUnfixed(parsed)
+		if (loadBearing.length > 0) {
+			return {
+				status: 'fail',
+				reason: `${loadBearing.length} load-bearing follow-up row(s) not fixed`,
+				evidence: { load_bearing_unfixed: loadBearing.map(rowSummary) },
+				inputs,
+			}
+		}
+
+		return {
+			status: 'pass',
+			reason: `followups.json adjudicated (${parsed.rows.length} row(s), ${candidates.length} expected candidate(s))`,
+			inputs,
+		}
+	},
+}
+
+registerGate(gate)
+export default gate

package/src/cli/gate/gates/index.mjs

@@ -16,6 +16,7 @@ import './plan-exists.mjs'
 import './all-subtasks-complete.mjs'
 import './verify-approved.mjs'
 import './review-clean.mjs'
+import './followups-adjudicated.mjs'
 import './gitignore-in-sync.mjs'
 import './consistency-check.mjs'
 import './tdd-iron-law.mjs'

package/src/cli/git/materialize-env.mjs

@@ -0,0 +1,212 @@
+/**
+ * git/materialize-env.mjs — framework-CLI env materialization seam (ID-06).
+ *
+ * Subtask 2 of `build-unified-per-project-env-secrets-ma_16-06-26` (#354). The
+ * third worktree-create seam: after `apt-tools worktree create --task` adds a
+ * worktree, write the project's stored env file blobs verbatim into it so a CLI
+ * verify-in-worktree run has the same env as the main checkout.
+ *
+ * This is a standalone `.mjs` mirror of the TS core `materializeProjectEnv`
+ * (the framework CLI cannot import the compiled `@aperant/core` helper). It is
+ * deliberately self-contained + best-effort: every failure path returns a
+ * `{ materialized: 0, ... }` envelope instead of throwing, so worktree creation
+ * (the parent op) is never aborted by an env hiccup.
+ *
+ * libSQL `project_env` schema (subtask 1) — keyed `(project_id, rel_path)`:
+ *   project_id TEXT, rel_path TEXT, contents TEXT [may be safeStorage-encrypted
+ *   on the desktop write path], classification TEXT, fingerprint TEXT, updated_at TEXT.
+ *
+ * Encryption caveat: the desktop write path wraps `contents` with Electron's
+ * safeStorage `CryptoProvider`, which a standalone Node CLI cannot decrypt. We
+ * write whatever the column holds — plaintext in self-hosted/CLI contexts
+ * (`CryptoProvider` absent), opaque otherwise. That mirrors the libSQL
+ * backend's own plaintext-fallback robustness and is the documented framework
+ * limitation; the desktop seams (pipeline + terminal) decrypt via the store.
+ */
+
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path'
+
+/** Resolve the shared libSQL DB path: APERANT_DB_PATH override → ~/.aperant/data.db. */
+function resolveDbPath() {
+	const raw = process.env.APERANT_DB_PATH
+	if (raw && raw.trim().length > 0) return raw
+	return join(homedir(), '.aperant', 'data.db')
+}
+
+/**
+ * Reject a rel_path that is absolute or escapes the worktree root BEFORE any
+ * write (the traversal guard, mirroring the core `assertPathContained` choke
+ * point). Returns the resolved absolute target, or null when unsafe.
+ *
+ * Exported so the security-sensitive guard can be unit-tested directly: the
+ * libSQL-backed `materializeProjectEnvCli` can only no-op in environments where
+ * `@libsql/client` is unresolvable (the framework test runner), so the pure
+ * guard is the testable load-bearing surface.
+ */
+export function resolveContainedTarget(worktreePath, relPath) {
+	if (!relPath || isAbsolute(relPath)) return null
+	const base = resolve(worktreePath)
+	const target = resolve(base, relPath)
+	if (target !== base && !target.startsWith(base + sep)) return null
+	return target
+}
+
+/** sha256 hex of a file's verbatim text — drift comparison only (ID-07). */
+function fingerprint(contents) {
+	return createHash('sha256').update(contents, 'utf-8').digest('hex')
+}
+
+/** Lazily open the shared libSQL DB, or null when absent / @libsql unavailable. */
+async function openDb() {
+	const dbPath = resolveDbPath()
+	if (!existsSync(dbPath)) return null
+	let createClient
+	try {
+		;({ createClient } = await import('@libsql/client'))
+	} catch {
+		// @libsql/client not installed in this consumer — best-effort no-op.
+		return null
+	}
+	try {
+		return createClient({ url: `file:${dbPath}` })
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Resolve the libSQL `projects.id` for a given project root path. The desktop /
+ * self-hosted app keys `project_env` rows by the project's stored id, NOT its
+ * path; the framework CLI only knows the path, so we match it against the
+ * `projects.path` column. Returns null when the project is unknown to libSQL
+ * (e.g. a fresh repo never opened in the app) — the caller treats that as
+ * "no env to materialize", never an error.
+ */
+export async function resolveProjectIdFromPath(client, projectPath) {
+	if (!client) return null
+	const wanted = resolve(projectPath)
+	try {
+		const result = await client.execute({ sql: 'SELECT id, path FROM projects', args: [] })
+		for (const row of result.rows) {
+			if (row.path != null && resolve(String(row.path)) === wanted) {
+				return String(row.id)
+			}
+		}
+	} catch {
+		// projects table absent or unreadable — no project id.
+	}
+	return null
+}
+
+/**
+ * Read every `project_env` row for a project from an open libSQL client.
+ * Returns `[]` (never throws) when the table is absent or projectId is null.
+ *
+ * @returns Promise<Array<{ relPath, contents, classification, fingerprint }>>
+ */
+async function readProjectEnvRows(client, projectId) {
+	if (!client || !projectId) return []
+	try {
+		const result = await client.execute({
+			sql: 'SELECT rel_path, contents, classification, fingerprint FROM project_env WHERE project_id = ? ORDER BY rel_path ASC',
+			args: [projectId],
+		})
+		return result.rows.map((row) => ({
+			relPath: String(row.rel_path),
+			contents: row.contents == null ? '' : String(row.contents),
+			classification: String(row.classification),
+			fingerprint: String(row.fingerprint),
+		}))
+	} catch {
+		// Missing table (project_env never created) or read error — no-op.
+		return []
+	}
+}
+
+/** Close a libSQL client best-effort (never throws). */
+function closeDb(client) {
+	try {
+		client?.close?.()
+	} catch {
+		/* best-effort */
+	}
+}
+
+/**
+ * Materialize the project's stored env blobs verbatim into a worktree.
+ *
+ * @param worktreePath  absolute path of the target worktree
+ * @param projectPath   absolute path of the main project root (used to resolve
+ *                      the libSQL project id via `projects.path`)
+ * @param explicitProjectId optional override when the caller already knows the id
+ * @returns { materialized, rejected, errored } counts — never throws.
+ */
+export async function materializeProjectEnvCli(worktreePath, projectPath, explicitProjectId) {
+	const client = await openDb()
+	try {
+		const projectId = explicitProjectId || (await resolveProjectIdFromPath(client, projectPath))
+		const rows = await readProjectEnvRows(client, projectId)
+		let materialized = 0
+		let rejected = 0
+		let errored = 0
+
+		for (const row of rows) {
+			const target = resolveContainedTarget(worktreePath, row.relPath)
+			if (!target) {
+				rejected += 1
+				continue
+			}
+			try {
+				mkdirSync(dirname(target), { recursive: true })
+				writeFileSync(target, row.contents, 'utf-8')
+				materialized += 1
+			} catch {
+				errored += 1
+			}
+		}
+
+		return { materialized, rejected, errored }
+	} finally {
+		closeDb(client)
+	}
+}
+
+/**
+ * Detect drift for an already-materialized worktree (ID-07): compare each
+ * stored blob's fingerprint against the on-disk file. Returns per-file verdicts;
+ * `sync-env` simply re-runs `materializeProjectEnvCli` to overwrite.
+ *
+ * @returns { hasDrift, files: [{ relPath, status }] } — never throws.
+ */
+export async function detectEnvDriftCli(worktreePath, projectPath, explicitProjectId) {
+	const client = await openDb()
+	try {
+		const projectId = explicitProjectId || (await resolveProjectIdFromPath(client, projectPath))
+		const rows = await readProjectEnvRows(client, projectId)
+		const files = []
+		for (const row of rows) {
+			const target = resolveContainedTarget(worktreePath, row.relPath)
+			if (!target || !existsSync(target)) {
+				files.push({ relPath: row.relPath, status: 'missing' })
+				continue
+			}
+			let onDisk
+			try {
+				onDisk = readFileSync(target, 'utf-8')
+			} catch {
+				files.push({ relPath: row.relPath, status: 'missing' })
+				continue
+			}
+			files.push({
+				relPath: row.relPath,
+				status: fingerprint(onDisk) === row.fingerprint ? 'in-sync' : 'drifted',
+			})
+		}
+		return { hasDrift: files.some((f) => f.status !== 'in-sync'), files }
+	} finally {
+		closeDb(client)
+	}
+}

package/src/cli/help.mjs

@@ -19,6 +19,9 @@ Commands:
   config upgrade-layout <dir> [--dry-run]     Migrate .aperant/ folder layout to C36 shape (moves + rewrites gitignore)
   audit privacy <dir> [--scrub]         C35: diff tracked .aperant/* vs share policy (exit 2 on violations; --scrub prints filter-repo commands + checklist, never executes)
   audit visibility-signals <dir>         C35: structured JSON signals for /apt:setup's visibility mini-flow
+  merge detect <dir> [--base <ref>] [--head <ref>]   Trial-merge mergeability probe (reuses audit branch-current detection); emits {mergeable, conflicts_preview?} for apt:merge-conflict-resolution
+  merge markers <dir>                    Read on-disk conflict markers from the unmerged worktree so the agent can resolve them inline; emits {conflicted, files:[{path,content}]}
+  merge integrate <dir> --tasks <ids> | --batch <id> [--base <ref>]   Serialize a fan-out batch into base: order tasks (topological on depends_on, else stable), probe each PR's mergeability (reuses merge detect), emit an integration report for apt:fan-out §5
   state-update <dir> --field --value    Update a state field
   detect-project <project-dir>          Scan project for init classification
   init-state <dir> --config <json>      Write config + state after init flow
@@ -74,9 +77,10 @@ Commands:
 
   standards <project-dir> [--profile <name>] [--json] [--no-color]   C20: zero-orchestration read-only bundle (constitution + profile + feature registry + design tokens + taste)
 
-  worktree create <dir> --subtask <id> --branch <name>  Create isolated worktree for a subtask
+  worktree create <dir> --subtask <id> --branch <name>  Create isolated worktree for a subtask (also materializes the project's stored env blobs into the new worktree, #354)
   worktree remove <dir> --subtask <id> [--force]        Remove a subtask worktree
   worktree list <dir>                                   List active worktrees under .aperant/worktrees/
+  worktree sync-env <dir> --task <id> [--scope <s>] [--project-id <id>]  Re-materialize the project's stored env blobs into an existing task worktree (store is source of truth — overwrites, no merge)
 
   detect-worktree <project-dir>          Check if running inside a git worktree
   template <name>                        Output a template (agents-greenfield, agents-brownfield, config, state, gitignore)
@@ -131,6 +135,10 @@ Commands:
   ci-watch start|stop|status|tick <dir> [--pr <N>] [...]   /apt:watch-ci primitives — see SKILL.md for full flag matrix
   ci-watch sweep <dir> --orphaned [--dry-run]              BUG-027: enumerate ci-watches state files, query gh per PR, remove terminal-state (MERGED|CLOSED) entries (manual GC; rate-limited)
 
+  followups check <dir> --task-id <id>                      G45: derive the expected follow-up universe (Out of Scope ∪ raw review rows ∪ qa findings) + report missing/unadjudicated/unfixed/undispositioned rows; exit 1 when the ledger is dishonest
+  followups disposition <dir> --task-id <id> --row <row-id> --kind <filed_task|executed_commit|parked_note|dropped_by_user> --ref <ref> [--reason <text>]   G45: flip a ledger row to dispositioned (atomic; dropped_by_user requires --reason)
+  followups policy <dir> --task-id <id>                     G45: effective disposition policy (ask|file|chain + max_chain_depth) from config.followups when set, else autonomy-derived
+
 Flags:
   --version                             Print version and exit
   --help                                Print usage and exit

package/src/cli/install/legacy-paths.mjs

@@ -102,6 +102,7 @@ export const LEGACY_INSTALL_PATHS = Object.freeze({
 			'agents/apt-fan-out.md',
 			'agents/apt-handoff.md',
 			'agents/apt-improve.md',
+			'agents/apt-merge-conflict-resolution.md',
 			'agents/apt-mockup.md',
 			'agents/apt-pause.md',
 			'agents/apt-personas.md',
@@ -146,6 +147,7 @@ export const LEGACY_INSTALL_PATHS = Object.freeze({
 			'commands/apt-fan-out.md',
 			'commands/apt-handoff.md',
 			'commands/apt-improve.md',
+			'commands/apt-merge-conflict-resolution.md',
 			'commands/apt-mockup.md',
 			'commands/apt-pause.md',
 			'commands/apt-personas.md',
@@ -180,6 +182,7 @@ export const LEGACY_INSTALL_PATHS = Object.freeze({
 			'agents/apt-planner.md',
 			'agents/apt-pr-review-codebase-fit.md',
 			'agents/apt-pr-review-fixer.md',
+			'agents/apt-pr-review-i18n.md',
 			'agents/apt-pr-review-logic.md',
 			'agents/apt-pr-review-performance.md',
 			'agents/apt-pr-review-quality.md',
@@ -187,6 +190,7 @@ export const LEGACY_INSTALL_PATHS = Object.freeze({
 			'agents/apt-pr-review-self-reviewer.md',
 			'agents/apt-pr-review-test-integrity.md',
 			'agents/apt-pr-review-validator.md',
+			'agents/apt-pr-review-xplatform.md',
 			'agents/apt-researcher.md',
 			'agents/apt-reviewer.md',
 			'agents/apt-team-docs-narrator.md',

package/src/cli/roadmap/lifecycle.mjs

@@ -12,6 +12,7 @@
 
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { resolveMainRepoRoot } from '../util/state-paths.mjs'
 import { loadRoadmapForScope, saveRoadmapForScope } from './io.mjs'
 import { applyRollup } from './rollup.mjs'
 import { syncRoadmapInProcess } from './sync.mjs'
@@ -78,7 +79,9 @@ export function applyLifecyclePhaseSideEffect(targetDir, task, spec, reasonPrefi
 	if (spec.to === 'completed') {
 		let stateBlob = opts.stateBlob
 		if (!stateBlob) {
-			const statePath = join(targetDir, '.aperant', 'state.json')
+			// state-fork-fix: ephemeral sibling-count read resolves to the main
+			// board (the committable roadmapDir read above stays worktree-local).
+			const statePath = join(resolveMainRepoRoot(targetDir), '.aperant', 'state.json')
 			if (existsSync(statePath)) {
 				try {
 					stateBlob = JSON.parse(readFileSync(statePath, 'utf-8'))

package/src/cli/task/ids.mjs

@@ -45,6 +45,15 @@ export function generateTaskId(description, config, now = new Date()) {
 	return `${slug}_${date}`
 }
 
+/**
+ * Build the `.aperant/tasks/<id>/` directory path.
+ *
+ * state-fork-fix: `tasks/` is EPHEMERAL, so callers pass the resolved main-repo
+ * state root (`resolveMainRepoRoot(projectDir)`) as `projectDir` — the redirect
+ * stays visible at each call site rather than being hidden inside this builder.
+ * `resolve()` is idempotent on an already-absolute root, so passing the resolved
+ * root is safe.
+ */
 export function getTaskDir(projectDir, taskId) {
 	return join(resolve(projectDir), '.aperant', 'tasks', taskId)
 }

package/src/cli/task/index-md.mjs

@@ -6,14 +6,21 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { loadMergedProjectConfig } from '../config/load.mjs'
 import { withFileLock } from '../util/fs-lock.mjs'
+import { resolveMainRepoRoot } from '../util/state-paths.mjs'
 import { formatDateDisplay, formatTimeDisplay } from './format.mjs'
 
 /**
  * Regenerate .aperant/tasks/INDEX.md from state.json.
  * One line per task — lightweight project task management view.
+ *
+ * state-fork-fix: both the state.json READ and the tasks/INDEX.md WRITE are
+ * ephemeral, so they resolve to the MAIN repo from any worktree cwd. Config
+ * (loadMergedProjectConfig below) stays on the raw targetDir — config.json /
+ * config.local.json are committable + per-device, not the ephemeral board.
  */
 export function regenerateTaskIndex(targetDir) {
-	const statePath = join(targetDir, '.aperant', 'state.json')
+	const stateRoot = resolveMainRepoRoot(targetDir)
+	const statePath = join(stateRoot, '.aperant', 'state.json')
 	if (!existsSync(statePath)) return
 
 	// AUDIT-001: read through the merged loader so per-device
@@ -90,14 +97,15 @@ export function regenerateTaskIndex(targetDir) {
 
 	lines.push('', `*Auto-generated by apt-tools \u2014 ${new Date().toISOString()}*`, '')
 
-	const indexPath = join(targetDir, '.aperant', 'tasks', 'INDEX.md')
-	mkdirSync(join(targetDir, '.aperant', 'tasks'), { recursive: true })
+	const indexPath = join(stateRoot, '.aperant', 'tasks', 'INDEX.md')
+	mkdirSync(join(stateRoot, '.aperant', 'tasks'), { recursive: true })
 	// Lock-protected — C28 R4. Concurrent regenerators must not interleave.
+	// Lock root moves with the file (state-fork-fix ID-06).
 	withFileLock(
 		indexPath,
 		() => {
 			writeFileSync(indexPath, lines.join('\n'), 'utf-8')
 		},
-		{ projectRoot: targetDir },
+		{ projectRoot: stateRoot },
 	)
 }

package/src/cli/util/io.mjs

@@ -5,7 +5,7 @@
  * match the originals byte-for-byte; the CLI snapshot harness enforces this.
  */
 
-import { readFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -17,6 +17,20 @@ export { appendJsonl, atomicWriteJson, atomicWriteText } from './atomic-write.mj
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
 
+/**
+ * Read + JSON-parse a file if it exists, returning null when the file is
+ * absent OR unparseable (malformed JSON is a non-fatal "no document" signal
+ * for the callers that use this — gates / followups CLI). Never throws.
+ */
+export function readJsonIfExists(path) {
+	if (!existsSync(path)) return null
+	try {
+		return JSON.parse(readFileSync(path, 'utf-8'))
+	} catch {
+		return null
+	}
+}
+
 /**
  * Read framework package.json and return a "<name> <version>" identity string.
  * Resolves relative to this module's location so the CLI keeps its own

package/src/cli/util/project.mjs

@@ -9,7 +9,7 @@
 
 import { existsSync, mkdirSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
-import { detectWorktree } from '../git/worktree-detect.mjs'
+import { resolveMainRepoRoot } from './state-paths.mjs'
 
 /**
  * Walk upward from the target path until we find a `.aperant/` directory.
@@ -28,19 +28,16 @@ export function findProjectRootFromPath(filePath) {
 }
 
 /**
- * Get the shared lock directory — uses git common dir so locks coordinate
- * across worktrees. Falls back to local .aperant/locks/ if not in git.
+ * Get the shared lock directory — resolves to the main repo's .aperant/locks/
+ * from any worktree so locks coordinate across worktrees. Falls back to the
+ * resolved local .aperant/locks/ if not in git.
+ *
+ * This is a SEPARATE policy wrapper over the shared resolveMainRepoRoot
+ * mechanism (state-fork-fix ID-03) — locks are short-lived and do NOT follow
+ * resolveStateDir's Phase-2 home relocation, so the two stay distinct.
  */
 export function getSharedLockDir(projectDir) {
-	const wt = detectWorktree(projectDir)
-	if (wt.is_worktree && wt.main_repo_root) {
-		// Use main repo's .aperant/locks/ so all worktrees share the same locks
-		const sharedDir = join(wt.main_repo_root, '.aperant', 'locks')
-		mkdirSync(sharedDir, { recursive: true })
-		return sharedDir
-	}
-	// Not a worktree — use local
-	const localDir = join(resolve(projectDir), '.aperant', 'locks')
-	mkdirSync(localDir, { recursive: true })
-	return localDir
+	const sharedDir = join(resolveMainRepoRoot(projectDir), '.aperant', 'locks')
+	mkdirSync(sharedDir, { recursive: true })
+	return sharedDir
 }

package/src/cli/util/state-paths.mjs

@@ -0,0 +1,45 @@
+/**
+ * state-paths.mjs — the single home for "resolve the ephemeral .aperant/
+ * board to the main repo from any worktree" (state-fork-fix, Phase 1).
+ *
+ * `resolveMainRepoRoot` is the ONE low-level MECHANISM. It replaces the three
+ * hand-rolled copies of the `wt.is_worktree && wt.main_repo_root` redirect in
+ * `getSharedLockDir` / `commands/event.mjs` / `coordination/agent-identity.mjs`.
+ * It is null-guarded: `detectWorktree` returns `main_repo_root: null` AND
+ * `worktree_root: null` on a non-git dir (git/worktree-detect.mjs:46-53), so we
+ * NEVER feed `null` into `join()` and NEVER throw on a non-git input.
+ *
+ * `resolveStateDir` is the thin POLICY wrapper scoped to `state.json` + `tasks/`
+ * only — the only wrapper Phase 2 repoints (to an XDG home). It is NOT used to
+ * build any committable path (`roadmap/`, `features/`, `config.json`, ...).
+ */
+
+import { join, resolve } from 'node:path'
+import { detectWorktree } from '../git/worktree-detect.mjs'
+
+/**
+ * Resolve the main repo root from any cwd shape.
+ *  - worktree cwd        → the main repo root (so all worktrees share one board)
+ *  - git, non-worktree   → the git toplevel
+ *  - non-git dir         → resolve(projectDir) (null-guarded fallback, never null)
+ *
+ * @param {string} projectDir
+ * @returns {string}
+ */
+export function resolveMainRepoRoot(projectDir) {
+	const wt = detectWorktree(projectDir)
+	if (wt.is_worktree && wt.main_repo_root) return wt.main_repo_root
+	if (wt.worktree_root) return wt.worktree_root
+	return resolve(projectDir)
+}
+
+/**
+ * The `.aperant` directory holding the ephemeral board (`state.json` + `tasks/`),
+ * resolved to the main repo from any cwd. Phase 1 body; Phase 2 repoints this.
+ *
+ * @param {string} projectDir
+ * @returns {string}
+ */
+export function resolveStateDir(projectDir) {
+	return join(resolveMainRepoRoot(projectDir), '.aperant')
+}