@aperant/framework 0.10.0 → 0.12.0

package/src/cli/commands/route.mjs

@@ -32,7 +32,12 @@ import {
 	getTaskIsolationConfig,
 	getTrustedSkillSources,
 	loadMergedProjectConfig,
+	loadProjectConfig,
 } from '../config/load.mjs'
+import { resolveSharePolicy } from '../config/share-policy.mjs'
+import { computeCatchUpPanel } from '../coordination/catch-up.mjs'
+import { createCoordinationStore } from '../coordination/store.mjs'
+import { resolveLocalDefaultBranch } from '../git/default-branch.mjs'
 import '../gate/gates/index.mjs'
 import * as gateRegistry from '../gate/registry.mjs'
 import { detectHost, SUPPORTED_HOSTS } from '../host/detect.mjs'
@@ -96,6 +101,78 @@ function readUpdateCheckCache() {
 	return null
 }
 
+/**
+ * Is this an interactive (TTY) apt call? The catch-up panel + Last-Seen Marker
+ * are gated to interactive contexts (LD-02) — exactly like the statusline
+ * isTTY gate — so spawned subagents, fan-out workers, and non-TTY/piped calls
+ * are strict no-ops (they neither read nor write the marker). `APT_FORCE_TTY`
+ * forces the gate open for tests; `APT_CATCH_UP_DISABLE` forces it closed so a
+ * background spawner can opt every nested call out.
+ */
+function isInteractiveTty() {
+	if (process.env.APT_CATCH_UP_DISABLE === '1') return false
+	if (process.env.APT_FORCE_TTY === '1') return true
+	return Boolean(process.stdout?.isTTY || process.stderr?.isTTY)
+}
+
+/**
+ * Lazy-compute the catch-up panel for an interactive call and advance the
+ * Last-Seen Marker AFTER the panel is evaluated (R2/LD-02). Returns the panel
+ * (or null) to fold onto the route envelope as a top-level `catch_up` field.
+ *
+ * Marker-advance ordering (correctness-critical):
+ *   - last_run_at    = now              — always (engagement, not greeting);
+ *   - last_main_sha  = defaultBranch.sha — only AFTER the digest was computed,
+ *                                          i.e. only when we resolved a branch
+ *                                          (even when the digest is empty);
+ *   - last_active_task = welcome-back task id, when present.
+ *
+ * Non-TTY callers never reach this function (the caller gates on
+ * isInteractiveTty), so background/spawned calls never touch the marker.
+ *
+ * @param {string} targetDir
+ * @returns {object|null} the catch_up panel, or null.
+ */
+function computeCatchUpForRoute(targetDir) {
+	// Setup mirrors cmdCatchUp in commands/catch-up.mjs (recompute-only variant).
+	const config = loadProjectConfig(targetDir)
+	if (!config) return null
+
+	const store = createCoordinationStore(targetDir)
+	const marker = store.readLastSeen()
+	const td = config?.collaboration?.team_digest
+	const vis = resolveSharePolicy(config).visibility
+	const needsDigest = td?.enabled !== false && (vis === 'team' || vis === 'oss')
+	const defaultBranch = needsDigest ? resolveLocalDefaultBranch(targetDir) : null
+	const now = Date.now()
+
+	let panel = null
+	try {
+		panel = computeCatchUpPanel(targetDir, {
+			config,
+			now,
+			marker,
+			defaultBranch,
+		})
+	} catch (e) {
+		console.warn('[apt] catch-up:', e?.message ?? e)
+		panel = null
+	}
+
+	// Advance the marker AFTER panel eval. last_main_sha only when we actually
+	// resolved a default branch (the digest was computed, possibly empty).
+	const advance = { last_run_at: new Date(now).toISOString() }
+	if (defaultBranch?.sha) advance.last_main_sha = defaultBranch.sha
+	if (panel?.welcome_back?.task_id) advance.last_active_task = panel.welcome_back.task_id
+	try {
+		store.advanceLastSeen(advance)
+	} catch {
+		/* best-effort — never block routing on a marker write */
+	}
+
+	return panel
+}
+
 /**
  * Deterministic mapping from an explicit track flag (--quick/--deep/--debug)
  * to its canonical {track, primary_skill} pair. Flag overrides are user
@@ -309,6 +386,13 @@ export function cmdRoute(projectDir, extraArgs) {
 		}
 	}
 
+	// Catch-up panel (LD-11): lazy-compute on interactive (TTY) calls only, and
+	// only when config exists (init has no config yet). The compute also
+	// advances the Last-Seen Marker after panel eval (LD-02). Non-TTY calls are
+	// strict no-ops — no read, no write, no field. Folded onto every returned
+	// envelope below as a top-level `catch_up` field, mirroring update_check.
+	const catch_up = hasConfig && isInteractiveTty() ? computeCatchUpForRoute(targetDir) : null
+
 	// ---------------- Deterministic branches (zero-behavior-change) ----------------
 	// These fire regardless of host detection status — missing host is not
 	// fatal for init/status/help/skill-passthrough.
@@ -322,6 +406,7 @@ export function cmdRoute(projectDir, extraArgs) {
 			host_capabilities,
 			task_isolation,
 			update_check,
+			catch_up: null,
 			reason: 'No .aperant/config.json found — first-time setup required',
 		})
 	}
@@ -335,6 +420,7 @@ export function cmdRoute(projectDir, extraArgs) {
 			host_capabilities,
 			task_isolation,
 			update_check,
+			catch_up,
 			reason: 'No input provided — showing project status',
 		})
 	}
@@ -348,6 +434,7 @@ export function cmdRoute(projectDir, extraArgs) {
 			host_capabilities,
 			task_isolation,
 			update_check,
+			catch_up,
 			reason: 'Help requested',
 		})
 	}
@@ -395,6 +482,7 @@ export function cmdRoute(projectDir, extraArgs) {
 			host_capabilities,
 			task_isolation,
 			update_check,
+			catch_up,
 			...(gate_preview ? { gate_preview } : {}),
 			reason: `Direct skill invocation: apt:${firstWord}`,
 		})
@@ -444,6 +532,7 @@ export function cmdRoute(projectDir, extraArgs) {
 			host_capabilities,
 			task_isolation,
 			update_check,
+			catch_up,
 			...(gate_preview ? { gate_preview } : {}),
 			...(spar_inject_gates ? { spar_inject_gates } : {}),
 			classification: {
@@ -523,7 +612,9 @@ export function cmdRoute(projectDir, extraArgs) {
 		)
 	}
 
-	return ok(envelope)
+	// Fold the catch-up panel onto the classify envelope as a top-level field,
+	// mirroring update_check (LD-11). null when non-TTY / neither half fires.
+	return ok({ ...envelope, catch_up })
 }
 
 /**

package/src/cli/commands/verify-sandbox.mjs

@@ -0,0 +1,231 @@
+/**
+ * commands/verify-sandbox.mjs — `apt-tools verify-sandbox <projectDir>`.
+ *
+ * Drives runSelfTest() then atomically writes
+ * .aperant/state/verify-proof-sandbox-verified.json with the v2-shaped
+ * verdict envelope. On win32, short-circuits to a platform_unsupported
+ * verdict WITHOUT spawning child processes (ID-06 v1 supported floor =
+ * darwin + linux).
+ *
+ * The state file is written for BOTH verified-true and verified-false
+ * outcomes (ID-02 — no silent state mutation). The sandbox gate at
+ * apt-verify-proof/SKILL.md Step 2c (subtask 5.1) reads this file.
+ */
+
+import { join, resolve } from 'node:path'
+import { atomicWriteJson } from '../util/atomic-write.mjs'
+import { withFileLock } from '../util/fs-lock.mjs'
+import { err, exitWith, ok } from '../util/result.mjs'
+import { loadRuntimeCapabilities } from '../util/runtime-capabilities.mjs'
+import { matchPatternForProject } from '../verify-proof/sandbox/pattern-matcher.mjs'
+import {
+	discoverBundledRecipes,
+	readSandboxConfig,
+} from '../verify-proof/sandbox/sandbox-config.mjs'
+import { runSelfTest } from '../verify-proof/sandbox/self-test.mjs'
+
+/**
+ * @param {string} projectDir
+ * @param {string[]} [extra]
+ */
+export async function cmdVerifySandbox(projectDir, _extra = []) {
+	if (!projectDir) return err('Usage: apt-tools verify-sandbox <project-dir>')
+
+	const target = resolve(projectDir)
+	const platform = process.platform
+	const statePath = join(target, '.aperant', 'state', 'verify-proof-sandbox-verified.json')
+	const at = new Date().toISOString()
+
+	const host = {
+		platform,
+		arch: process.arch,
+		nodeVersion: process.version,
+	}
+
+	// Resolve recipeId from config or runtime detection.
+	const sandboxCfg = readSandboxConfig(target)
+	const recipes = discoverBundledRecipes()
+	let recipeId = sandboxCfg?.recipeId ?? null
+	let recipeVersion = sandboxCfg?.recipeVersion ?? null
+	if (!recipeId) {
+		const runtime = loadRuntimeCapabilities(target)
+		const match = matchPatternForProject(target, runtime, recipes)
+		recipeId = match.recipeId
+	}
+	// Always populate recipeVersion from bundled recipes when absent — covers
+	// the case where config pins recipeId but omits recipeVersion (LOG-003).
+	if (recipeId && !recipeVersion) {
+		recipeVersion = recipes.find((r) => r.recipeId === recipeId)?.recipeVersion ?? null
+	}
+
+	// win32 short-circuit (AC12, ID-06 v1 floor).
+	if (platform === 'win32') {
+		const envelope = {
+			verified: false,
+			verdict: 'needs_human',
+			reason: 'platform_unsupported',
+			recipeId,
+			recipeVersion,
+			verifiedAt: at,
+			host,
+		}
+		const writeErr = writeStateFile(statePath, envelope)
+		if (writeErr) {
+			return exitWith(
+				{
+					status: 'error',
+					command: 'verify-sandbox',
+					code: 'E_STATE_WRITE_FAILED',
+					verdict: 'needs_human',
+					reason: 'state_write_failed',
+					cause: writeErr.message,
+					project_dir: target,
+					state_path: statePath,
+				},
+				1,
+			)
+		}
+		return ok({
+			status: 'ok',
+			command: 'verify-sandbox',
+			project_dir: target,
+			state_path: statePath,
+			...envelope,
+		})
+	}
+
+	if (!recipeId) {
+		const envelope = {
+			verified: false,
+			verdict: 'needs_human',
+			reason: 'no_recipe_available',
+			recipeId: null,
+			recipeVersion: null,
+			verifiedAt: at,
+			host,
+		}
+		const writeErr = writeStateFile(statePath, envelope)
+		if (writeErr) {
+			return exitWith(
+				{
+					status: 'error',
+					command: 'verify-sandbox',
+					code: 'E_STATE_WRITE_FAILED',
+					verdict: 'needs_human',
+					reason: 'state_write_failed',
+					cause: writeErr.message,
+					project_dir: target,
+					state_path: statePath,
+				},
+				1,
+			)
+		}
+		return exitWith(
+			{
+				status: 'error',
+				command: 'verify-sandbox',
+				code: 'E_NO_RECIPE',
+				project_dir: target,
+				state_path: statePath,
+				...envelope,
+			},
+			1,
+		)
+	}
+
+	let result
+	try {
+		result = await runSelfTest({ projectDir: target, recipeId, recipes })
+	} catch (e) {
+		const envelope = {
+			verified: false,
+			verdict: 'needs_human',
+			reason: 'self_test_failed_app_init_timeout',
+			recipeId,
+			recipeVersion,
+			verifiedAt: at,
+			host,
+			error: e?.message ?? String(e),
+		}
+		const writeErr = writeStateFile(statePath, envelope)
+		if (writeErr) {
+			return exitWith(
+				{
+					status: 'error',
+					command: 'verify-sandbox',
+					code: 'E_STATE_WRITE_FAILED',
+					verdict: 'needs_human',
+					reason: 'state_write_failed',
+					cause: writeErr.message,
+					project_dir: target,
+					state_path: statePath,
+				},
+				1,
+			)
+		}
+		return exitWith(
+			{
+				status: 'error',
+				command: 'verify-sandbox',
+				project_dir: target,
+				state_path: statePath,
+				...envelope,
+			},
+			1,
+		)
+	}
+
+	const envelope = {
+		verified: result.verified,
+		verdict: result.verdict,
+		reason: result.reason,
+		recipeId,
+		recipeVersion,
+		verifiedAt: at,
+		host,
+		durationMs: result.durationMs,
+	}
+	const writeErr = writeStateFile(statePath, envelope)
+	if (writeErr) {
+		return exitWith(
+			{
+				status: 'error',
+				command: 'verify-sandbox',
+				code: 'E_STATE_WRITE_FAILED',
+				verdict: 'needs_human',
+				reason: 'state_write_failed',
+				cause: writeErr.message,
+				project_dir: target,
+				state_path: statePath,
+			},
+			1,
+		)
+	}
+
+	const exitCode = result.verified ? 0 : 1
+	return exitWith(
+		{
+			status: result.verified ? 'ok' : 'error',
+			command: 'verify-sandbox',
+			project_dir: target,
+			state_path: statePath,
+			...envelope,
+		},
+		exitCode,
+	)
+}
+
+/**
+ * Write the verdict envelope to the state file under a file lock.
+ * Returns null on success, or an Error if the lock or write fails.
+ */
+function writeStateFile(statePath, envelope) {
+	try {
+		withFileLock(statePath, () => {
+			atomicWriteJson(statePath, envelope)
+		})
+		return null
+	} catch (e) {
+		return e instanceof Error ? e : new Error(String(e))
+	}
+}

package/src/cli/config/share-policy.mjs

@@ -254,6 +254,7 @@ export function buildPolicyIgnoreMatcher(policy) {
 			rest.startsWith('events/') ||
 			rest.startsWith('locks/') ||
 			rest.startsWith('team-status/') ||
+			rest.startsWith('last-seen/') ||
 			rest.startsWith('paused/') ||
 			rest.startsWith('rationalizations/') ||
 			rest === 'digests/.last-run.json' ||

package/src/cli/config/upgrade-gitignore.mjs

@@ -189,6 +189,7 @@ export function buildAperantGitignoreTemplate(policy = DEFAULT_SHARE_POLICY) {
 	// maintainer cannot accidentally un-ignore it with a broad `!config*.json`
 	// allow rule.
 	lines.push('config.local.json')
+	lines.push('last-seen/')
 	lines.push('')
 	lines.push('# ── Derived markdown indexes (regenerated from JSON) ──────────────')
 	lines.push('tasks/INDEX.md')

package/src/cli/consistency/parse-qa.mjs

@@ -7,13 +7,17 @@
  *   - flat findings: findings: [{severity}]
  *   - legacy `issues: [{severity}]`
  *
- * Verdict closed set: {approved, approved-with-notes, rejected, needs-changes}.
- * Anything else -> 'unknown'. Accepts legacy `status` as a fallback field name.
+ * v0.9.0 (verify-proof-v2-outcome-walker_27-05-26) — verdict closed set is
+ * `{approved, rejected, needs_human, needs-changes}`. `approved_with_notes`
+ * is DELETED (no shim) — reading a legacy `approved_with_notes` /
+ * `approved-with-notes` value throws a clear migration error pointing at
+ * the framework CHANGELOG entry. Anything else maps to `'unknown'`.
+ * Accepts legacy `status` as a fallback field name.
  *
  * Output: {verdict, findings: [{severity, title, status, file}]}
  */
 
-const KNOWN_VERDICTS = new Set(['approved', 'approved-with-notes', 'rejected', 'needs-changes'])
+const KNOWN_VERDICTS = new Set(['approved', 'rejected', 'needs-human', 'needs-changes'])
 
 const SEVERITY_MAP = {
 	critical: 'critical',
@@ -56,7 +60,19 @@ function normalizeVerdict(v) {
 	const k = v.toLowerCase().trim()
 	// normalize common spellings
 	const canonical = k.replace(/_/g, '-')
-	return KNOWN_VERDICTS.has(canonical) ? canonical : 'unknown'
+	// v0.9.0 migration: approved_with_notes / approved-with-notes is
+	// DELETED with no shim. Crash loudly so the consumer task is
+	// re-run, not silently re-mapped to `approved`.
+	if (canonical === 'approved-with-notes') {
+		throw new Error(
+			"qa_signoff.json carries the legacy verdict 'approved_with_notes' (or 'approved-with-notes'). " +
+				"This verdict is removed in framework v0.9.0+ (see packages/framework/CHANGELOG.md :: 'verify-proof v2 — outcome walker + two-gate verdict'). " +
+				'Re-run verify-proof on this task to mint a fresh qa_signoff.json with the new {approved, rejected, needs_human} enum.',
+		)
+	}
+	// Accept both snake_case and kebab-case for needs_human.
+	const needsHuman = canonical === 'needs-human' ? 'needs-human' : canonical
+	return KNOWN_VERDICTS.has(needsHuman) ? needsHuman : 'unknown'
 }
 
 function collectRaw(qa) {

package/src/cli/consistency/rules/r5-verdict-consistency.mjs

@@ -3,13 +3,15 @@
  * consistency/rules/r5-verdict-consistency.mjs — R5 (C15).
  *
  * Fails when:
- *   - qa.verdict === 'approved' or 'approved-with-notes' AND review has >=1
- *     unresolved critical or major finding
- *   - qa.verdict === 'rejected' AND qa has no findings at all AND review has
- *     zero unresolved findings (rejected-without-evidence)
+ *   - qa.verdict === 'approved' AND review has >=1 unresolved critical or
+ *     major finding.
+ *   - qa.verdict === 'rejected' AND qa has no findings at all AND review
+ *     has zero unresolved findings (rejected-without-evidence).
  *
- * `approved-with-notes` no longer escapes unresolved critical or major
- * findings (G42 Phase 1). It still passes for lower-severity issues.
+ * v0.9.0 (verify-proof-v2-outcome-walker_27-05-26) — the legacy
+ * `approved-with-notes` branch is REMOVED. The verdict enum is the closed
+ * set `{approved, rejected, needs_human}`. Reading a legacy verdict
+ * crashes in parseQaSignoff before this rule executes.
  *
  * Severity: error. Stages: verify, ship.
  */
@@ -30,10 +32,7 @@ const rule = {
 		const unresolvedBlocking = reviewFindings.filter(
 			(f) => (f.severity === 'critical' || f.severity === 'major') && f.status !== 'fixed',
 		)
-		if (
-			(verdict === 'approved' || verdict === 'approved-with-notes') &&
-			unresolvedBlocking.length > 0
-		) {
+		if (verdict === 'approved' && unresolvedBlocking.length > 0) {
 			return {
 				status: 'fail',
 				drift: [
@@ -43,11 +42,10 @@ const rule = {
 							id: f.id,
 							title: f.title,
 						})),
-						reason:
-							'approved/approved-with-notes verdict with unresolved critical or major finding(s) (G42 Phase 1)',
+						reason: 'approved verdict with unresolved critical or major finding(s) (G42 Phase 1)',
 					},
 				],
-				reason: `approved/approved-with-notes verdict contradicts ${unresolvedBlocking.length} unresolved critical/major finding(s)`,
+				reason: `approved verdict contradicts ${unresolvedBlocking.length} unresolved critical/major finding(s)`,
 			}
 		}
 		if (verdict === 'rejected') {