@aperant/framework 0.6.2

package/src/cli/constitution/parse.mjs

@@ -0,0 +1,362 @@
+/**
+ * @internal
+ * constitution/parse.mjs — AGENTS.md principle extractor (C14 subtask 1).
+ *
+ * Pure function: parseAgentsMd(markdown) -> Principle[]
+ *
+ * A Principle is:
+ *   {
+ *     id:       string,      // stable slug
+ *     title:    string,      // human-readable first line / heading
+ *     text:     string,      // the matched chunk (keyword seed)
+ *     source:   { section: string, line: number },
+ *     keywords: string[],    // derived, deduped, stopword-stripped
+ *     severity: 'must' | 'should' | 'never' | 'principle' | 'obligation'
+ *   }
+ *
+ * Extraction rules (applied in order, dedup by normalized title):
+ *   1. Numbered lists under a heading matching /principles?|constraints?|rules?/i
+ *      → severity 'principle', id `p{n}-{slug(title)}`.
+ *   2. Bullets (any depth) containing a standalone MUST/SHOULD/NEVER token
+ *      (word-boundary, case-sensitive) → severity from the token,
+ *      id `{severity}-{slug(first-5-words)}`.
+ *   3. Rows of the "Deployment Modes" + "Obligations" table →
+ *      one principle per row + an umbrella principle
+ *      `deployment-modes-all-modes` whose keywords include every mode name.
+ *
+ * Returns `[]` (not throws) on empty string or markdown with no matches.
+ */
+
+const STOPWORDS = new Set([
+	'the',
+	'a',
+	'an',
+	'and',
+	'or',
+	'of',
+	'for',
+	'to',
+	'in',
+	'on',
+	'must',
+	'should',
+	'never',
+	'with',
+	'without',
+	'is',
+	'are',
+	'this',
+	'that',
+	'these',
+	'those',
+	'be',
+	'been',
+	'being',
+	'have',
+	'has',
+	'had',
+	'not',
+	'but',
+	'from',
+	'into',
+	'over',
+	'under',
+	'its',
+])
+
+/**
+ * Lowercase + replace non-alphanumerics with hyphens + trim.
+ * Used for building stable slug ids.
+ */
+function slugify(text) {
+	return String(text)
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, '-')
+		.replace(/^-+|-+$/g, '')
+		.slice(0, 60)
+}
+
+/**
+ * Derive keywords from a text chunk:
+ *   lowercase → strip non-[a-z0-9] → drop stopwords → keep len >= 4 → dedup.
+ */
+function deriveKeywords(text) {
+	const seen = new Set()
+	const out = []
+	const tokens = String(text)
+		.toLowerCase()
+		.split(/[^a-z0-9]+/g)
+		.filter(Boolean)
+	for (const tok of tokens) {
+		if (tok.length < 4) continue
+		if (STOPWORDS.has(tok)) continue
+		if (seen.has(tok)) continue
+		seen.add(tok)
+		out.push(tok)
+	}
+	return out
+}
+
+/**
+ * Normalize a title for dedup: lowercase + collapse whitespace + strip
+ * punctuation.
+ */
+function normalizeTitle(title) {
+	return String(title)
+		.toLowerCase()
+		.replace(/[^a-z0-9\s]+/g, ' ')
+		.replace(/\s+/g, ' ')
+		.trim()
+}
+
+/**
+ * Detect a `## Heading` or `### Heading` line. Returns {level, title} or null.
+ */
+function parseHeading(line) {
+	const m = /^(#{1,6})\s+(.+?)\s*$/.exec(line)
+	if (!m) return null
+	return { level: m[1].length, title: m[2] }
+}
+
+/**
+ * Strip markdown bullet/numbering prefix and any bold wrappers so the caller
+ * sees the raw text content of a bullet line.
+ */
+function stripBulletPrefix(line) {
+	return line
+		.replace(/^\s*(?:[-*+]|\d+\.)\s+/, '')
+		.replace(/^\*\*(.+?)\*\*/, '$1')
+		.trim()
+}
+
+/**
+ * Return true when the line starts a bullet (any depth) or a numbered item.
+ */
+function isBullet(line) {
+	return /^\s*(?:[-*+]|\d+\.)\s+/.test(line)
+}
+
+/**
+ * Return true when the line looks like a Principles/Constraints/Rules heading.
+ */
+function isPrinciplesHeading(title) {
+	return /principles?|constraints?|rules?/i.test(title)
+}
+
+/**
+ * Return true when the line looks like the Deployment-Modes obligation heading.
+ */
+function isDeploymentModesHeading(title) {
+	return /deployment\s*modes/i.test(title) && /obligation/i.test(title)
+}
+
+/**
+ * Pull the first N words out of a text chunk (used for slug seeds).
+ */
+function firstWords(text, n) {
+	return String(text).split(/\s+/).slice(0, n).join(' ')
+}
+
+/**
+ * Extract principles from an AGENTS.md markdown string.
+ *
+ * @param {string} markdown
+ * @returns {Array<{
+ *   id: string,
+ *   title: string,
+ *   text: string,
+ *   source: { section: string, line: number },
+ *   keywords: string[],
+ *   severity: 'must'|'should'|'never'|'principle'|'obligation'
+ * }>}
+ */
+export function parseAgentsMd(markdown) {
+	if (typeof markdown !== 'string' || markdown.length === 0) return []
+	const lines = markdown.split(/\r?\n/)
+
+	const principles = []
+	const seenTitles = new Set()
+
+	function push(p) {
+		const key = normalizeTitle(p.title)
+		if (!key) return
+		if (seenTitles.has(key)) return
+		seenTitles.add(key)
+		principles.push(p)
+	}
+
+	// Track state across lines.
+	let section = '(root)'
+	let inPrinciples = false
+	let principlesCounter = 0
+	let tableHeadingSection = null
+	let tableHeaderLine = null
+	let tableHeaderCols = null
+	let tableRowsSeen = 0
+	const deploymentModeNames = []
+
+	for (let i = 0; i < lines.length; i++) {
+		const rawLine = lines[i]
+		const line = rawLine
+
+		const heading = parseHeading(line)
+		if (heading) {
+			// If we were mid-way through a deployment-modes table and a new
+			// heading appears, finalize the umbrella principle for the rows
+			// we already collected before we lose the state.
+			if (tableHeadingSection && tableRowsSeen > 0) {
+				const umbrellaText = `Deployment modes: ${deploymentModeNames.join(', ')}`
+				push({
+					id: 'deployment-modes-all-modes',
+					title: 'Deployment modes — all modes covered',
+					text: umbrellaText,
+					source: { section: tableHeadingSection, line: tableHeaderLine ?? i + 1 },
+					keywords: [
+						'deployment',
+						'modes',
+						...deploymentModeNames.map((m) => slugify(m).replace(/-/g, '')),
+						...deriveKeywords(umbrellaText),
+					].filter(Boolean),
+					severity: 'obligation',
+				})
+			}
+
+			section = heading.title
+			inPrinciples = isPrinciplesHeading(heading.title)
+			if (inPrinciples) principlesCounter = 0
+			// Deployment-modes detection — next non-blank bullet block below
+			// triggers table parsing.
+			if (isDeploymentModesHeading(heading.title)) {
+				tableHeadingSection = heading.title
+				tableHeaderLine = null
+				tableHeaderCols = null
+				tableRowsSeen = 0
+			} else {
+				// A non-deployment heading clears any partially-collected table
+				// state (we only read the table directly below its heading).
+				if (tableHeadingSection && i > 0) {
+					tableHeadingSection = null
+					tableHeaderCols = null
+					tableRowsSeen = 0
+				}
+			}
+			continue
+		}
+
+		// Rule 3 — Deployment Modes table rows.
+		if (tableHeadingSection) {
+			// Table detection: a line starting with `|` is a table row; header
+			// is followed by a `|---|---|` separator.
+			if (/^\s*\|/.test(line)) {
+				const cols = line
+					.trim()
+					.replace(/^\|/, '')
+					.replace(/\|\s*$/, '')
+					.split('|')
+					.map((c) => c.trim())
+				if (!tableHeaderCols) {
+					tableHeaderCols = cols
+					tableHeaderLine = i + 1
+					continue
+				}
+				// Separator row — skip.
+				if (cols.every((c) => /^:?-+:?$/.test(c))) continue
+				// Data row → first column is the mode name.
+				const modeName = cols[0].replace(/\*\*/g, '').trim()
+				if (!modeName) continue
+				const rowText = cols.join(' ')
+				tableRowsSeen++
+				deploymentModeNames.push(modeName)
+				push({
+					id: `deployment-mode-${slugify(modeName)}`,
+					title: `Deployment mode: ${modeName}`,
+					text: rowText,
+					source: { section: tableHeadingSection, line: i + 1 },
+					keywords: deriveKeywords(`${modeName} ${rowText}`),
+					severity: 'obligation',
+				})
+				continue
+			}
+			// A non-table, non-blank line after we started collecting rows
+			// means the table has ended. Finalize the umbrella principle.
+			if (tableRowsSeen > 0 && line.trim().length > 0) {
+				const umbrellaText = `Deployment modes: ${deploymentModeNames.join(', ')}`
+				push({
+					id: 'deployment-modes-all-modes',
+					title: 'Deployment modes — all modes covered',
+					text: umbrellaText,
+					source: { section: tableHeadingSection, line: tableHeaderLine ?? i + 1 },
+					keywords: [
+						'deployment',
+						'modes',
+						...deploymentModeNames.map((m) => slugify(m).replace(/-/g, '')),
+						...deriveKeywords(umbrellaText),
+					].filter(Boolean),
+					severity: 'obligation',
+				})
+				tableHeadingSection = null
+				tableHeaderCols = null
+				tableRowsSeen = 0
+			}
+		}
+
+		// Rule 1 — numbered list under a Principles/Constraints/Rules heading.
+		if (inPrinciples && /^\s*\d+\.\s+/.test(line)) {
+			principlesCounter++
+			const body = stripBulletPrefix(line)
+			const titleSeed = firstWords(body.replace(/[.:]/g, ' '), 5)
+			push({
+				id: `p${principlesCounter}-${slugify(titleSeed)}`,
+				title: body,
+				text: body,
+				source: { section, line: i + 1 },
+				keywords: deriveKeywords(body),
+				severity: 'principle',
+			})
+			continue
+		}
+
+		// Rule 2 — bullets with a standalone MUST/SHOULD/NEVER token.
+		if (isBullet(line)) {
+			const body = stripBulletPrefix(line)
+			// MUST NOT should still count as 'must' (rule hits MUST first).
+			const tokenMatch = /\b(MUST|SHOULD|NEVER)\b/.exec(body)
+			if (tokenMatch) {
+				const severity = tokenMatch[1].toLowerCase()
+				const titleSeed = firstWords(body.replace(/[.:]/g, ' '), 5)
+				push({
+					id: `${severity}-${slugify(titleSeed)}`,
+					title: body,
+					text: body,
+					source: { section, line: i + 1 },
+					keywords: deriveKeywords(body),
+					severity,
+				})
+			}
+		}
+	}
+
+	// If the file ends while a deployment-modes table was still open, emit
+	// the umbrella principle now.
+	if (tableHeadingSection && tableRowsSeen > 0) {
+		const umbrellaText = `Deployment modes: ${deploymentModeNames.join(', ')}`
+		push({
+			id: 'deployment-modes-all-modes',
+			title: 'Deployment modes — all modes covered',
+			text: umbrellaText,
+			source: { section: tableHeadingSection, line: tableHeaderLine ?? lines.length },
+			keywords: [
+				'deployment',
+				'modes',
+				...deploymentModeNames.map((m) => slugify(m).replace(/-/g, '')),
+				...deriveKeywords(umbrellaText),
+			].filter(Boolean),
+			severity: 'obligation',
+		})
+	}
+
+	return principles
+}
+
+// Re-export helpers so match.mjs / tests can reuse the same stopword policy.
+export { deriveKeywords, normalizeTitle, slugify }

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

@@ -0,0 +1,102 @@
+/**
+ * @internal
+ * agent-identity.mjs — per-agent identity record (R4 precursor).
+ *
+ * This module is part of the @internal CoordinationStore seam (R8). Do NOT
+ * import from `bin/apt-tools.mjs` or add to any package `exports` map.
+ *
+ * V1 returns `{ agentId, pid, hostname, incarnation }` — enough for the
+ * team-status directory in R2 to key per-agent files. R4 (subtask 6) fills in
+ * TTL-based liveness filtering on top of this record.
+ *
+ * Incarnation is a monotonic counter stored at
+ * `.aperant/team-status/.incarnation`. Incremented once per process via
+ * `nextIncarnation(projectRoot)` during identity resolution and cached in
+ * module scope so repeated calls within the same process are stable.
+ */
+
+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'
+
+// 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.
+ */
+export function resolveSharedRoot(projectDir) {
+	const wt = detectWorktree(projectDir)
+	return wt.is_worktree && wt.main_repo_root ? wt.main_repo_root : projectDir
+}
+
+/**
+ * Read and increment the per-project incarnation counter atomically. Stored
+ * as JSON `{ value: <int> }` under `.aperant/team-status/.incarnation` so the
+ * normal atomicWriteJson pipeline handles it.
+ *
+ * If the counter file is missing/malformed, we start from 1.
+ */
+function nextIncarnation(projectRoot) {
+	const sharedRoot = resolveSharedRoot(projectRoot)
+	const dir = join(sharedRoot, '.aperant', 'team-status')
+	mkdirSync(dir, { recursive: true })
+	const counterPath = join(dir, '.incarnation')
+	let next = 1
+	withFileLock(
+		counterPath,
+		() => {
+			let current = 0
+			if (existsSync(counterPath)) {
+				try {
+					const raw = readFileSync(counterPath, 'utf-8').trim()
+					const parsed = JSON.parse(raw)
+					if (typeof parsed?.value === 'number' && Number.isFinite(parsed.value)) {
+						current = parsed.value
+					}
+				} catch {
+					/* malformed — restart from 0 */
+				}
+			}
+			next = current + 1
+			atomicWriteJson(counterPath, { value: next })
+		},
+		{ projectRoot: sharedRoot },
+	)
+	return next
+}
+
+/**
+ * Return the current agent's identity. Cached per project root so repeated
+ * callers within a single process see a stable incarnation.
+ *
+ * `APT_AGENT_ID` overrides the default `<hostname>-<pid>` assembly — used by
+ * tests to force a deterministic id.
+ */
+export function getAgentIdentity(projectDir) {
+	const sharedRoot = resolveSharedRoot(projectDir)
+	if (cache.has(sharedRoot)) return cache.get(sharedRoot)
+
+	const pid = process.pid
+	const host = osHostname()
+	const agentId = process.env.APT_AGENT_ID || `${host}-${pid}`
+	const incarnation = nextIncarnation(projectDir)
+	const identity = { agentId, pid, hostname: host, incarnation }
+	cache.set(sharedRoot, identity)
+	return identity
+}
+
+/**
+ * Test-only helper: reset the process-local identity cache so a fresh
+ * getAgentIdentity() call picks up a new incarnation. Not part of the public
+ * surface.
+ *
+ * @internal
+ */
+export function __resetAgentIdentityCacheForTests() {
+	cache.clear()
+}

package/src/cli/coordination/event-log.mjs

@@ -0,0 +1,88 @@
+/**
+ * @internal
+ * event-log.mjs — append-only lifecycle event log (R10).
+ *
+ * Writes one JSON-encoded line per event to
+ * `.aperant/events/{YYYY-MM-DD}.jsonl` via the R3 appendJsonl primitive.
+ * POSIX O_APPEND gives us atomic concurrent writes across agents, so
+ * multiple processes running `task update` / `task close` cannot tear each
+ * other's lines.
+ *
+ * This module is `@internal` — consumed only through the CoordinationStore
+ * seam (store.appendEvent). Do NOT import from bin/apt-tools.mjs.
+ *
+ * The existing numbered-JSON event surface in commands/event.mjs is NOT
+ * touched — its `rebuild-state` consumer keeps working. The JSONL log is
+ * additive, covering the forensic trail the roundtable's Devil's Advocate
+ * required for when state.json / team-status leave git (R2, R6).
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { appendJsonl } from '../util/io.mjs'
+import { getAgentIdentity, resolveSharedRoot } from './agent-identity.mjs'
+
+/**
+ * Derive the day bucket for the current instant. UTC so agents on different
+ * machines agree on the file name.
+ */
+function todayBucket(now = new Date()) {
+	return now.toISOString().slice(0, 10)
+}
+
+/**
+ * Append a lifecycle event. `evt` shape:
+ *   {
+ *     op: 'task.created' | 'task.lifecycle.{phase}' | 'task.closed' | ...,
+ *     task: string,                // task id
+ *     data?: object,               // op-specific payload
+ *   }
+ *
+ * The writer stamps `t`, `agent`, `pid`, `hostname`, `incarnation` onto the
+ * record so consumers can correlate across machines without fetching state.
+ *
+ * `projectRoot` may be a worktree path; the writer resolves the shared main
+ * repo root so every agent's events land in a single directory.
+ *
+ * @internal
+ */
+export function appendLifecycleEvent(projectRoot, evt, now = new Date()) {
+	const sharedRoot = resolveSharedRoot(projectRoot)
+	const identity = getAgentIdentity(projectRoot)
+	const file = join(sharedRoot, '.aperant', 'events', `${todayBucket(now)}.jsonl`)
+	const record = {
+		t: now.toISOString(),
+		agent: identity.agentId,
+		pid: identity.pid,
+		hostname: identity.hostname,
+		incarnation: identity.incarnation,
+		op: evt.op,
+		task: evt.task ?? null,
+		data: evt.data ?? {},
+	}
+	appendJsonl(file, record)
+	return { file, record }
+}
+
+/**
+ * Read all events for a given day bucket (defaults to today, UTC). Returns
+ * an array of parsed objects; malformed lines are skipped defensively.
+ *
+ * @internal
+ */
+export function readLifecycleEventsForDay(projectRoot, day = todayBucket()) {
+	const sharedRoot = resolveSharedRoot(projectRoot)
+	const file = join(sharedRoot, '.aperant', 'events', `${day}.jsonl`)
+	if (!existsSync(file)) return []
+	const body = readFileSync(file, 'utf-8')
+	const out = []
+	for (const line of body.split('\n')) {
+		if (!line) continue
+		try {
+			out.push(JSON.parse(line))
+		} catch {
+			/* skip malformed */
+		}
+	}
+	return out
+}

package/src/cli/coordination/store.mjs

@@ -0,0 +1,146 @@
+/**
+ * @internal
+ * coordination/store.mjs — thin abstraction seam for coordination writes (R8).
+ *
+ * IMPORTANT: this module is `@internal`. It is NOT exported from
+ * `bin/apt-tools.mjs`, it is NOT added to any package `exports` map, and it
+ * must not appear in README / public docs. The seam exists so future
+ * subtasks (R2 team-status dir, R4 liveness, R10 event log) have a single
+ * place to swap implementations without every call site needing an edit.
+ *
+ * V1 contract: every method is a thin wrapper over the existing filesystem
+ * helpers (`atomicWriteJson`, `withFileLock`). Behavior must match the
+ * pre-seam call sites byte-for-byte — C29's smoke-drain harness (retired in
+ * C30) originally guarded against regressions; the vitest suite under
+ * src/__tests__ now owns that coverage.
+ *
+ * Methods:
+ *   - readState()
+ *   - writeState(next) / updateState(mutator)
+ *   - upsertTeamStatus(taskId, data) / removeTeamStatus(taskId)
+ *   - listTeamStatus({ includeStale? })            — filled in by R2
+ *   - appendEvent(evt)                             — filled in by R10
+ *   - resolveSharedRoot()                          — main repo root helper
+ *
+ * Callers that mutate state should use `updateState(mutator)` (lock-protected
+ * read-modify-write). Callers that only read should use `readState()`.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { withFileLock } from '../util/fs-lock.mjs'
+import { atomicWriteJson } from '../util/io.mjs'
+import { getAgentIdentity, resolveSharedRoot } from './agent-identity.mjs'
+import { appendLifecycleEvent } from './event-log.mjs'
+import {
+	listActive as teamStatusListActive,
+	removeSelf as teamStatusRemoveSelf,
+	upsertSelf as teamStatusUpsertSelf,
+} from './team-status.mjs'
+
+/**
+ * Construct a coordination store bound to a specific project root. The
+ * returned object is plain-JS with bound methods — no classes, matching the
+ * rest of the `.mjs` CLI kernel style.
+ *
+ * @internal
+ */
+export function createCoordinationStore(projectRoot) {
+	const sharedRoot = resolveSharedRoot(projectRoot)
+	const statePath = join(sharedRoot, '.aperant', 'state.json')
+
+	return {
+		/** @internal */
+		resolveSharedRoot: () => sharedRoot,
+
+		/** @internal — returns null if state.json is missing or malformed. */
+		readState() {
+			if (!existsSync(statePath)) return null
+			try {
+				return JSON.parse(readFileSync(statePath, 'utf-8'))
+			} catch {
+				return null
+			}
+		},
+
+		/**
+		 * @internal — lock-protected atomic write of the full state object.
+		 * Prefer `updateState(mutator)` for read-modify-write.
+		 */
+		writeState(state) {
+			withFileLock(
+				statePath,
+				() => {
+					atomicWriteJson(statePath, state)
+				},
+				{ projectRoot: sharedRoot },
+			)
+		},
+
+		/**
+		 * @internal — read, mutate via `mutator(state)`, write back under a
+		 * single lock. Mirrors the pattern used throughout commands/task.mjs.
+		 */
+		updateState(mutator) {
+			return withFileLock(
+				statePath,
+				() => {
+					let state = null
+					if (existsSync(statePath)) {
+						try {
+							state = JSON.parse(readFileSync(statePath, 'utf-8'))
+						} catch {
+							state = null
+						}
+					}
+					const result = mutator(state)
+					if (result !== undefined) atomicWriteJson(statePath, result)
+					return result
+				},
+				{ projectRoot: sharedRoot },
+			)
+		},
+
+		/**
+		 * @internal — R2: per-agent team-status/{agentId}.json writes.
+		 * C34: the legacy active.json dual-write has been removed; the
+		 * per-agent directory is the sole source of truth.
+		 */
+		upsertTeamStatus(taskId, data = {}) {
+			teamStatusUpsertSelf(projectRoot, taskId, data)
+		},
+
+		/** @internal — see upsertTeamStatus. */
+		removeTeamStatus(taskId) {
+			teamStatusRemoveSelf(projectRoot, taskId)
+		},
+
+		/**
+		 * @internal — R2 directory aggregation + R4 liveness filtering.
+		 * Pass `{ includeStale: true }` to disable stale-filtering (used by
+		 * `apt-tools active list --include-stale`).
+		 */
+		listTeamStatus(opts = {}) {
+			return teamStatusListActive(projectRoot, opts)
+		},
+
+		/**
+		 * @internal — R10 append-only event log. Emits one JSONL line per
+		 * call via appendLifecycleEvent. Best-effort: filesystem errors are
+		 * swallowed so a missing events/ dir never breaks task lifecycle.
+		 */
+		appendEvent(evt) {
+			try {
+				return appendLifecycleEvent(projectRoot, evt)
+			} catch {
+				/* best-effort — never block a lifecycle transition on the log */
+				return null
+			}
+		},
+
+		/** @internal */
+		getIdentity() {
+			return getAgentIdentity(projectRoot)
+		},
+	}
+}