@aperant/framework 0.6.2

package/src/cli/gate/cache.mjs

@@ -0,0 +1,135 @@
+/**
+ * @internal
+ * gate/cache.mjs — per-task gate result cache with input hashing (C2).
+ *
+ * Stored at .aperant/tasks/{task-id}/.gate-cache.json as:
+ *
+ *   {
+ *     "<gate_id>": {
+ *       "key":    "<sha256 of {gate_id, inputs[{path, mtime_ns, size, content_hash?}]}>",
+ *       "verdict": { status, reason, evidence?, inputs? },
+ *       "ts":     "<ISO timestamp>"
+ *     }
+ *   }
+ *
+ * Input hashing prefers (path, mtime_ns, size) for speed. When mtime is
+ * clamped to low resolution (some filesystems return only second precision,
+ * so a sub-second edit can be invisible), we fall back to a SHA-256 of the
+ * file contents via `content_hash`. The fallback fires when either:
+ *   - `APT_GATE_CACHE_CONTENT_HASH=1` is set (test-only full content mode), or
+ *   - the underlying platform reports 0 for the fs.Stats.mtimeNs field.
+ *
+ * Atomic writes via the shared atomicWriteJson helper — no partial state
+ * ever visible to a concurrent reader.
+ *
+ * Force overrides NEVER write cache entries (that contract is enforced in
+ * commands/gate.mjs, not here — this module only stores what it's asked to).
+ */
+
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { atomicWriteJson } from '../util/io.mjs'
+
+const CACHE_FILENAME = '.gate-cache.json'
+
+/**
+ * Read and return the entire cache map for a task directory. Returns an
+ * empty object when the cache file is missing or malformed (the caller
+ * treats every miss as a cache miss — no error, no throw).
+ *
+ * @internal
+ */
+export function readCache(taskDir) {
+	const path = join(taskDir, CACHE_FILENAME)
+	if (!existsSync(path)) return {}
+	try {
+		const parsed = JSON.parse(readFileSync(path, 'utf-8'))
+		return typeof parsed === 'object' && parsed !== null ? parsed : {}
+	} catch {
+		return {}
+	}
+}
+
+/**
+ * Persist a single gate verdict to the per-task cache file. Reads the
+ * existing file, splices the new entry in, and atomic-writes back.
+ *
+ * @internal
+ */
+export function writeCache(taskDir, gateId, key, verdict) {
+	const path = join(taskDir, CACHE_FILENAME)
+	const existing = readCache(taskDir)
+	existing[gateId] = {
+		key,
+		verdict,
+		ts: new Date().toISOString(),
+	}
+	atomicWriteJson(path, existing)
+}
+
+/**
+ * Drop a single gate's entry from the cache (used by explicit invalidations).
+ * Silently no-ops when the cache or the entry is missing.
+ *
+ * @internal
+ */
+export function invalidateCache(taskDir, gateId) {
+	const path = join(taskDir, CACHE_FILENAME)
+	const existing = readCache(taskDir)
+	if (!(gateId in existing)) return
+	delete existing[gateId]
+	atomicWriteJson(path, existing)
+}
+
+/**
+ * Describe an input file in a way that detects both coarse (path/size) and
+ * fine-grained (mtime or content-hash) changes. Returns null for paths that
+ * do not exist on disk (gates that read non-existent files — e.g. a missing
+ * spec.md — should still be cacheable, so we record a sentinel instead of
+ * skipping the input).
+ */
+function describeInput(path) {
+	try {
+		const st = statSync(path)
+		const descriptor = {
+			path,
+			size: st.size,
+			mtime_ns:
+				typeof st.mtimeNs === 'bigint'
+					? st.mtimeNs.toString()
+					: // Round to ns to avoid "1.71e21"-style exponent strings from floating
+						// multiplication — the stable integer form stays stable under JSON.
+						String(Math.round(st.mtimeMs * 1_000_000)),
+		}
+		const useContentHash =
+			process.env.APT_GATE_CACHE_CONTENT_HASH === '1' ||
+			descriptor.mtime_ns === '0' ||
+			descriptor.mtime_ns === 'NaN'
+		if (useContentHash) {
+			try {
+				descriptor.content_hash = createHash('sha256').update(readFileSync(path)).digest('hex')
+			} catch {
+				/* leave mtime_ns as the only signal */
+			}
+		}
+		return descriptor
+	} catch {
+		return { path, missing: true }
+	}
+}
+
+/**
+ * Compute a deterministic SHA-256 over {gate_id, inputs}. Inputs may be
+ * either already-described records `{path, size, mtime_ns, ...}` or raw
+ * path strings (gates return raw paths; we describe them here).
+ *
+ * @internal
+ */
+export function computeInputHash(gateId, inputs) {
+	const described = inputs.map((input) =>
+		typeof input === 'string' ? describeInput(input) : input,
+	)
+	const payload = JSON.stringify({ gate_id: gateId, inputs: described })
+	return createHash('sha256').update(payload).digest('hex')
+}

package/src/cli/gate/context.mjs

@@ -0,0 +1,92 @@
+/**
+ * @internal
+ * gate/context.mjs — GateContext builder (C2).
+ *
+ * Gates receive a shared, cheap-to-build context object so they don't have to
+ * re-derive paths, task records, and config. The context carries:
+ *
+ *   {
+ *     projectRoot:  string,          // absolute caller cwd (may be worktree)
+ *     sharedRoot:   string,          // main repo root via CoordinationStore
+ *     taskId:       string,
+ *     taskDir:      string,          // <sharedRoot>/.aperant/tasks/<taskId>/
+ *     taskRecord:   object | null,   // state.active_tasks[taskId] (or null)
+ *     config:       object           // .aperant/config.json (empty {} if none)
+ *   }
+ *
+ * The builder is side-effect-free — it never writes state, never mutates the
+ * task record, never touches the event log.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { createCoordinationStore } from '../coordination/store.mjs'
+
+const SAFE_TASK_ID_PATTERN = /^[a-zA-Z0-9_-]+$/
+
+function readJsonIfExists(path) {
+	if (!existsSync(path)) return null
+	try {
+		return JSON.parse(readFileSync(path, 'utf-8'))
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Build a GateContext for the given task. Throws if the task directory does
+ * not exist — callers should catch and surface the "task not found" error as
+ * a CLI-level failure envelope.
+ *
+ * @internal
+ */
+export function buildGateContext(projectRoot, taskId) {
+	if (!taskId || typeof taskId !== 'string') {
+		throw new Error('buildGateContext: taskId is required')
+	}
+	if (!SAFE_TASK_ID_PATTERN.test(taskId)) {
+		const err = new Error(`invalid task id: ${taskId}`)
+		err.code = 'ETASKINVALID'
+		throw err
+	}
+	const absRoot = resolve(projectRoot)
+	const store = createCoordinationStore(absRoot)
+	const sharedRoot = store.resolveSharedRoot()
+	const sharedTaskDir = join(sharedRoot, '.aperant', 'tasks', taskId)
+	const localTaskDir = join(absRoot, '.aperant', 'tasks', taskId)
+	const taskDir = existsSync(sharedTaskDir)
+		? sharedTaskDir
+		: sharedRoot !== absRoot && existsSync(localTaskDir)
+			? localTaskDir
+			: null
+	if (!taskDir) {
+		const err = new Error(`task not found: ${taskId}`)
+		err.code = 'ETASKNOTFOUND'
+		throw err
+	}
+
+	const state = store.readState()
+	const localState =
+		sharedRoot !== absRoot ? readJsonIfExists(join(absRoot, '.aperant', 'state.json')) : null
+	const taskRecord = state?.active_tasks?.[taskId] ?? localState?.active_tasks?.[taskId] ?? null
+
+	let config = {}
+	const configPath = join(sharedRoot, '.aperant', 'config.json')
+	config = readJsonIfExists(configPath) ?? {}
+	if (
+		sharedRoot !== absRoot &&
+		Object.keys(config).length === 0 &&
+		existsSync(join(absRoot, '.aperant', 'config.json'))
+	) {
+		config = readJsonIfExists(join(absRoot, '.aperant', 'config.json')) ?? {}
+	}
+
+	return {
+		projectRoot: absRoot,
+		sharedRoot,
+		taskId,
+		taskDir,
+		taskRecord,
+		config,
+	}
+}

package/src/cli/gate/gates/all-subtasks-complete.mjs

@@ -0,0 +1,60 @@
+/**
+ * @internal
+ * G3 all-subtasks-complete — blocking gate for `apt:verify`.
+ *
+ * Parses {task_dir}/implementation_plan.json and fails when any subtask's
+ * status is not the literal string "completed". A missing/malformed plan is
+ * also treated as a fail (the verifier cannot score what it cannot read).
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { registerGate } from '../registry.mjs'
+
+const gate = {
+	id: 'all-subtasks-complete',
+	description: 'every subtask in implementation_plan.json has status === "completed"',
+	severity: 'blocking',
+	skills: ['verify'],
+	async check(ctx) {
+		const planPath = join(ctx.taskDir, 'implementation_plan.json')
+		const inputs = [planPath]
+		if (!existsSync(planPath)) {
+			return {
+				status: 'fail',
+				reason: `implementation_plan.json missing at ${planPath}`,
+				inputs,
+			}
+		}
+		let plan
+		try {
+			plan = JSON.parse(readFileSync(planPath, 'utf-8'))
+		} catch (err) {
+			return {
+				status: 'fail',
+				reason: `implementation_plan.json does not parse: ${err.message}`,
+				inputs,
+			}
+		}
+		const subtasks = Array.isArray(plan.subtasks) ? plan.subtasks : []
+		const incomplete = subtasks.filter((s) => s?.status !== 'completed')
+		if (incomplete.length > 0) {
+			return {
+				status: 'fail',
+				reason: `${incomplete.length} subtask(s) not completed: ${incomplete
+					.map((s) => `${s.id ?? '?'}(${s.status ?? 'unknown'})`)
+					.join(', ')}`,
+				evidence: { incomplete: incomplete.map((s) => ({ id: s.id, status: s.status })) },
+				inputs,
+			}
+		}
+		return {
+			status: 'pass',
+			reason: `${subtasks.length} subtask(s) completed`,
+			inputs,
+		}
+	},
+}
+
+registerGate(gate)
+export default gate

package/src/cli/gate/gates/consistency-check.mjs

@@ -0,0 +1,60 @@
+/**
+ * @internal
+ * G8 consistency-check — blocking gate for `apt:ship` (C15).
+ *
+ * Runs the full C15 cross-artifact consistency validator at stage 'ship'.
+ * Maps the envelope to a gate verdict:
+ *   - errors === 0  -> pass  (warnings never fail ship)
+ *   - errors  >  0  -> fail
+ *
+ * `inputs` lists all five artifact paths so the C2 gate cache invalidates
+ * only when one of them actually changes.
+ */
+
+import { join } from 'node:path'
+
+import { checkConsistency } from '../../consistency/check.mjs'
+// Ensure rules self-register before checkConsistency runs.
+import '../../consistency/rules/index.mjs'
+import { registerGate } from '../registry.mjs'
+
+const gate = {
+	id: 'consistency-check',
+	description: 'Cross-artifact consistency (spec/plan/review/qa/progress) has no error drift.',
+	severity: 'blocking',
+	skills: ['ship'],
+	async check(ctx) {
+		const inputs = [
+			join(ctx.taskDir, 'spec.md'),
+			join(ctx.taskDir, 'implementation_plan.json'),
+			join(ctx.taskDir, 'review.json'),
+			join(ctx.taskDir, 'qa_signoff.json'),
+			join(ctx.taskDir, 'build-progress.json'),
+		]
+		const env = await checkConsistency({ taskDir: ctx.taskDir, stage: 'ship' })
+		if (env.errors === 0) {
+			return {
+				status: 'pass',
+				reason: `${env.rules.length} rule(s) clean (${env.warnings} warning(s))`,
+				evidence: { errors: env.errors, warnings: env.warnings },
+				inputs,
+			}
+		}
+		const failing = env.rules
+			.filter((r) => r.status === 'fail' && r.severity === 'error')
+			.map((r) => r.id)
+		return {
+			status: 'fail',
+			reason: `${env.errors} error-severity consistency drift (${failing.join(', ')})`,
+			evidence: {
+				errors: env.errors,
+				warnings: env.warnings,
+				failing_rules: failing,
+			},
+			inputs,
+		}
+	},
+}
+
+registerGate(gate)
+export default gate

package/src/cli/gate/gates/constitution-coverage.mjs

@@ -0,0 +1,67 @@
+/**
+ * @internal
+ * G7 constitution-coverage — blocking gate for `plan` + `execute` (C14).
+ *
+ * Verifies that every AGENTS.md principle is addressed in spec.md, either by
+ * keyword evidence or an explicit `- [id] N/A: <reason>` opt-out inside a
+ * dedicated `## Constitution Coverage` section.
+ *
+ * Status mapping:
+ *   - AGENTS.md missing      → skip  ("no constitution — greenfield")
+ *   - spec.md missing        → skip  ("spec.md not yet produced")
+ *   - any principle missing  → fail  (evidence lists missing ids + summary)
+ *   - otherwise              → pass
+ *
+ * Severity is `blocking` — when `plan` or `execute` fires this gate with a
+ * non-greenfield project, a missing principle halts the skill until the
+ * spec.md addresses it (or the operator runs with --force --reason per C2).
+ */
+
+import { join } from 'node:path'
+import { checkCoverage } from '../../constitution/coverage.mjs'
+import { registerGate } from '../registry.mjs'
+
+const gate = {
+	id: 'constitution-coverage',
+	description: 'Every AGENTS.md principle is covered or explicitly N/A in the task spec.md',
+	severity: 'blocking',
+	skills: ['plan', 'execute'],
+	async check(ctx) {
+		const agentsPath = join(ctx.sharedRoot, 'AGENTS.md')
+		const specPath = join(ctx.taskDir, 'spec.md')
+
+		const result = checkCoverage({ agentsPath, specPath })
+		const inputs = [agentsPath, specPath]
+
+		if (result.status === 'skip') {
+			return {
+				status: 'skip',
+				reason: result.reason,
+				inputs,
+			}
+		}
+
+		if (result.status === 'fail') {
+			const missingIds = result.principles.filter((p) => p.status === 'missing').map((p) => p.id)
+			return {
+				status: 'fail',
+				reason: result.reason,
+				evidence: {
+					summary: result.summary,
+					missing: missingIds,
+				},
+				inputs,
+			}
+		}
+
+		return {
+			status: 'pass',
+			reason: result.reason,
+			evidence: { summary: result.summary },
+			inputs,
+		}
+	},
+}
+
+registerGate(gate)
+export default gate

package/src/cli/gate/gates/constitution-read.mjs

@@ -0,0 +1,37 @@
+/**
+ * @internal
+ * G1 constitution-read — AGENTS.md exists at the project root.
+ *
+ * Severity: warn (C2 scope). Fires for execute/verify/ship. A heavier
+ * "constitution was actually referenced in recent context" check is deferred
+ * to C14.
+ */
+
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { registerGate } from '../registry.mjs'
+
+const gate = {
+	id: 'constitution-read',
+	description: 'AGENTS.md exists at the project root (lightweight C14 precursor)',
+	severity: 'warn',
+	skills: ['execute', 'verify', 'ship'],
+	async check(ctx) {
+		const path = join(ctx.sharedRoot, 'AGENTS.md')
+		if (existsSync(path)) {
+			return {
+				status: 'pass',
+				reason: 'AGENTS.md present',
+				inputs: [path],
+			}
+		}
+		return {
+			status: 'warn',
+			reason: 'AGENTS.md missing at project root',
+			inputs: [path],
+		}
+	},
+}
+
+registerGate(gate)
+export default gate

package/src/cli/gate/gates/gitignore-in-sync.mjs

@@ -0,0 +1,41 @@
+/**
+ * @internal
+ * G6 gitignore-in-sync — blocking gate for `apt:ship`.
+ *
+ * Promotes the existing C34a drift warning to a hard block at ship time:
+ * wraps checkGitignoreDrift(projectRoot) and fails when drifted === true.
+ */
+
+import { join } from 'node:path'
+import { checkGitignoreDrift } from '../../config/gitignore-drift.mjs'
+import { registerGate } from '../registry.mjs'
+
+const gate = {
+	id: 'gitignore-in-sync',
+	description: '.aperant/.gitignore matches policy-expected template',
+	severity: 'blocking',
+	skills: ['ship'],
+	async check(ctx) {
+		const inputs = [
+			join(ctx.sharedRoot, '.aperant', '.gitignore'),
+			join(ctx.sharedRoot, '.aperant', 'config.json'),
+		]
+		const result = checkGitignoreDrift(ctx.sharedRoot)
+		if (result.drifted) {
+			return {
+				status: 'fail',
+				reason: '.aperant/.gitignore has drifted from policy-expected template',
+				evidence: { reason: result.reason ?? null },
+				inputs,
+			}
+		}
+		return {
+			status: 'pass',
+			reason: '.aperant/.gitignore matches policy-expected template',
+			inputs,
+		}
+	},
+}
+
+registerGate(gate)
+export default gate

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

@@ -0,0 +1,22 @@
+/**
+ * @internal
+ * gate/gates/index.mjs — barrel that imports every built-in gate module.
+ *
+ * Each built-in gate module calls `registerGate(...)` at import time. Importing
+ * this barrel once (from commands/gate.mjs and commands/route.mjs) is therefore
+ * sufficient to populate the registry with the full C2 initial gate set.
+ *
+ * When a new built-in gate is added, append its import here and register it
+ * from its own module — do not register gates inline in this file.
+ */
+
+import './constitution-read.mjs'
+import './constitution-coverage.mjs'
+import './plan-exists.mjs'
+import './all-subtasks-complete.mjs'
+import './verify-approved.mjs'
+import './review-clean.mjs'
+import './gitignore-in-sync.mjs'
+import './consistency-check.mjs'
+import './tdd-iron-law.mjs'
+import './r-persona-alignment.mjs'

package/src/cli/gate/gates/plan-exists.mjs

@@ -0,0 +1,55 @@
+/**
+ * @internal
+ * G2 plan-exists — blocking gate for `apt:execute`.
+ *
+ * Requires {task_dir}/spec.md AND {task_dir}/implementation_plan.json to
+ * exist and the JSON to parse. Matches the exact preconditions the executor
+ * relies on in Section 1 of its skill.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { registerGate } from '../registry.mjs'
+
+const gate = {
+	id: 'plan-exists',
+	description: 'spec.md and implementation_plan.json exist and parse',
+	severity: 'blocking',
+	skills: ['execute'],
+	async check(ctx) {
+		const specPath = join(ctx.taskDir, 'spec.md')
+		const planPath = join(ctx.taskDir, 'implementation_plan.json')
+		const inputs = [specPath, planPath]
+		if (!existsSync(specPath)) {
+			return {
+				status: 'fail',
+				reason: `spec.md missing at ${specPath}`,
+				inputs,
+			}
+		}
+		if (!existsSync(planPath)) {
+			return {
+				status: 'fail',
+				reason: `implementation_plan.json missing at ${planPath}`,
+				inputs,
+			}
+		}
+		try {
+			JSON.parse(readFileSync(planPath, 'utf-8'))
+		} catch (err) {
+			return {
+				status: 'fail',
+				reason: `implementation_plan.json does not parse: ${err.message}`,
+				inputs,
+			}
+		}
+		return {
+			status: 'pass',
+			reason: 'spec.md and implementation_plan.json present and valid',
+			inputs,
+		}
+	},
+}
+
+registerGate(gate)
+export default gate