@aperant/framework 0.13.0-next.0 → 0.15.0

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

@@ -71,13 +71,15 @@ export function buildAperantGitignoreTemplate(policy = DEFAULT_SHARE_POLICY) {
 		'#     framework scaffolding that ships with the repo. Runtime workflow run',
 		'#     files (workflows/*.json + workflows/archive/) are ephemeral.',
 		'#   shared-source (committed iff matching share.* toggle is on):',
-		'#     team.json, roadmap/**, decisions/*.md, digests/*.md, tasks/*/** —',
-		'#     the allow rules below are emitted only when the policy opts in.',
+		'#     team.json, roadmap/**, decisions/*.md, digests/*.md, tasks/*/**,',
+		'#     quick/*/** (quick shares the tasks toggle) — the allow rules below',
+		'#     are emitted only when the policy opts in.',
 		'#   ephemeral/coordination (always ignored): state.json, active.json (legacy, removed in C34 — rule kept as defense in depth), events/,',
 		'#     locks/, team-status/, paused/, pending-effects.jsonl — per-machine',
 		'#     lifecycle data; committing leaks PIDs + hostnames.',
-		'#   derived/regenerated (always ignored): tasks/INDEX.md, roadmap/**/ROADMAP.md,',
-		'#     decisions/INDEX.md — humans read the Markdown, machines write the JSON.',
+		'#   derived/regenerated (always ignored): tasks/INDEX.md, quick/INDEX.md,',
+		'#     roadmap/**/ROADMAP.md, decisions/INDEX.md — humans read the Markdown,',
+		'#     machines write the JSON.',
 		'',
 		'# Ignore everything by default',
 		'*',
@@ -139,6 +141,15 @@ export function buildAperantGitignoreTemplate(policy = DEFAULT_SHARE_POLICY) {
 		lines.push('!tasks/*/ # class: shared-source')
 		lines.push('!tasks/*/** # class: shared-source')
 		lines.push('')
+		// QUICK-task records share the tasks toggle (quick is a task track).
+		// Same shape as tasks/: per-record dirs allowed, derived INDEX denied.
+		lines.push('# Quick-task records (the per-task directory content, not the INDEX)')
+		lines.push('!quick/')
+		lines.push('quick/*')
+		lines.push('# Re-allow per-quick-task directories; INDEX.md is derived and stays ignored.')
+		lines.push('!quick/*/ # class: shared-source')
+		lines.push('!quick/*/** # class: shared-source')
+		lines.push('')
 	}
 
 	// ── Shared-source: roadmap (share.roadmap) ──────────────────────────────
@@ -193,6 +204,10 @@ export function buildAperantGitignoreTemplate(policy = DEFAULT_SHARE_POLICY) {
 	lines.push('')
 	lines.push('# ── Derived markdown indexes (regenerated from JSON) ──────────────')
 	lines.push('tasks/INDEX.md')
+	// quick/INDEX.md is the QUICK-task analogue of tasks/INDEX.md — a derived
+	// markdown index regenerated from the per-task records. Always denied,
+	// regardless of share.tasks, so it never lingers as a tracked dirty file.
+	lines.push('quick/INDEX.md')
 	lines.push('')
 
 	return lines.join('\n')
@@ -298,7 +313,14 @@ function loadPolicyFromConfig(aperantDir) {
 }
 
 function findTrackedFilesThatWillBeIgnored(projectRoot) {
-	const candidates = ['.aperant/state.json', '.aperant/active.json', '.aperant/tasks/INDEX.md']
+	const candidates = [
+		'.aperant/state.json',
+		'.aperant/active.json',
+		'.aperant/tasks/INDEX.md',
+		// Derived QUICK index — always ignored now; surface the historical
+		// orphan (committed before quick/ entered the taxonomy) for untracking.
+		'.aperant/quick/INDEX.md',
+	]
 	// roadmap/**/ROADMAP.md — enumerate via git ls-files below.
 	const tracked = new Set()
 	try {

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

@@ -48,7 +48,7 @@ export function parseQaSignoff(qa) {
 		findings.push({
 			severity: sev,
 			title: typeof f.title === 'string' ? f.title : typeof f.message === 'string' ? f.message : '',
-			status: typeof f.status === 'string' ? f.status.toLowerCase() : 'open',
+			status: normalizeFindingStatus(f),
 			file: typeof f.file === 'string' ? f.file : typeof f.path === 'string' ? f.path : '',
 		})
 	}
@@ -100,3 +100,13 @@ function normalizeSeverity(sev) {
 	const key = sev.toLowerCase().trim()
 	return SEVERITY_MAP[key] ?? null
 }
+
+// Mirror parse-review's `normalizeStatus` shorthand: a finding marked with the
+// `fixed: true` / `resolved: true` boolean (no string `status`) is `fixed`.
+// Without this, derive.mjs would treat such a finding as a still-open candidate
+// and the ledger would have to cover a phantom expected row.
+function normalizeFindingStatus(f) {
+	if (f.fixed === true) return 'fixed'
+	if (f.resolved === true) return 'fixed'
+	return typeof f.status === 'string' ? f.status.toLowerCase() : 'open'
+}

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

@@ -61,6 +61,42 @@ export function parseReview(review) {
 	return { findings }
 }
 
+/**
+ * Like {@link parseReview} but RETAINS the sub-critical findings that
+ * `DROPPED_SEVERITIES` discards (suggestion/nitpick/note/info/minor). The
+ * severity is the raw lowercased string (no SEVERITY_MAP collapse), so a
+ * `warning` stays `warning` and a `minor` stays `minor`. Status uses the
+ * identical `normalizeStatus` rules as parseReview (`fixed:true`,
+ * `resolved:true`, `deferred-*` collapse). The id-synthesis (`rf-<i>`) and
+ * `{id, severity, status, title, file}` shape match parseReview.
+ *
+ * Additive export — parseReview's output is byte-stable.
+ *
+ * @param {object | null | undefined} review
+ * @returns {{findings: Array<{id: string, severity: string, status: string, title: string, file: string}>}}
+ */
+export function parseReviewRaw(review) {
+	if (!review || typeof review !== 'object') {
+		return { findings: [] }
+	}
+
+	const raw = collectRaw(review)
+	const findings = []
+	for (let i = 0; i < raw.length; i++) {
+		const f = raw[i]
+		if (!f || typeof f !== 'object') continue
+		if (typeof f.severity !== 'string') continue
+		findings.push({
+			id: typeof f.id === 'string' ? f.id : typeof f.id === 'number' ? String(f.id) : `rf-${i + 1}`,
+			severity: f.severity.toLowerCase().trim(),
+			status: normalizeStatus(f),
+			title: typeof f.title === 'string' ? f.title : typeof f.message === 'string' ? f.message : '',
+			file: typeof f.file === 'string' ? f.file : typeof f.path === 'string' ? f.path : '',
+		})
+	}
+	return { findings }
+}
+
 function collectRaw(review) {
 	const out = []
 	const findings = review.findings

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

@@ -43,6 +43,49 @@ export function parseSpec(md) {
 	return { acs, dimensions_claimed }
 }
 
+/**
+ * Extract `## Out of Scope` bullets from a spec.md string.
+ *
+ * Heading match is case-insensitive at any level >= 2. Bullets may be
+ * `-`/`*`/numbered; the section body ends at the next heading of
+ * equal-or-shallower depth. Returns `[]` on absent section or non-string
+ * input. Does NOT touch the filesystem (additive sibling to parseSpec — the
+ * existing parseSpec return shape is unchanged).
+ *
+ * @param {string | null | undefined} md
+ * @returns {Array<{text: string, line: number}>}
+ */
+export function parseOutOfScope(md) {
+	if (typeof md !== 'string' || md.length === 0) return []
+
+	const lines = md.split(/\r?\n/)
+	let headingIdx = -1
+	let headingLevel = 0
+	for (let i = 0; i < lines.length; i++) {
+		const m = lines[i].match(/^(#{2,})\s*out\s+of\s+scope\s*$/i)
+		if (m) {
+			headingIdx = i
+			headingLevel = m[1].length
+			break
+		}
+	}
+	if (headingIdx === -1) return []
+
+	const out = []
+	for (let i = headingIdx + 1; i < lines.length; i++) {
+		const line = lines[i]
+		const h = line.match(/^(#{1,6})\s+/)
+		if (h && h[1].length <= headingLevel) break
+
+		const bulletMatch = line.match(/^\s*(?:[-*]|\d+\.)\s+(.*)$/)
+		if (!bulletMatch) continue
+		const text = bulletMatch[1].trim()
+		if (text.length === 0) continue
+		out.push({ text, line: i + 1 })
+	}
+	return out
+}
+
 function collectAcs(lines) {
 	// Find the first "## Acceptance Criteria" heading (level >= 2).
 	let headingIdx = -1

package/src/cli/coordination/agent-identity.mjs

@@ -18,20 +18,22 @@
 import { existsSync, mkdirSync, readFileSync } from 'node:fs'
 import { hostname as osHostname } from 'node:os'
 import { join } from 'node:path'
-import { detectWorktree } from '../git/worktree-detect.mjs'
 import { withFileLock } from '../util/fs-lock.mjs'
 import { atomicWriteJson } from '../util/io.mjs'
+import { resolveMainRepoRoot } from '../util/state-paths.mjs'
 
 // Cached identity per project root (rooted at the shared .aperant/ dir).
 const cache = new Map()
 
 /**
  * Resolve the shared coordination root — always the main repo's root, even
- * when called from a worktree. Mirrors commands/event.mjs.
+ * when called from a worktree. Body re-pointed at the shared resolveMainRepoRoot
+ * mechanism (state-fork-fix ID-07) to inherit the null-guard; the name and the
+ * @internal CoordinationStore seam ownership stay as-is (it is NOT merged with
+ * resolveStateDir — it is a SEPARATE policy wrapper over the same mechanism).
  */
 export function resolveSharedRoot(projectDir) {
-	const wt = detectWorktree(projectDir)
-	return wt.is_worktree && wt.main_repo_root ? wt.main_repo_root : projectDir
+	return resolveMainRepoRoot(projectDir)
 }
 
 /**

package/src/cli/dispatch.mjs

@@ -63,6 +63,7 @@ import { cmdEffects } from './commands/effects.mjs'
 import { cmdEvent } from './commands/event.mjs'
 import { cmdFanOut } from './commands/fan-out.mjs'
 import { cmdFeaturesAudit } from './commands/features-audit.mjs'
+import { cmdFollowups } from './commands/followups.mjs'
 import { cmdGate } from './commands/gate.mjs'
 import { cmdHealthCheck } from './commands/health-check.mjs'
 import { cmdHostDetect, cmdReconcile } from './commands/host-detect.mjs'
@@ -70,6 +71,7 @@ import { cmdInit } from './commands/init.mjs'
 import { cmdInitState } from './commands/init-state.mjs'
 import { cmdInstallFromSource } from './commands/install-from-source.mjs'
 import { cmdLock } from './commands/lock.mjs'
+import { cmdMerge } from './commands/merge-detect.mjs'
 import { cmdMigratePrReviews } from './commands/migrate-pr-reviews.mjs'
 import { cmdMobilePrepare } from './commands/mobile-prepare.mjs'
 import { cmdPersonas } from './commands/personas.mjs'
@@ -317,6 +319,7 @@ export const DISPATCH = {
 	'variant-pick': (args) => wrap(cmdVariantPick)(args[1], args[2], args.slice(3)),
 	worktree: (args) => wrap(cmdWorktree)(args[1], args[2], args.slice(3)),
 	audit: (args) => wrap(cmdAudit)(args[1], args[2], args.slice(3)),
+	merge: (args) => wrap(cmdMerge)(args[1], args[2], args.slice(3)),
 	'release-notes': (args) => wrap(cmdReleaseNotes)(args[1], args[2], args.slice(3)),
 	team: (args) => wrap(cmdTeam)(args[1], args[2], args.slice(3)),
 	active: (args) => wrap(cmdActive)(args[1], args[2], args.slice(3)),
@@ -336,6 +339,7 @@ export const DISPATCH = {
 	context: (args) => wrap(cmdContext)(args[1], args[2], args.slice(3)),
 	adr: (args) => wrap(cmdAdr)(args[1], args[2], args.slice(3)),
 	triage: (args) => wrap(cmdTriage)(args[1], args[2], args.slice(3)),
+	followups: (args) => wrap(cmdFollowups)(args[1], args[2], args.slice(3)),
 	modes: async (args) => {
 		const { cmdModes } = await import('./commands/modes.mjs')
 		return wrap(cmdModes)(args[1], args[2], args.slice(3))

package/src/cli/followups/derive.mjs

@@ -0,0 +1,123 @@
+/**
+ * @internal
+ * followups/derive.mjs — deterministic expected-candidate derivation (G45, ID-04).
+ *
+ * Pure: takes already-parsed inputs (no fs), returns the expected row
+ * universe + outcome-ref validation. The expected universe is what makes the
+ * ledger DERIVED, not voluntary — a writer cannot self-certify completeness.
+ *
+ * Expected universe =
+ *     parseOutOfScope(spec.md) bullets                      → origin 'plan',   id `oos-<n>`
+ *   ∪ parseReviewRaw(review.json) rows status !== 'fixed'   → origin 'review', id `rev-<finding.id>`
+ *   ∪ parseQaSignoff(qa_signoff.json) findings status!=='fixed' → origin 'verify', id `qa-<n>`
+ *
+ * Each candidate carries a full payload `{id, title, origin, class_hint}` so
+ * the adjudicating agent appends ledger rows mechanically. `class_hint` is a
+ * non-authoritative suggestion (ID-03): plan/verify default to 'new-task',
+ * review findings default to 'in-pr'.
+ */
+
+import { parseQaSignoff } from '../consistency/parse-qa.mjs'
+import { parseReviewRaw } from '../consistency/parse-review.mjs'
+import { parseOutOfScope } from '../consistency/parse-spec.mjs'
+
+/**
+ * @param {{specContent?: string, review?: object, qa?: object}} inputs
+ * @returns {Array<{id: string, title: string, origin: string, class_hint: string}>}
+ */
+export function deriveExpectedCandidates({ specContent, review, qa } = {}) {
+	/** @type {Array<{id: string, title: string, origin: string, class_hint: string}>} */
+	const candidates = []
+
+	// (1) Out of Scope bullets — origin plan, 1-based ordinal id.
+	const oos = parseOutOfScope(specContent)
+	for (let i = 0; i < oos.length; i++) {
+		candidates.push({
+			id: `oos-${i + 1}`,
+			title: oos[i].text,
+			origin: 'plan',
+			class_hint: 'new-task',
+		})
+	}
+
+	// (2) Review raw rows that are not fixed — origin review, id rev-<finding.id>.
+	const rawReview = parseReviewRaw(review)
+	for (const f of rawReview.findings) {
+		if (f.status === 'fixed') continue
+		candidates.push({
+			id: `rev-${f.id}`,
+			title: f.title || f.id,
+			origin: 'review',
+			class_hint: 'in-pr',
+		})
+	}
+
+	// (3) QA sign-off findings that are not fixed — origin verify, 1-based
+	// ordinal by ABSOLUTE position in the findings list. The id MUST be stable
+	// as findings get fixed over the task's life: a counter over the filtered
+	// (non-fixed) subset would renumber qa-2 → qa-1 once an earlier finding
+	// flips to fixed, so an already-adjudicated ledger row (id qa-2) would
+	// resurface as a "missing expected" candidate — the exact evaporation this
+	// gate exists to prevent. Position-based ids match the oos path (absolute
+	// index) and the rev path (stable finding id).
+	const qaParsed = parseQaSignoff(qa)
+	for (let i = 0; i < qaParsed.findings.length; i++) {
+		const f = qaParsed.findings[i]
+		if (f.status === 'fixed') continue
+		candidates.push({
+			id: `qa-${i + 1}`,
+			title: f.title || `qa finding ${i + 1}`,
+			origin: 'verify',
+			class_hint: 'new-task',
+		})
+	}
+
+	return candidates
+}
+
+/**
+ * Validate every `outcome_refs[]` entry + `adjudication.outcome_ref` on the
+ * ledger rows against the set of `O<n>` ids from parseUserOutcomes. Unknown
+ * refs are returned for `invalid_outcome_refs[]` (never a new id namespace,
+ * ID-01). A null/omitted `adjudication.outcome_ref` is valid (refactor-only
+ * specs have no outcomes).
+ *
+ * @param {Array<{id: string, outcome_refs?: string[], adjudication?: {outcome_ref?: string|null}}>} rows  — validated ledger rows (only id / outcome_refs / adjudication.outcome_ref are read)
+ * @param {{outcomes?: Array<{id: string}>}} parsedOutcomes  — parseUserOutcomes(spec.md)
+ * @returns {Array<{row_id: string, ref: string, field: string}>}
+ */
+export function validateOutcomeRefs(rows, parsedOutcomes) {
+	const valid = new Set(
+		(parsedOutcomes && Array.isArray(parsedOutcomes.outcomes) ? parsedOutcomes.outcomes : []).map(
+			(o) => o.id,
+		),
+	)
+	/** @type {Array<{row_id: string, ref: string, field: string}>} */
+	const invalid = []
+	const list = Array.isArray(rows) ? rows : []
+	for (const r of list) {
+		const refs = Array.isArray(r.outcome_refs) ? r.outcome_refs : []
+		for (const ref of refs) {
+			if (!valid.has(ref)) invalid.push({ row_id: r.id, ref, field: 'outcome_refs' })
+		}
+		const adjRef = r.adjudication?.outcome_ref
+		if (typeof adjRef === 'string' && adjRef.length > 0 && !valid.has(adjRef)) {
+			invalid.push({ row_id: r.id, ref: adjRef, field: 'adjudication.outcome_ref' })
+		}
+	}
+	return invalid
+}
+
+/**
+ * Compute the set of expected candidate ids missing from the ledger rows.
+ * Returns the full candidate payloads for each missing id (so the agent can
+ * append them mechanically — ID-04).
+ *
+ * @param {Array<{id: string, title: string, origin: string, class_hint: string}>} candidates
+ * @param {Array<{id: string}>} rows  — only the `id` is read
+ * @returns {Array<{id: string, title: string, origin: string, class_hint: string}>}
+ */
+export function computeMissingExpected(candidates, rows) {
+	const present = new Set((Array.isArray(rows) ? rows : []).map((r) => r.id))
+	return (Array.isArray(candidates) ? candidates : []).filter((c) => !present.has(c.id))
+}

package/src/cli/followups/schema.mjs

@@ -0,0 +1,264 @@
+/**
+ * @internal
+ * followups/schema.mjs — validate the per-task followups.json ledger (G45).
+ *
+ * Pure: takes a parsed JSON document, returns a normalized shape with
+ * structured `schema_errors[]`. Never throws, never touches the filesystem
+ * (mirrors the consistency-parser style).
+ *
+ * Row shape:
+ *   {
+ *     id: string,                                  // free id (e.g. oos-1, rev-rf-3, qa-2, or a voluntary id)
+ *     title: string,
+ *     class_proposed: 'in-pr' | 'new-task' | 'polish',   // a PROPOSAL — adjudication is authority (ID-03)
+ *     origin: 'plan' | 'discuss' | 'execute' | 'verify' | 'review' | 'ci',
+ *     files: string[],
+ *     outcome_refs: string[],                      // 'O<n>' ids validated elsewhere (derive.validateOutcomeRefs)
+ *     status: 'open' | 'fixed' | 'dispositioned',
+ *     adjudication?: {
+ *       verdict: 'load-bearing' | 'deferrable',
+ *       by: 'verify' | 'verify-proof',
+ *       outcome_ref?: string | null               // nullable — refactor-only specs have no outcomes (ID-01)
+ *     },
+ *     disposition?: {
+ *       kind: 'filed_task' | 'executed_commit' | 'parked_note' | 'dropped_by_user',
+ *       ref: string,
+ *       reason?: string                            // required for dropped_by_user (enforced at the CLI seam)
+ *     }
+ *   }
+ *
+ * Output:
+ *   { rows: ValidRow[], schema_errors: [{row_index, id?, field, message}] }
+ *
+ * A row that fails validation is reported in schema_errors and EXCLUDED from
+ * rows[] (so downstream gate logic never reasons over a malformed row).
+ */
+
+export const CLASS_PROPOSED = new Set(['in-pr', 'new-task', 'polish'])
+export const ORIGINS = new Set(['plan', 'discuss', 'execute', 'verify', 'review', 'ci'])
+export const STATUSES = new Set(['open', 'fixed', 'dispositioned'])
+export const VERDICTS = new Set(['load-bearing', 'deferrable'])
+export const ADJUDICATORS = new Set(['verify', 'verify-proof'])
+export const DISPOSITION_KINDS = new Set([
+	'filed_task',
+	'executed_commit',
+	'parked_note',
+	'dropped_by_user',
+])
+
+/**
+ * @typedef {Object} FollowupAdjudication
+ * @property {'load-bearing'|'deferrable'} verdict
+ * @property {'verify'|'verify-proof'} by
+ * @property {string|null} [outcome_ref]
+ *
+ * @typedef {Object} FollowupDisposition
+ * @property {'filed_task'|'executed_commit'|'parked_note'|'dropped_by_user'} kind
+ * @property {string} ref
+ * @property {string} [reason]
+ *
+ * @typedef {Object} FollowupRow
+ * @property {string} id
+ * @property {string} title
+ * @property {'in-pr'|'new-task'|'polish'} class_proposed
+ * @property {'plan'|'discuss'|'execute'|'verify'|'review'|'ci'} origin
+ * @property {string[]} files
+ * @property {string[]} outcome_refs
+ * @property {'open'|'fixed'|'dispositioned'} status
+ * @property {FollowupAdjudication} [adjudication]
+ * @property {FollowupDisposition} [disposition]
+ *
+ * @typedef {Object} ParsedFollowups
+ * @property {FollowupRow[]} rows
+ * @property {Array<{row_index: number, id?: string, field: string, message: string}>} schema_errors
+ *
+ * The selector helpers below read only `status` / `adjudication` /
+ * `disposition`, so they accept a structural row shape (any caller-built row
+ * with those fields fits) and return the same element type they were given.
+ * @typedef {{status?: string, adjudication?: {verdict?: string}, disposition?: {kind?: string, ref?: string}}} SelectorRow
+ */
+
+/**
+ * @param {unknown} doc  — a parsed followups.json document. Accepts either
+ *   `{ rows: [...] }` or a bare `[...]` array of rows.
+ * @returns {ParsedFollowups}
+ */
+export function parseFollowups(doc) {
+	/** @type {Array<{row_index: number, id?: string, field: string, message: string}>} */
+	const schema_errors = []
+	/** @type {Array<object>} */
+	const rows = []
+
+	const rawRows = extractRows(doc)
+	if (rawRows === null) {
+		schema_errors.push({
+			row_index: -1,
+			field: 'rows',
+			message: 'followups.json must be an array of rows or an object with a `rows` array',
+		})
+		return { rows, schema_errors }
+	}
+
+	for (let i = 0; i < rawRows.length; i++) {
+		const r = rawRows[i]
+		const errsBefore = schema_errors.length
+		if (!r || typeof r !== 'object' || Array.isArray(r)) {
+			schema_errors.push({ row_index: i, field: 'row', message: 'row must be an object' })
+			continue
+		}
+		const id = typeof r.id === 'string' && r.id.trim().length > 0 ? r.id : undefined
+		const push = (field, message) => schema_errors.push({ row_index: i, id, field, message })
+
+		if (!id) push('id', 'missing or empty `id`')
+		if (typeof r.title !== 'string' || r.title.trim().length === 0)
+			push('title', 'missing or empty `title`')
+		if (!CLASS_PROPOSED.has(r.class_proposed))
+			push('class_proposed', `must be one of: ${[...CLASS_PROPOSED].join(', ')}`)
+		if (!ORIGINS.has(r.origin)) push('origin', `must be one of: ${[...ORIGINS].join(', ')}`)
+		if (!STATUSES.has(r.status)) push('status', `must be one of: ${[...STATUSES].join(', ')}`)
+		if (r.files !== undefined && !isStringArray(r.files)) push('files', 'must be a string array')
+		if (r.outcome_refs !== undefined && !isStringArray(r.outcome_refs))
+			push('outcome_refs', 'must be a string array of O<n> ids')
+
+		if (r.adjudication !== undefined) {
+			const a = r.adjudication
+			if (!a || typeof a !== 'object' || Array.isArray(a)) {
+				push('adjudication', 'must be an object when present')
+			} else {
+				if (!VERDICTS.has(a.verdict))
+					push('adjudication.verdict', `must be one of: ${[...VERDICTS].join(', ')}`)
+				if (!ADJUDICATORS.has(a.by))
+					push('adjudication.by', `must be one of: ${[...ADJUDICATORS].join(', ')}`)
+				if (
+					a.outcome_ref !== undefined &&
+					a.outcome_ref !== null &&
+					typeof a.outcome_ref !== 'string'
+				)
+					push('adjudication.outcome_ref', 'must be a string, null, or omitted')
+			}
+		}
+
+		if (r.disposition !== undefined) {
+			const d = r.disposition
+			if (!d || typeof d !== 'object' || Array.isArray(d)) {
+				push('disposition', 'must be an object when present')
+			} else {
+				if (!DISPOSITION_KINDS.has(d.kind))
+					push('disposition.kind', `must be one of: ${[...DISPOSITION_KINDS].join(', ')}`)
+				if (typeof d.ref !== 'string' || d.ref.trim().length === 0)
+					push('disposition.ref', 'missing or empty `ref`')
+			}
+		}
+
+		if (schema_errors.length === errsBefore) {
+			rows.push({
+				id,
+				title: r.title,
+				class_proposed: r.class_proposed,
+				origin: r.origin,
+				files: Array.isArray(r.files) ? r.files : [],
+				outcome_refs: Array.isArray(r.outcome_refs) ? r.outcome_refs : [],
+				status: r.status,
+				...(r.adjudication !== undefined
+					? { adjudication: normalizeAdjudication(r.adjudication) }
+					: {}),
+				...(r.disposition !== undefined
+					? { disposition: normalizeDisposition(r.disposition) }
+					: {}),
+			})
+		}
+	}
+
+	return { rows, schema_errors }
+}
+
+/**
+ * Rows that block `task close`: any `open` row, or any `dispositioned` row
+ * without a valid `disposition.kind` + `ref`. (A `fixed` row is settled.)
+ *
+ * @template {SelectorRow} T
+ * @param {{rows: T[]}} parsed
+ * @returns {T[]}
+ */
+export function listBlockingRowsForClose(parsed) {
+	const rows = parsed && Array.isArray(parsed.rows) ? parsed.rows : []
+	return rows.filter((r) => {
+		if (r.status === 'open') return true
+		if (r.status === 'dispositioned') {
+			const d = r.disposition
+			return (
+				!d ||
+				!DISPOSITION_KINDS.has(d.kind) ||
+				typeof d.ref !== 'string' ||
+				d.ref.trim().length === 0
+			)
+		}
+		return false
+	})
+}
+
+/**
+ * Open rows that have no `adjudication` (ship-gate input).
+ *
+ * @template {SelectorRow} T
+ * @param {{rows: T[]}} parsed
+ * @returns {T[]}
+ */
+export function listUnadjudicatedOpen(parsed) {
+	const rows = parsed && Array.isArray(parsed.rows) ? parsed.rows : []
+	return rows.filter((r) => r.status === 'open' && !r.adjudication)
+}
+
+/**
+ * Load-bearing rows that are not yet fixed (ship-gate input).
+ *
+ * @template {SelectorRow} T
+ * @param {{rows: T[]}} parsed
+ * @returns {T[]}
+ */
+export function listLoadBearingUnfixed(parsed) {
+	const rows = parsed && Array.isArray(parsed.rows) ? parsed.rows : []
+	return rows.filter(
+		(r) => r.adjudication && r.adjudication.verdict === 'load-bearing' && r.status !== 'fixed',
+	)
+}
+
+/**
+ * Rows whose `status === 'dispositioned'` lack a valid disposition record.
+ *
+ * @template {SelectorRow} T
+ * @param {{rows: T[]}} parsed
+ * @returns {T[]}
+ */
+export function listUndispositioned(parsed) {
+	const rows = parsed && Array.isArray(parsed.rows) ? parsed.rows : []
+	return rows.filter((r) => {
+		if (r.status !== 'dispositioned') return false
+		const d = r.disposition
+		return (
+			!d || !DISPOSITION_KINDS.has(d.kind) || typeof d.ref !== 'string' || d.ref.trim().length === 0
+		)
+	})
+}
+
+function extractRows(doc) {
+	if (Array.isArray(doc)) return doc
+	if (doc && typeof doc === 'object' && Array.isArray(doc.rows)) return doc.rows
+	return null
+}
+
+function isStringArray(v) {
+	return Array.isArray(v) && v.every((x) => typeof x === 'string')
+}
+
+function normalizeAdjudication(a) {
+	const out = { verdict: a.verdict, by: a.by }
+	if (a.outcome_ref !== undefined) out.outcome_ref = a.outcome_ref
+	return out
+}
+
+function normalizeDisposition(d) {
+	const out = { kind: d.kind, ref: d.ref }
+	if (typeof d.reason === 'string') out.reason = d.reason
+	return out
+}