@aperant/framework 0.9.0 → 0.11.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/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-review.mjs

@@ -97,9 +97,11 @@ function normalizeStatus(f) {
 		if (STATUS_MAP[s]) return STATUS_MAP[s]
 		// BUG-009: reviewer-skill writes `deferred-per-spec`, `deferred-followup`,
 		// etc. for findings that are intentionally not being fixed in the
-		// current scope. Collapse the variant prefix back to canonical
-		// `deferred` so downstream gates (review-clean, ship) treat them
-		// the same as a bare `status: "deferred"`.
+		// current scope. Collapse the variant prefix back to canonical `deferred`.
+		// Note: for blocking severities (critical/major), `deferred` no longer
+		// clears review-clean or R5 (G42 Phase 1). Only `status: "fixed"` clears
+		// those gates. Non-blocking severities (suggestion/note) are dropped by
+		// normalizeSeverity and never reach the blocking filter.
 		if (s.startsWith('deferred-')) return 'deferred'
 	}
 	return 'open'

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

@@ -3,12 +3,13 @@
  * consistency/rules/r5-verdict-consistency.mjs — R5 (C15).
  *
  * Fails when:
- *   - qa.verdict === 'approved' AND review has >=1 unresolved critical finding
+ *   - 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)
  *
- * `approved-with-notes` is the escape hatch — passes regardless of unresolved
- * criticals in review.json.
+ * `approved-with-notes` no longer escapes unresolved critical or major
+ * findings (G42 Phase 1). It still passes for lower-severity issues.
  *
  * Severity: error. Stages: verify, ship.
  */
@@ -26,23 +27,27 @@ const rule = {
 		}
 		const verdict = parsed.qa.verdict ?? 'unknown'
 		const reviewFindings = parsed?.review?.findings ?? []
-		const unresolvedCritical = reviewFindings.filter(
-			(f) => f.severity === 'critical' && f.status !== 'fixed',
+		const unresolvedBlocking = reviewFindings.filter(
+			(f) => (f.severity === 'critical' || f.severity === 'major') && f.status !== 'fixed',
 		)
-		if (verdict === 'approved' && unresolvedCritical.length > 0) {
+		if (
+			(verdict === 'approved' || verdict === 'approved-with-notes') &&
+			unresolvedBlocking.length > 0
+		) {
 			return {
 				status: 'fail',
 				drift: [
 					{
 						verdict,
-						blockers: unresolvedCritical.map((f) => ({
+						blockers: unresolvedBlocking.map((f) => ({
 							id: f.id,
 							title: f.title,
 						})),
-						reason: 'approved verdict with unresolved critical finding(s)',
+						reason:
+							'approved/approved-with-notes verdict with unresolved critical or major finding(s) (G42 Phase 1)',
 					},
 				],
-				reason: `approved verdict contradicts ${unresolvedCritical.length} unresolved critical finding(s)`,
+				reason: `approved/approved-with-notes verdict contradicts ${unresolvedBlocking.length} unresolved critical/major finding(s)`,
 			}
 		}
 		if (verdict === 'rejected') {

package/src/cli/coordination/catch-up.mjs

@@ -0,0 +1,231 @@
+/**
+ * @internal
+ * coordination/catch-up.mjs — composes the combined catch-up panel: the
+ * Welcome-Back Summary (your own half-finished work, local-only) and the
+ * gated Team-Change Digest (what teammates merged while you were away).
+ *
+ * Composition order is fixed: welcome_back first, then team_digest (LD-10).
+ * The renderer (apt/SKILL.md) enforces display order; this module only sets
+ * the field order on the returned object.
+ *
+ * Both halves diff against one Last-Seen Marker:
+ *   - Welcome-Back fires on a staleness threshold (now - last_run_at), reads
+ *     only local state.active_tasks, and is ALWAYS-ON regardless of visibility
+ *     (LD-08/09).
+ *   - Team-Change Digest fires only when share.visibility is team/oss AND the
+ *     local default-branch sha has moved since last_main_sha (LD-04/06/07).
+ *
+ * Returns null when neither half fires. This module is `@internal` — reached
+ * via the route.mjs lazy-compute path and the apt-tools catch-up command, not
+ * from bin/apt-tools.mjs directly.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { resolveSharePolicy } from '../config/share-policy.mjs'
+import { listMergedPullRequests } from '../git/default-branch.mjs'
+import { getGitIdentity } from '../git/identity.mjs'
+import { resolveSharedRoot } from './agent-identity.mjs'
+
+const HOUR_MS = 60 * 60 * 1000
+
+/**
+ * Best-available per-task activity timestamp (ms). Prefers an explicit
+ * updated_at, then the most recent history entry, then created_at.
+ *
+ * @param {object} task
+ * @returns {number} epoch ms, or 0 when no timestamp is parseable.
+ */
+function taskActivityMs(task) {
+	const candidates = []
+	if (task?.updated_at) candidates.push(Date.parse(task.updated_at))
+	if (Array.isArray(task?.history)) {
+		for (const h of task.history) {
+			if (h?.at) candidates.push(Date.parse(h.at))
+		}
+	}
+	if (task?.created_at) candidates.push(Date.parse(task.created_at))
+	const valid = candidates.filter((n) => Number.isFinite(n))
+	return valid.length ? Math.max(...valid) : 0
+}
+
+/**
+ * A coarse "x ago" relative-time string. Kept dependency-free and stable for
+ * tests — granularity is minutes/hours/days.
+ *
+ * @param {number} deltaMs
+ * @returns {string}
+ */
+function relativeTime(deltaMs) {
+	if (!Number.isFinite(deltaMs) || deltaMs < 0) return 'just now'
+	const mins = Math.floor(deltaMs / 60000)
+	if (mins < 1) return 'just now'
+	if (mins < 60) return `${mins}m ago`
+	const hours = Math.floor(mins / 60)
+	if (hours < 24) return `${hours}h ago`
+	const days = Math.floor(hours / 24)
+	return `${days}d ago`
+}
+
+/**
+ * Read the first actionable next-step line from a task's CONTINUE note, if one
+ * exists at `.aperant/tasks/{taskId}/CONTINUE.md`. Parses the first non-empty
+ * item under the `## Next Steps` heading (the pause-note format).
+ *
+ * @param {string} sharedRoot
+ * @param {string} taskId
+ * @returns {string|null}
+ */
+function readNextStepLine(sharedRoot, taskId) {
+	if (!taskId) return null
+	const notePath = join(sharedRoot, '.aperant', 'tasks', taskId, 'CONTINUE.md')
+	if (!existsSync(notePath)) return null
+	let text
+	try {
+		text = readFileSync(notePath, 'utf-8')
+	} catch {
+		return null
+	}
+	const lines = text.split('\n')
+	const headingIdx = lines.findIndex((l) => /^##\s+Next Steps\s*$/i.test(l.trim()))
+	if (headingIdx === -1) return null
+	for (let i = headingIdx + 1; i < lines.length; i++) {
+		const raw = lines[i].trim()
+		if (raw.startsWith('##')) break // next section
+		if (raw.length === 0) continue
+		// Strip a leading list marker: "1. ", "- ", "* ".
+		const cleaned = raw.replace(/^(\d+\.|[-*])\s+/, '').trim()
+		if (cleaned.length > 0) return cleaned
+	}
+	return null
+}
+
+/**
+ * Build the Welcome-Back half from local state (LD-08/09). Returns null when
+ * the threshold has not elapsed or there is no active task.
+ *
+ * @param {object} params
+ * @param {object} params.config
+ * @param {number} params.now           epoch ms
+ * @param {object|null} params.marker
+ * @param {object|null} params.state    raw state.json (for active_tasks)
+ * @param {string} params.sharedRoot
+ * @returns {object|null}
+ */
+function buildWelcomeBack({ config, now, marker, state, sharedRoot }) {
+	const wb = config?.collaboration?.welcome_back
+	if (wb?.enabled === false) return null
+
+	const lastRunAt = marker?.last_run_at ? Date.parse(marker.last_run_at) : NaN
+	const thresholdHours = Number.isFinite(wb?.threshold_hours) ? wb.threshold_hours : 16
+	// Only fire when we have a baseline AND the gap strictly exceeds the threshold.
+	if (!Number.isFinite(lastRunAt)) return null
+	if (now - lastRunAt <= thresholdHours * HOUR_MS) return null
+
+	const activeTasks =
+		state?.active_tasks && typeof state.active_tasks === 'object' ? state.active_tasks : {}
+	const ids = Object.keys(activeTasks)
+	if (ids.length === 0) return null
+
+	// Pick the single most-recently-active task.
+	let bestId = null
+	let bestMs = -1
+	for (const id of ids) {
+		const ms = taskActivityMs(activeTasks[id])
+		if (ms > bestMs) {
+			bestMs = ms
+			bestId = id
+		}
+	}
+	if (!bestId) return null
+
+	const task = activeTasks[bestId]
+	const currentSubtask = task?.progress?.current_subtask ?? task?.current_subtask ?? null
+
+	return {
+		task_id: bestId,
+		description: task?.description ?? bestId,
+		lifecycle_phase: task?.lifecycle_phase ?? null,
+		current_subtask: currentSubtask,
+		progress: task?.progress ?? null,
+		relative_time: bestMs > 0 ? relativeTime(now - bestMs) : null,
+		next_step: readNextStepLine(sharedRoot, bestId),
+		others_count: Math.max(0, ids.length - 1),
+	}
+}
+
+/**
+ * Build the Team-Change Digest half (LD-04/06/07). Returns null when the
+ * visibility gate is closed (solo), the digest is disabled, or the
+ * default-branch sha has not moved since the marker.
+ *
+ * @param {object} params
+ * @param {string} params.projectRoot
+ * @param {object} params.config
+ * @param {object|null} params.marker
+ * @param {{ branch: string, sha: string }|null} params.defaultBranch
+ * @returns {object|null}
+ */
+function buildTeamDigest({ projectRoot, config, marker, defaultBranch }) {
+	const td = config?.collaboration?.team_digest
+	if (td?.enabled === false) return null
+
+	const visibility = resolveSharePolicy(config).visibility
+	if (visibility !== 'team' && visibility !== 'oss') return null
+
+	if (!defaultBranch?.sha) return null
+	// Only fire when main has actually moved since the recorded baseline.
+	if (marker?.last_main_sha && marker.last_main_sha === defaultBranch.sha) return null
+
+	const maxEntries = Number.isInteger(td?.max_entries) && td.max_entries > 0 ? td.max_entries : 7
+	const identity = (() => {
+		try {
+			return getGitIdentity(projectRoot)
+		} catch {
+			return null
+		}
+	})()
+
+	const { entries, more_count } = listMergedPullRequests(projectRoot, {
+		sinceSha: marker?.last_main_sha || null,
+		defaultBranch: defaultBranch.branch,
+		currentUserEmail: identity?.email || '',
+		maxEntries,
+	})
+
+	if (entries.length === 0 && more_count === 0) return null
+	return { entries, more_count }
+}
+
+/**
+ * Compose the combined catch-up panel. Returns null when neither half fires.
+ *
+ * @param {string} projectRoot
+ * @param {object} params
+ * @param {object} params.config
+ * @param {number} params.now                       epoch ms
+ * @param {object|null} params.marker               Last-Seen Marker
+ * @param {{ branch: string, sha: string }|null} params.defaultBranch
+ * @returns {{ welcome_back: object|null, team_digest: object|null }|null}
+ *
+ * @internal
+ */
+export function computeCatchUpPanel(projectRoot, { config, now, marker, defaultBranch } = {}) {
+	const sharedRoot = resolveSharedRoot(projectRoot)
+	const state = (() => {
+		const statePath = join(sharedRoot, '.aperant', 'state.json')
+		if (!existsSync(statePath)) return null
+		try {
+			return JSON.parse(readFileSync(statePath, 'utf-8'))
+		} catch {
+			return null
+		}
+	})()
+
+	const welcome_back = buildWelcomeBack({ config, now, marker, state, sharedRoot })
+	const team_digest = buildTeamDigest({ projectRoot, config, marker, defaultBranch })
+
+	if (!welcome_back && !team_digest) return null
+	// Fixed field order: welcome_back first (LD-10).
+	return { welcome_back, team_digest }
+}

package/src/cli/coordination/last-seen.mjs

@@ -0,0 +1,131 @@
+/**
+ * @internal
+ * last-seen.mjs — per-machine, per-git-identity Last-Seen Marker (LD-01).
+ *
+ * The collaboration catch-up surfaces (Welcome-Back Summary + Team-Change
+ * Digest) both diff against one baseline record per human/machine:
+ *
+ *   .aperant/last-seen/{email-slug}.json  →  { last_run_at, last_main_sha, last_active_task }
+ *
+ * The slug is derived from the git `user.email` (stable per human/machine),
+ * lowercased with every non-[a-z0-9] run collapsed to '-'. The directory is
+ * gitignored in the same per-machine ephemeral class as `team-status/` and
+ * `events/` (see upgrade-gitignore.mjs / share-policy.mjs).
+ *
+ * Modeled on team-status.mjs: resolveSharedRoot-based path so the marker lives
+ * in the main repo even when called from a worktree; atomicWriteJson +
+ * mkdirSync(recursive) for durable writes.
+ *
+ * This module is `@internal` — consumed only through the CoordinationStore
+ * seam (store.readLastSeen / store.advanceLastSeen). Do NOT import it from
+ * bin/apt-tools.mjs.
+ */
+
+import { existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { getGitIdentity } from '../git/identity.mjs'
+import { atomicWriteJson } from '../util/io.mjs'
+import { resolveSharedRoot } from './agent-identity.mjs'
+
+function lastSeenDir(projectRoot) {
+	return join(resolveSharedRoot(projectRoot), '.aperant', 'last-seen')
+}
+
+/**
+ * Slug a git email into a filesystem-safe key: lowercase, every run of
+ * non-[a-z0-9] characters collapsed to a single '-'.
+ *
+ * @param {string} email
+ * @returns {string}
+ */
+export function slugFromEmail(email) {
+	return String(email)
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, '-')
+		.replace(/^-+|-+$/g, '')
+}
+
+function markerPath(projectRoot) {
+	const identity = (() => {
+		try {
+			return getGitIdentity(projectRoot)
+		} catch {
+			return null
+		}
+	})()
+	if (!identity?.email) return null
+	const slug = slugFromEmail(identity.email)
+	if (!slug) return null
+	return join(lastSeenDir(projectRoot), `${slug}.json`)
+}
+
+/**
+ * Read the current user's Last-Seen Marker. Returns null when the git email is
+ * absent (no identity → no key) or the file does not yet exist / is malformed.
+ *
+ * @param {string} projectRoot
+ * @returns {{ last_run_at: string|null, last_main_sha: string|null, last_active_task: string|null }|null}
+ *
+ * @internal
+ */
+export function readLastSeen(projectRoot) {
+	const path = markerPath(projectRoot)
+	if (!path || !existsSync(path)) return null
+	try {
+		const record = JSON.parse(readFileSync(path, 'utf-8'))
+		if (!record || typeof record !== 'object') return null
+		return {
+			last_run_at: record.last_run_at ?? null,
+			last_main_sha: record.last_main_sha ?? null,
+			last_active_task: record.last_active_task ?? null,
+		}
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Advance the marker, merging partial fields onto any existing record.
+ *
+ * Marker-advance semantics (LD-02):
+ *   - last_run_at is always settable (it measures engagement).
+ *   - last_main_sha is optional — the caller passes it only AFTER the digest
+ *     was computed (even when empty). When undefined, the existing sha is kept.
+ *   - last_active_task is optional — the welcome-back task id, kept otherwise.
+ *
+ * No-op (returns null) when the git email is absent — there is no key to write.
+ *
+ * @param {string} projectRoot
+ * @param {{ last_run_at?: string, last_main_sha?: string|null, last_active_task?: string|null }} fields
+ * @returns {object|null} the written record, or null when there is no identity key.
+ *
+ * @internal
+ */
+export function advanceLastSeen(projectRoot, fields = {}) {
+	const path = markerPath(projectRoot)
+	if (!path) return null
+
+	let existing = {}
+	if (existsSync(path)) {
+		try {
+			existing = JSON.parse(readFileSync(path, 'utf-8')) || {}
+		} catch {
+			existing = {}
+		}
+	}
+
+	const record = {
+		last_run_at:
+			fields.last_run_at !== undefined ? fields.last_run_at : (existing.last_run_at ?? null),
+		last_main_sha:
+			fields.last_main_sha !== undefined ? fields.last_main_sha : (existing.last_main_sha ?? null),
+		last_active_task:
+			fields.last_active_task !== undefined
+				? fields.last_active_task
+				: (existing.last_active_task ?? null),
+	}
+
+	mkdirSync(lastSeenDir(projectRoot), { recursive: true })
+	atomicWriteJson(path, record)
+	return record
+}

package/src/cli/coordination/store.mjs

@@ -33,6 +33,7 @@ import { atomicWriteJson } from '../util/io.mjs'
 import { getAgentIdentity, resolveSharedRoot } from './agent-identity.mjs'
 import { appendLifecycleEvent } from './event-log.mjs'
 import { validateConductorEvent } from './event-schema.mjs'
+import { advanceLastSeen as lastSeenAdvance, readLastSeen as lastSeenRead } from './last-seen.mjs'
 import {
 	listActive as teamStatusListActive,
 	removeSelf as teamStatusRemoveSelf,
@@ -152,6 +153,23 @@ export function createCoordinationStore(projectRoot) {
 			}
 		},
 
+		/**
+		 * @internal — LD-01: read the per-machine Last-Seen Marker. Returns
+		 * null when the git email is absent or the marker has not been written.
+		 */
+		readLastSeen() {
+			return lastSeenRead(projectRoot)
+		},
+
+		/**
+		 * @internal — LD-02: advance the Last-Seen Marker. `last_run_at` is
+		 * always settable; `last_main_sha` / `last_active_task` are optional
+		 * partial fields merged onto the existing record.
+		 */
+		advanceLastSeen(fields = {}) {
+			return lastSeenAdvance(projectRoot, fields)
+		},
+
 		/** @internal */
 		getIdentity() {
 			return getAgentIdentity(projectRoot)

package/src/cli/dispatch.mjs

@@ -39,6 +39,7 @@ import { cmdAdr } from './commands/adr.mjs'
 import { cmdAudit } from './commands/audit.mjs'
 import { cmdAuthorSkill } from './commands/author-skill.mjs'
 import { cmdBootstrap } from './commands/bootstrap.mjs'
+import { cmdCatchUp } from './commands/catch-up.mjs'
 import { cmdCheck } from './commands/check.mjs'
 import { cmdCheckVersion } from './commands/check-version.mjs'
 import { cmdCiWatch, cmdCiWatchSweep } from './commands/ci-watch.mjs'
@@ -212,6 +213,7 @@ export const DISPATCH = {
 
 	// ---- (positional dir, slice(2)) shape ----
 	state: (args) => wrap(cmdState)(args[1]),
+	'catch-up': (args) => wrap(cmdCatchUp)(args[1]),
 	config: (args) => wrap(cmdConfig)(args[1], args.slice(2)),
 	'state-update': (args) => wrap(cmdStateUpdate)(args[1], args.slice(2)),
 	'state-artifacts': (args) => wrap(cmdStateArtifacts)(args[1], args.slice(2)),

package/src/cli/gate/gates/review-clean.mjs

@@ -8,7 +8,9 @@
  * shapes the reviewer skill writes: `fixed: true`, `resolved: true`,
  * `status: "fixed"` (string), and `status: "deferred-*"` variants
  * (BUG-009). Fails if any post-normalization finding is severity
- * critical|major AND status is neither `fixed` nor `deferred`.
+ * critical|major AND status is not `fixed`. `deferred` no longer clears
+ * blocking findings (G42 Phase 1 — only `--force --reason` override may
+ * bypass blocking severity deferrals).
  */
 
 import { existsSync, readFileSync } from 'node:fs'
@@ -55,7 +57,7 @@ const gate = {
 		// hole and picks up `deferred-*` variants for free.
 		const { findings: normalized } = parseReview(doc)
 		const unresolved = normalized.filter(
-			(f) => POST_NORM_BLOCKING.has(f.severity) && f.status !== 'fixed' && f.status !== 'deferred',
+			(f) => POST_NORM_BLOCKING.has(f.severity) && f.status !== 'fixed',
 		)
 		if (unresolved.length > 0) {
 			return {