@aperant/framework 0.6.4 → 0.6.6

package/src/cli/ci-watch/stop-matrix.mjs

@@ -0,0 +1,181 @@
+/**
+ * ci-watch/stop-matrix.mjs — pure stop-matrix classifier (D-06).
+ *
+ * `classify({checks, state, prMetadata})` returns
+ *   { action, counts_toward_budget, reason }
+ *
+ * No I/O, no fs, no gh CLI shell-outs — caller pre-fetches `checks` (the
+ * payload from `gh pr checks --json name,bucket,state,conclusion,detailsUrl`)
+ * and `prMetadata` (`gh pr view --json state,reviewDecision`) and passes them
+ * in. The orchestrator in commands/ci-watch.mjs handles the side effects
+ * implied by the action.
+ *
+ * Predicate order matters — short-circuits go first (merged/closed/green/cap
+ * fire before any per-check inspection). See spec.md §9 table for the full
+ * ordering.
+ *
+ * The 11 actions:
+ *   merged, closed, green, attempts-cap, wall-cap, reviewer-pause,
+ *   identical-log, flake-skip, infra-backoff, diverged-rebased,
+ *   diverged-bailed, fix
+ *
+ * `counts_toward_budget` is `true` for fix attempts (including rebase
+ * attempts and rebase-bail); `false` for flake-skip / infra-backoff; `false`
+ * (with a sentinel meaning "n/a") for terminal actions.
+ */
+
+const ATTEMPTS_CAP = 5
+
+const INFRA_FAILURE_CLASSES = new Set(['runner-oom', 'runner-cancelled', 'gh-5xx', 'timeout'])
+
+/**
+ * @typedef {Object} CheckRow
+ * @property {string} [name]
+ * @property {string} [conclusion] e.g. 'success' | 'failure' | 'cancelled' | 'timed_out' | 'neutral'
+ * @property {string} [state]
+ * @property {string} [bucket]
+ * @property {string} [failure_class] — optional pre-classified hint (test-only seam)
+ * @property {string} [log_fingerprint] — optional digest for identical-log detection
+ *
+ * @typedef {Object} ClassifyInput
+ * @property {CheckRow[]} checks
+ * @property {Object} state — per-PR state (see state.mjs §8)
+ * @property {Object} prMetadata — { state: 'OPEN'|'CLOSED'|'MERGED', reviewDecision?: string }
+ *
+ * @typedef {Object} ClassifyOutput
+ * @property {string} action
+ * @property {boolean} counts_toward_budget
+ * @property {string} reason
+ *
+ * @param {ClassifyInput} input
+ * @returns {ClassifyOutput}
+ */
+export function classify({ checks, state, prMetadata }) {
+	const pr = prMetadata || {}
+	const st = state || {}
+	const rows = Array.isArray(checks) ? checks : []
+
+	// 1. MERGED.
+	if (pr.state === 'MERGED') {
+		return { action: 'merged', counts_toward_budget: false, reason: 'pr is merged' }
+	}
+	// 2. CLOSED (not merged).
+	if (pr.state === 'CLOSED') {
+		return { action: 'closed', counts_toward_budget: false, reason: 'pr is closed unmerged' }
+	}
+
+	const failed = rows.filter((c) => isFailing(c))
+	const allGreen = rows.length > 0 && rows.every((c) => c.conclusion === 'success')
+
+	// 3. All checks green.
+	if (allGreen) {
+		return { action: 'green', counts_toward_budget: false, reason: 'all checks succeeded' }
+	}
+
+	// 3b. No checks registered yet — CI hasn't enqueued jobs. Wait without
+	// burning a fix attempt.
+	if (rows.length === 0) {
+		return { action: 'wait', counts_toward_budget: false, reason: 'no checks registered yet' }
+	}
+
+	// 4. Attempts cap (only when red present — otherwise green/merged/closed would have fired).
+	const attempts = st.attempts || 0
+	if (attempts >= ATTEMPTS_CAP && failed.length > 0) {
+		return {
+			action: 'attempts-cap',
+			counts_toward_budget: false,
+			reason: `${attempts} fix attempts used; cap is ${ATTEMPTS_CAP}`,
+		}
+	}
+
+	// 5. Wall-clock cap.
+	if (st.deadline && Date.now() > new Date(st.deadline).getTime() && failed.length > 0) {
+		return {
+			action: 'wall-cap',
+			counts_toward_budget: false,
+			reason: 'past 4h deadline',
+		}
+	}
+
+	// 6. Reviewer asked for changes.
+	if (pr.reviewDecision === 'CHANGES_REQUESTED') {
+		return {
+			action: 'reviewer-pause',
+			counts_toward_budget: false,
+			reason: 'reviewer requested changes — pausing',
+		}
+	}
+
+	// 7. Identical-log → non-converging fixer.
+	// Compare aggregate fingerprints (same format as the write side in ci-watch.mjs).
+	if (attempts > 0 && st.last_status && failed.length > 0) {
+		const currentFingerprint = failed
+			.map((f) => `${f.name}:${f.log_fingerprint ?? ''}`)
+			.sort()
+			.join('|')
+		if (currentFingerprint === st.last_status) {
+			return {
+				action: 'identical-log',
+				counts_toward_budget: false,
+				reason: 'failed-check fingerprint identical to last attempt',
+			}
+		}
+	}
+
+	// 8. Flake-skip — same check failed then passed on rerun, no commit between.
+	// The classifier sees this as an explicit hint from the caller: failed rows
+	// classified as `bucket === 'flake'` or `failure_class === 'flake'` are the
+	// flaky-test variety and must not burn a fix attempt. Fires when EVERY
+	// remaining failure is a flake — if any non-flake failure is present, we
+	// fall through and the real failure governs.
+	if (
+		failed.length > 0 &&
+		failed.every((c) => c.bucket === 'flake' || c.failure_class === 'flake')
+	) {
+		return {
+			action: 'flake-skip',
+			counts_toward_budget: false,
+			reason: 'check transient — passed on rerun',
+		}
+	}
+
+	// 9. Infra failure class.
+	if (failed.some((c) => INFRA_FAILURE_CLASSES.has(c.failure_class))) {
+		return {
+			action: 'infra-backoff',
+			counts_toward_budget: false,
+			reason: 'infra-class failure — backoff and retry',
+		}
+	}
+
+	// 10. Diverged branch — caller has already done the fetch + dry-rebase and
+	// passes the outcome in `prMetadata.diverged`:
+	//   { rebased: true }   → action 'diverged-rebased' (counts)
+	//   { rebased: false }  → action 'diverged-bailed'  (counts)
+	if (pr.diverged && typeof pr.diverged === 'object') {
+		if (pr.diverged.rebased === true) {
+			return {
+				action: 'diverged-rebased',
+				counts_toward_budget: true,
+				reason: 'origin ahead; rebased successfully',
+			}
+		}
+		return {
+			action: 'diverged-bailed',
+			counts_toward_budget: true,
+			reason: 'origin ahead; rebase conflict',
+		}
+	}
+
+	// 11. Default red — go fix.
+	return {
+		action: 'fix',
+		counts_toward_budget: true,
+		reason: 'red checks present — attempting fix',
+	}
+}
+
+export function isFailing(check) {
+	const c = check.conclusion
+	return c === 'failure' || c === 'cancelled' || c === 'timed_out' || c === 'action_required'
+}

package/src/cli/cli-wrappers/ci-watch.mjs

@@ -0,0 +1,9 @@
+/**
+ * cli-wrappers/ci-watch.mjs — Layer 2 wrapper for the ci-watch cmd.
+ *
+ * Today this is a passthrough — DISPATCH calls wrap(cmdCiWatch) directly.
+ * Re-exporting under cliCiWatch keeps the file-per-cmd structural seam
+ * (mirrors task.mjs / pr-review.mjs).
+ */
+
+export { cmdCiWatch as cliCiWatch } from '../commands/ci-watch.mjs'

package/src/cli/commands/adr.mjs

@@ -0,0 +1,243 @@
+/**
+ * commands/adr.mjs — `apt-tools adr write` (Pocock adoption ST-6, AC5).
+ *
+ * Writes an ADR under `docs/adr/NNNN-slug.md` ONLY when all three Nygard
+ * gates pass: hard-to-reverse AND surprising-without-context AND
+ * real-trade-off. When any gate fails, the writer returns a `filtered`
+ * envelope and writes nothing — the decision stays in
+ * `.aperant/context/notes/{task-id}.md` instead.
+ *
+ * CLI:
+ *   apt-tools adr write <project-dir>
+ *     --title <slug>
+ *     --hard-to-reverse <true|false>
+ *     --surprising-without-context <true|false>
+ *     --real-trade-off <true|false>
+ *     --decision <text>
+ *     --consequences <text>
+ *     [--context <text>]
+ *     [--status Proposed|Accepted|Deprecated|Superseded]
+ *
+ * Output: JSON envelope.
+ *   On filter:  { status: 'filtered', failed_gates: string[], reason: 'three-gate-filter' }
+ *   On write:   { status: 'ok', command: 'adr-write', file: <abs path>, number: N, slug: '...' }
+ */
+
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { parseFlags } from '../util/args.mjs'
+import { err, exitWith, ok } from '../util/result.mjs'
+
+/**
+ * Parse a flag value as a strict boolean. Returns null on unrecognized form
+ * so callers can distinguish "missing" from "false".
+ *
+ * @param {unknown} v
+ * @returns {boolean|null}
+ */
+function parseBool(v) {
+	if (v === true) return true
+	if (typeof v !== 'string') return null
+	const low = v.toLowerCase()
+	if (low === 'true' || low === 'yes' || low === '1') return true
+	if (low === 'false' || low === 'no' || low === '0') return false
+	return null
+}
+
+/**
+ * Slugify a title for the filename (NNNN-slug.md).
+ *
+ * @param {string} title
+ */
+function slugify(title) {
+	return title
+		.toLowerCase()
+		.trim()
+		.replace(/[^\w\s-]/g, '')
+		.replace(/\s+/g, '-')
+		.replace(/-+/g, '-')
+		.replace(/^-|-$/g, '')
+}
+
+/**
+ * Find the next ADR sequence number by scanning `docs/adr/`.
+ *
+ * @param {string} adrDir
+ * @returns {number}
+ */
+function nextAdrNumber(adrDir) {
+	if (!existsSync(adrDir)) return 1
+	const entries = readdirSync(adrDir)
+	let max = 0
+	for (const name of entries) {
+		const m = name.match(/^(\d{4})-/)
+		if (!m) continue
+		const n = Number.parseInt(m[1], 10)
+		if (n > max) max = n
+	}
+	return max + 1
+}
+
+/**
+ * Render the ADR markdown body.
+ *
+ * @param {{
+ *   number: number,
+ *   title: string,
+ *   status: string,
+ *   date: string,
+ *   context: string,
+ *   decision: string,
+ *   consequences: string,
+ *   hardToReverse: boolean,
+ *   surprisingWithoutContext: boolean,
+ *   realTradeOff: boolean,
+ * }} opts
+ */
+function renderAdr(opts) {
+	const paddedNumber = String(opts.number).padStart(4, '0')
+	return [
+		`# ADR-${paddedNumber}: ${opts.title}`,
+		'',
+		`**Status:** ${opts.status}`,
+		`**Date:** ${opts.date}`,
+		'',
+		'## Context',
+		'',
+		opts.context,
+		'',
+		'## Decision',
+		'',
+		opts.decision,
+		'',
+		'## Consequences',
+		'',
+		opts.consequences,
+		'',
+		'---',
+		'',
+		'## Nygard 3-gate filter (audit trail)',
+		'',
+		'This ADR was written via `apt-tools adr write` and passed all three of',
+		"Nygard's filter gates. Reversible / obvious / trade-off-free decisions",
+		'stay in `.aperant/context/notes/{task-id}.md` and do NOT become ADRs.',
+		'',
+		`- **Hard to reverse:** ${opts.hardToReverse}`,
+		`- **Surprising without context:** ${opts.surprisingWithoutContext}`,
+		`- **Real trade-off:** ${opts.realTradeOff}`,
+		'',
+	].join('\n')
+}
+
+/**
+ * CLI entry: `apt-tools adr <subcommand> <project-dir> [flags]`.
+ */
+export function cmdAdr(subcommand, projectDir, extraArgs) {
+	if (subcommand !== 'write') {
+		return err(
+			'Usage: apt-tools adr write <project-dir> --title <slug> --hard-to-reverse <bool> --surprising-without-context <bool> --real-trade-off <bool> --decision <text> --consequences <text> [--context <text>] [--status <status>]',
+			1,
+			{ command: 'adr' },
+		)
+	}
+	if (!projectDir) {
+		return err('project-dir is required', 1, { command: 'adr-write' })
+	}
+
+	const flags = parseFlags(extraArgs ?? [])
+	const title = flags.get('title')
+	if (typeof title !== 'string' || title.trim() === '') {
+		return err('--title <slug> is required', 1, { command: 'adr-write' })
+	}
+
+	// Three Nygard gates — every one must be parseable; missing means "not
+	// asked", which is the same as "no" for the filter.
+	const hardToReverse = parseBool(flags.get('hard-to-reverse'))
+	const surprisingWithoutContext = parseBool(flags.get('surprising-without-context'))
+	const realTradeOff = parseBool(flags.get('real-trade-off'))
+
+	for (const [name, value] of [
+		['--hard-to-reverse', hardToReverse],
+		['--surprising-without-context', surprisingWithoutContext],
+		['--real-trade-off', realTradeOff],
+	]) {
+		if (value === null) {
+			return err(`${name} <true|false> is required`, 1, { command: 'adr-write' })
+		}
+	}
+
+	const decision = flags.get('decision')
+	const consequences = flags.get('consequences')
+	if (typeof decision !== 'string' || decision.trim() === '') {
+		return err('--decision <text> is required', 1, { command: 'adr-write' })
+	}
+	if (typeof consequences !== 'string' || consequences.trim() === '') {
+		return err('--consequences <text> is required', 1, { command: 'adr-write' })
+	}
+
+	// Three-gate filter — every gate must be true to write.
+	const failed = []
+	if (!hardToReverse) failed.push('hard-to-reverse')
+	if (!surprisingWithoutContext) failed.push('surprising-without-context')
+	if (!realTradeOff) failed.push('real-trade-off')
+
+	if (failed.length > 0) {
+		return exitWith(
+			{
+				status: 'filtered',
+				command: 'adr-write',
+				reason: 'three-gate-filter',
+				failed_gates: failed,
+				note: 'Decision stays in .aperant/context/notes/{task-id}.md. ADRs are reserved for hard-to-reverse, surprising, real-trade-off decisions.',
+			},
+			0,
+		)
+	}
+
+	// All three gates passed — write the ADR.
+	const absProjectDir = resolve(projectDir)
+	if (!existsSync(absProjectDir)) {
+		return err(`project directory not found: ${absProjectDir}`, 1, { command: 'adr-write' })
+	}
+
+	const adrDir = join(absProjectDir, 'docs', 'adr')
+	if (!existsSync(adrDir)) {
+		mkdirSync(adrDir, { recursive: true })
+	}
+	const number = nextAdrNumber(adrDir)
+	const slug = slugify(title)
+	const paddedNumber = String(number).padStart(4, '0')
+	const filename = `${paddedNumber}-${slug}.md`
+	const filePath = join(adrDir, filename)
+
+	const status = (typeof flags.get('status') === 'string' && flags.get('status')) || 'Proposed'
+	const context =
+		(typeof flags.get('context') === 'string' && flags.get('context')) ||
+		'{Context not supplied — provide via --context on a re-run.}'
+	const date = new Date().toISOString().slice(0, 10)
+
+	const body = renderAdr({
+		number,
+		title,
+		status: String(status),
+		date,
+		context: String(context),
+		decision,
+		consequences,
+		hardToReverse: true,
+		surprisingWithoutContext: true,
+		realTradeOff: true,
+	})
+
+	writeFileSync(filePath, body)
+
+	return ok({
+		status: 'ok',
+		command: 'adr-write',
+		file: filePath,
+		number,
+		slug,
+		title,
+		passed_gates: ['hard-to-reverse', 'surprising-without-context', 'real-trade-off'],
+	})
+}