@aperant/framework 0.8.7 → 0.10.0

package/src/cli/commands/triage.mjs

@@ -3,8 +3,10 @@
  *
  * 5-state triage state machine with extensible metadata for v2 OSS
  * contributor primitives. Backend-configured: writes to
- * `.aperant/tasks/{task-id}/triage.json` by default (local-only); other
- * backends (github-issues, app-inbox) ship as not-implemented stubs.
+ * `.aperant/tasks/{task-id}/triage.json` by default (local-only). The
+ * `github-issues` backend mirrors triage state to a real GitHub issue via
+ * the `gh` CLI (create on first mirror, update/close on transition); the
+ * `app-inbox` backend remains a not-implemented stub (post-app-launch).
  *
  * Subcommands:
  *   apt-tools triage init <project-dir> --id <task-id> [--category bug|enhancement] [--extra '{...}']
@@ -20,6 +22,7 @@
  * mechanical state-machine surface; the routing is the skill body's job.
  */
 
+import { execFileSync } from 'node:child_process'
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import { parseFlags } from '../util/args.mjs'
@@ -71,6 +74,29 @@ function readBackend(absProjectDir) {
 	}
 }
 
+/**
+ * Read task_tracking.tracker_label_vocabulary from .aperant/config.json.
+ * Absent or "default" → use the `triage:<state>` prefix; any other
+ * non-empty string → that string is used as the label prefix instead
+ * (`<vocab>:<state>`). Per spec ID-03 / AC5. This is the ONLY label
+ * configurability — no speculative label-map.
+ *
+ * @param {string} absProjectDir
+ * @returns {string} the label prefix (default 'triage')
+ */
+function readLabelVocabulary(absProjectDir) {
+	const configPath = join(absProjectDir, '.aperant', 'config.json')
+	if (!existsSync(configPath)) return 'triage'
+	try {
+		const parsed = JSON.parse(readFileSync(configPath, 'utf-8'))
+		const vocab = parsed?.task_tracking?.tracker_label_vocabulary
+		if (typeof vocab === 'string' && vocab.length > 0 && vocab !== 'default') return vocab
+		return 'triage'
+	} catch {
+		return 'triage'
+	}
+}
+
 /**
  * Triage record file path.
  *
@@ -108,25 +134,321 @@ function writeTriage(path, record) {
 }
 
 /**
- * Apply the backend mirror step. local-only writes to disk; the other
- * backends return a not-implemented envelope so callers can handle the
- * stub gracefully.
+ * Map a `gh` invocation's arg array to a stable subcommand key for the
+ * test fixture (ID-07). The fixture maps these keys to {stdout, exitCode}.
+ *
+ * @param {string[]} args
+ * @returns {string}
+ */
+function ghFixtureKey(args) {
+	if (args[0] === '--version') return 'version'
+	if (args[0] === 'auth' && args[1] === 'status') return 'auth-status'
+	if (args[0] === 'repo' && args[1] === 'view') return 'repo-view'
+	if (args[0] === 'issue' && args[1] === 'create') return 'issue-create'
+	if (args[0] === 'issue' && args[1] === 'edit') return 'issue-edit'
+	if (args[0] === 'issue' && args[1] === 'close') return 'issue-close'
+	return args.slice(0, 2).join('-')
+}
+
+/**
+ * The single injection seam for `gh` shell-outs (ID-07). When
+ * process.env.APT_TRIAGE_GH_FIXTURE is set (a JSON map of subcommand key →
+ * {stdout, exitCode}), it returns the scripted response instead of
+ * shelling out — keeping unit tests hermetic (no network). Otherwise it
+ * runs `execFileSync('gh', args, ...)` with an arg array (NEVER a shell
+ * string — titles/bodies derive from task ids/reasons, ID-01).
+ *
+ * Returns a uniform `{ stdout, exitCode }`. A non-zero exit (or ENOENT) is
+ * reported via the return shape, NOT thrown — the caller maps it to an
+ * error envelope. The only thrown-then-caught path is ENOENT (gh missing),
+ * surfaced as exitCode:127 with code:'ENOENT' on the result.
+ *
+ * @param {string[]} args
+ * @param {string} cwd
+ * @returns {{ stdout: string, stderr: string, exitCode: number, code?: string }}
+ */
+function runGh(args, cwd) {
+	const fixtureRaw = process.env.APT_TRIAGE_GH_FIXTURE
+	if (fixtureRaw) {
+		let fixture
+		try {
+			fixture = JSON.parse(fixtureRaw)
+		} catch {
+			return { stdout: '', stderr: 'invalid APT_TRIAGE_GH_FIXTURE JSON', exitCode: 1 }
+		}
+		const key = ghFixtureKey(args)
+		const scripted = fixture[key]
+		if (!scripted) {
+			// No scripted entry → treat as gh missing so tests must be explicit.
+			return { stdout: '', stderr: `no fixture for ${key}`, exitCode: 127, code: 'ENOENT' }
+		}
+		return {
+			stdout: typeof scripted.stdout === 'string' ? scripted.stdout : '',
+			stderr: typeof scripted.stderr === 'string' ? scripted.stderr : '',
+			exitCode: typeof scripted.exitCode === 'number' ? scripted.exitCode : 0,
+			...(scripted.code ? { code: scripted.code } : {}),
+		}
+	}
+	try {
+		const stdout = execFileSync('gh', args, {
+			cwd,
+			encoding: 'utf-8',
+			stdio: ['ignore', 'pipe', 'pipe'],
+		})
+		return { stdout: stdout ?? '', stderr: '', exitCode: 0 }
+	} catch (e) {
+		// execFileSync throws on non-zero exit AND on spawn failure (ENOENT).
+		return {
+			stdout: typeof e?.stdout === 'string' ? e.stdout : '',
+			stderr: typeof e?.stderr === 'string' ? e.stderr : (e?.message ?? String(e)),
+			exitCode: typeof e?.status === 'number' ? e.status : 1,
+			...(e?.code ? { code: e.code } : {}),
+		}
+	}
+}
+
+/**
+ * Truncate a gh stderr message to a plain ~200-char string for the error
+ * envelope. NEVER returns an Error object / stacktrace (AC6).
+ *
+ * @param {string} stderr
+ * @returns {string}
+ */
+function ghErrorMessage(stderr) {
+	return String(stderr ?? '')
+		.trim()
+		.slice(0, 200)
+}
+
+/**
+ * Build the structured `gh` error envelope (ID-04). The adapter NEVER
+ * throws past its own boundary; every failure routes here.
+ *
+ * @param {string} reason
+ * @param {string} message
+ */
+function ghError(reason, message) {
+	return { status: 'error', backend: 'github-issues', reason, error: ghErrorMessage(message) }
+}
+
+/**
+ * Preflight: gh present? authenticated? remote/repo resolvable? (ID-05).
+ * Short-circuits to an error envelope on the first failure; on success
+ * returns the resolved `owner/repo` for deterministic `--repo` passing.
+ *
+ * @param {string} cwd
+ * @returns {{ ok: true, repo: string } | { ok: false, envelope: object }}
+ */
+function ghPreflight(cwd) {
+	const version = runGh(['--version'], cwd)
+	if (version.code === 'ENOENT' || version.exitCode === 127) {
+		return { ok: false, envelope: ghError('gh-unavailable', 'gh CLI not found on PATH') }
+	}
+	if (version.exitCode !== 0) {
+		return { ok: false, envelope: ghError('gh-unavailable', version.stderr) }
+	}
+	const auth = runGh(['auth', 'status'], cwd)
+	if (auth.exitCode !== 0) {
+		return { ok: false, envelope: ghError('gh-unauthenticated', auth.stderr) }
+	}
+	const repo = runGh(['repo', 'view', '--json', 'nameWithOwner', '--jq', '.nameWithOwner'], cwd)
+	if (repo.exitCode !== 0) {
+		return { ok: false, envelope: ghError('no-remote', repo.stderr) }
+	}
+	const nameWithOwner = repo.stdout.trim()
+	if (!nameWithOwner) {
+		return { ok: false, envelope: ghError('no-remote', 'gh repo view returned no nameWithOwner') }
+	}
+	return { ok: true, repo: nameWithOwner }
+}
+
+/**
+ * Parse the issue number + url from `gh issue create` stdout. gh prints
+ * the issue URL as the trailing line; the number is the path tail
+ * (`.../issues/N`). Documented parse assumption (spec Further Notes).
+ *
+ * @param {string} stdout
+ * @returns {{ issue_number: number, issue_url: string } | null}
+ */
+function parseCreatedIssue(stdout) {
+	const url = String(stdout ?? '')
+		.trim()
+		.split('\n')
+		.filter((l) => l.includes('/issues/'))
+		.pop()
+	if (!url) return null
+	const m = url.match(/\/issues\/(\d+)\b/)
+	if (!m) return null
+	return { issue_number: Number(m[1]), issue_url: url.trim() }
+}
+
+/**
+ * github-issues adapter (ID-01/02/03/04/05). Mirrors triage state to a
+ * real GitHub issue via the `gh` CLI: first mirror CREATES an issue,
+ * subsequent transitions UPDATE the SAME issue (label swap), and a
+ * transition to `wontfix` CLOSES it as "not planned". Persists the issue
+ * pointer onto `triage.json` (like local-only) so the pointer survives.
+ *
+ * Precedence (spec Further Notes): the local triage.json write is the
+ * caller's responsibility for local-only; here, the github backend is the
+ * sole persistence path, so this adapter writes triage.json itself with
+ * the github block attached. Label ops are best-effort (AC8): a failed
+ * label edit degrades to a warnings[] entry, the open/closed state change
+ * still lands.
+ *
+ * @param {string} absProjectDir
+ * @param {string} taskId
+ * @param {object} record  the (init or post-transition) triage record; mutated to carry `record.github`
+ * @returns {{ status: string, backend: 'github-issues', [k: string]: unknown }}
+ */
+function mirrorToGithubIssues(absProjectDir, taskId, record) {
+	const cwd = absProjectDir
+	const prefix = readLabelVocabulary(absProjectDir)
+	const stateLabel = (state) => `${prefix}:${state}`
+
+	const pre = ghPreflight(cwd)
+	if (!pre.ok) return pre.envelope
+	const repo = pre.repo
+
+	const warnings = []
+	const persist = () => writeTriage(triagePath(absProjectDir, taskId), record)
+
+	// CREATE path: no issue yet on the record.
+	if (!record.github || typeof record.github.issue_number !== 'number') {
+		const labels = []
+		if (typeof record.category === 'string' && record.category) labels.push(record.category)
+		labels.push(stateLabel(record.state))
+		const createArgs = [
+			'issue',
+			'create',
+			'--title',
+			`triage: ${taskId}`,
+			'--body',
+			`Triage state: ${record.state}${record.category ? ` (${record.category})` : ''}`,
+			'--repo',
+			repo,
+		]
+		for (const l of labels) createArgs.push('--label', l)
+		let res = runGh(createArgs, cwd)
+		if (res.exitCode !== 0) {
+			// AC8: a label that doesn't exist in the repo fails the create.
+			// Retry WITHOUT label flags so the issue still gets created.
+			const noLabelArgs = createArgs.filter(
+				(a, i) => a !== '--label' && createArgs[i - 1] !== '--label',
+			)
+			const retry = runGh(noLabelArgs, cwd)
+			if (retry.exitCode !== 0) {
+				return ghError('gh-command-failed', res.stderr || retry.stderr)
+			}
+			warnings.push(`label(s) not applied on create: ${ghErrorMessage(res.stderr)}`)
+			res = retry
+		}
+		const parsed = parseCreatedIssue(res.stdout)
+		if (!parsed) {
+			return ghError('gh-command-failed', `could not parse issue URL from: ${res.stdout}`)
+		}
+		record.github = { issue_number: parsed.issue_number, issue_url: parsed.issue_url, repo }
+		persist()
+		return {
+			status: 'ok',
+			backend: 'github-issues',
+			action: 'created',
+			issue_number: parsed.issue_number,
+			issue_url: parsed.issue_url,
+			warnings,
+		}
+	}
+
+	// UPDATE / CLOSE path: the record already points at an issue.
+	const issueNumber = record.github.issue_number
+	const issueRepo = typeof record.github.repo === 'string' ? record.github.repo : repo
+	// The previous state is the `from` of the last transition (the one that
+	// produced this record); on init there are no transitions.
+	const txs = Array.isArray(record.transitions) ? record.transitions : []
+	const lastTx = txs.length > 0 ? txs[txs.length - 1] : null
+	const oldLabel = lastTx ? stateLabel(lastTx.from) : null
+	const newLabel = stateLabel(record.state)
+
+	const editArgs = ['issue', 'edit', String(issueNumber), '--repo', issueRepo]
+	if (oldLabel) editArgs.push('--remove-label', oldLabel)
+	editArgs.push('--add-label', newLabel)
+	const edit = runGh(editArgs, cwd)
+	if (edit.exitCode !== 0) {
+		// AC8: label op failed (e.g. label not in repo). Degrade: skip the
+		// label swap, still perform the open/closed state change, warn.
+		warnings.push(`label swap skipped: ${ghErrorMessage(edit.stderr)}`)
+	}
+
+	if (record.state === 'wontfix') {
+		const close = runGh(
+			['issue', 'close', String(issueNumber), '--repo', issueRepo, '--reason', 'not planned'],
+			cwd,
+		)
+		if (close.exitCode !== 0) {
+			return ghError('gh-command-failed', close.stderr)
+		}
+		record.github = {
+			issue_number: issueNumber,
+			issue_url: record.github.issue_url,
+			repo: issueRepo,
+		}
+		persist()
+		return {
+			status: 'ok',
+			backend: 'github-issues',
+			action: 'closed',
+			issue_number: issueNumber,
+			issue_url: record.github.issue_url,
+			warnings,
+		}
+	}
+
+	record.github = { issue_number: issueNumber, issue_url: record.github.issue_url, repo: issueRepo }
+	persist()
+	return {
+		status: 'ok',
+		backend: 'github-issues',
+		action: 'updated',
+		issue_number: issueNumber,
+		issue_url: record.github.issue_url,
+		warnings,
+	}
+}
+
+/**
+ * Apply the backend mirror step. local-only writes to disk; github-issues
+ * dispatches to the gh-CLI adapter; app-inbox stays a not-implemented stub
+ * so callers can handle it gracefully.
  *
  * @param {string} backend
  * @param {string} absProjectDir
  * @param {string} taskId
  * @param {object} record
- * @returns {null | { status: 'not-implemented', backend: string, v2_issue: string }}
+ * @returns {null | { status: string, backend?: string, [k: string]: unknown }}
  */
 function mirrorToBackend(backend, absProjectDir, taskId, record) {
 	if (backend === 'local-only') {
 		writeTriage(triagePath(absProjectDir, taskId), record)
 		return null
 	}
-	// v1 stubs: github-issues and app-inbox return not-implemented.
+	if (backend === 'github-issues') {
+		return mirrorToGithubIssues(absProjectDir, taskId, record)
+	}
+	// v1 stub: app-inbox returns not-implemented (out of scope per spec).
 	return { status: 'not-implemented', backend, v2_issue: '#TBD' }
 }
 
+/**
+ * Map a non-null mirror envelope to its exit code. github-issues errors
+ * exit 1 (ID-04); the not-implemented stub and ok envelopes exit 0.
+ *
+ * @param {{ status: string, [k: string]: unknown }} mirror
+ * @returns {number}
+ */
+function mirrorExitCode(mirror) {
+	return mirror.status === 'error' ? 1 : 0
+}
+
 /**
  * Entry: `apt-tools triage <subcommand> <project-dir> [flags]`.
  */
@@ -200,8 +522,17 @@ export function cmdTriage(subcommand, projectDir, extraArgs) {
 			transitions: [],
 			extra,
 		}
-		const stub = mirrorToBackend(backend, absProjectDir, taskId, record)
-		if (stub) return exitWith({ command: 'triage-init', ...stub }, 0)
+		const mirror = mirrorToBackend(backend, absProjectDir, taskId, record)
+		if (mirror) {
+			// github-issues success merges its action/issue fields and echoes
+			// the persisted record (which now carries `github`); errors + the
+			// app-inbox not-implemented stub pass through as-is.
+			const merged =
+				mirror.status === 'ok'
+					? { command: 'triage-init', ...mirror, record }
+					: { command: 'triage-init', ...mirror }
+			return exitWith(merged, mirrorExitCode(mirror))
+		}
 		return ok({ status: 'ok', command: 'triage-init', backend, record })
 	}
 
@@ -259,9 +590,19 @@ export function cmdTriage(subcommand, projectDir, extraArgs) {
 			category: current.category,
 			extra: current.extra ?? {},
 			transitions: [...(current.transitions || []), transition],
+			// ID-02: carry the github issue pointer forward so subsequent
+			// transitions target the SAME issue instead of creating a duplicate.
+			// Only set when present (local-only records never carry it).
+			...(current.github ? { github: current.github } : {}),
+		}
+		const mirror = mirrorToBackend(backend, absProjectDir, taskId, next)
+		if (mirror) {
+			const merged =
+				mirror.status === 'ok'
+					? { command: 'triage-transition', ...mirror, transition, record: next }
+					: { command: 'triage-transition', ...mirror }
+			return exitWith(merged, mirrorExitCode(mirror))
 		}
-		const stub = mirrorToBackend(backend, absProjectDir, taskId, next)
-		if (stub) return exitWith({ command: 'triage-transition', ...stub }, 0)
 		return ok({
 			status: 'ok',
 			command: 'triage-transition',

package/src/cli/commands/uninstall.mjs

@@ -7,10 +7,10 @@
  * root — unknown files are left alone and the directory is preserved if
  * it would otherwise be non-empty.
  *
- * The APT section in `CLAUDE.md` / `AGENTS.md` is stripped between the
- * `<!-- APT:framework-start -->` / `<!-- APT:framework-end -->` markers
- * (same injection surface as `injectInstructionFile`). If the file becomes
- * empty after the strip, the file is removed too.
+ * The APT section in `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` is stripped
+ * between the `<!-- APT:framework-start -->` / `<!-- APT:framework-end -->`
+ * markers (same injection surface as `injectInstructionFile`). If the file
+ * becomes empty after the strip, the file is removed too.
  *
  * Flags:
  *   --purge               Also delete `.aperant/` state. Default: preserve
@@ -34,15 +34,18 @@ import {
 import { join, resolve } from 'node:path'
 import { MANIFEST_FILENAME } from '../install/manifest.mjs'
 import { RUNTIMES } from '../install/runtime-detect.mjs'
+import { APT_SECTION_STRIP_RE as APT_SECTION_RE } from '../util/aperant-section.mjs'
 import { err, ok } from '../util/result.mjs'
 
-const APT_SECTION_RE = /<!-- APT:framework-start -->[\s\S]*?<!-- APT:framework-end -->\n?/
 const APT_GITIGNORE_BLOCK_RE = /# APT:gitignore-start[\s\S]*?# APT:gitignore-end\n?/
 
 /**
  * Files inside the project root that may carry the APT-injected section.
+ * Derived from RUNTIMES.nativeInstructionFile so the list stays in sync with
+ * whatever targets `init` writes — the same drift class as the bug this PR
+ * fixes cannot occur here.
  */
-const INSTRUCTION_FILES = ['CLAUDE.md', 'AGENTS.md']
+const INSTRUCTION_FILES = [...new Set(RUNTIMES.map((r) => r.nativeInstructionFile).filter(Boolean))]
 
 /**
  * @typedef {Object} UninstallFlags
@@ -289,8 +292,8 @@ function removeRuntime(target, flags) {
 }
 
 /**
- * Strip the APT-injected section from CLAUDE.md / AGENTS.md. If the
- * remaining file is empty, the file itself is removed.
+ * Strip the APT-injected section from CLAUDE.md / AGENTS.md / GEMINI.md. If
+ * the remaining file is empty, the file itself is removed.
  *
  * @param {string} targetDir
  * @param {UninstallFlags} flags

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/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 {