@aperant/framework 0.8.6 → 0.9.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/install/manifest.mjs

@@ -39,6 +39,11 @@ export const MANIFEST_SCHEMA_VERSION = 1
  * @property {string} installedHash
  * @property {string} sourcePath
  * @property {string} transformVersion
+ * @property {boolean} [headerless]  true when the installed file legitimately
+ *   carries no apt-skill-version/apt-hook-version header (e.g. Codex strips it).
+ *   Drift detection skips the missing_header check for these — installedHash is
+ *   the sole drift signal. Absent (undefined) on pre-0.8.6 manifests → treated
+ *   as header-expected, preserving old behavior until re-install.
  */
 
 /**

package/src/cli/install/pipeline.mjs

@@ -17,6 +17,7 @@ import { atomicWriteText } from './atomic-text.mjs'
 import { addManifestEntry, newManifest, sha256, writeManifest } from './manifest.mjs'
 import { getRuntime } from './runtime-detect.mjs'
 import { classifyFileType } from './transforms/_shared.mjs'
+import { parseVersionHeader } from './version-header.mjs'
 
 const TRANSFORM_VERSION = '1'
 
@@ -67,6 +68,12 @@ function safeResolveWithin(installRoot, outputPath) {
  * @property {string} canonicalRelPath
  * @property {string} version
  * @property {'skill'|'agent'|'hook-js'|'hook-sh'|'unknown'} fileType
+ * @property {Record<string, string>} [agentContentByName]  canonical agent body
+ *   keyed by agent name (basename sans `.md`, e.g. `apt-planner`). Lets a
+ *   transform inline a referenced agent's prompt when the target runtime has
+ *   no separate agent-spawn surface (Codex). The pipeline always supplies it
+ *   (empty object when no agents discovered); optional here so unit tests can
+ *   construct a TransformInput without it — transforms default it to `{}`.
  */
 
 /**
@@ -180,6 +187,19 @@ export function runInstall({
 	const files = canonicalFiles ?? discoverCanonicalFiles(canonicalRoot)
 	const written = []
 	const skipped = []
+	// Map of agent name → canonical agent body, so a transform whose runtime
+	// has no separate agent-spawn surface (Codex) can inline a referenced
+	// agent's prompt. Keyed by basename sans `.md` (e.g. `apt-planner`). When
+	// the same name exists under both skills/ and agents/, last-wins — they are
+	// the same agent (see the de-dupe note below).
+	/** @type {Record<string, string>} */
+	const agentContentByName = {}
+	for (const f of files) {
+		if (f.fileType === 'agent') {
+			const name = f.relPath.replace(/^.*\//, '').replace(/\.md$/, '')
+			agentContentByName[name] = f.content
+		}
+	}
 	// De-dupe by output path — last-write-wins. Two canonical files can
 	// legitimately target the same output (e.g. skills/apt-planner.md and
 	// agents/apt-planner.md both producing agents/apt-planner.md). The
@@ -200,6 +220,7 @@ export function runInstall({
 				canonicalRelPath: f.relPath,
 				version,
 				fileType: f.fileType,
+				agentContentByName,
 			})
 		} catch (err) {
 			skipped.push(
@@ -225,12 +246,19 @@ export function runInstall({
 			}
 			atomicWriteText(absPath, out.content)
 			const installedHash = sha256(out.content)
+			// Record whether the installed file carries a version header. When a
+			// transform legitimately strips it (Codex frontmatter whitelist),
+			// drift detection must not flag it missing_header — installedHash is
+			// the drift signal. Only relevant for header-bearing file types.
+			const headerless =
+				/\.(md|js|mjs|sh)$/.test(out.outputPath) && parseVersionHeader(out.content) === null
 			entryByPath.set(out.outputPath, {
 				path: out.outputPath,
 				sourceHash,
 				installedHash,
 				sourcePath: `packages/framework/${f.relPath}`,
 				transformVersion: TRANSFORM_VERSION,
+				...(headerless ? { headerless: true } : {}),
 			})
 			if (!written.includes(out.outputPath)) written.push(out.outputPath)
 		}

package/src/cli/install/runtime-detect.mjs

@@ -36,6 +36,18 @@ import { MANIFEST_FILENAME } from './manifest.mjs'
  *                                  capitalized form of `id`. Use for runtimes
  *                                  whose product branding differs from the
  *                                  internal id (C58: `kilo` → "Kilo Code").
+ * @property {string|null} nativeInstructionFile
+ *                                  The root-level instruction file this
+ *                                  runtime's native CLI reads (e.g. `claude`
+ *                                  reads `CLAUDE.md`, `codex` reads
+ *                                  `AGENTS.md`). `init` stamps the
+ *                                  `<!-- APT:framework-* -->` managed block
+ *                                  into every distinct non-null target for the
+ *                                  selected runtimes. `null` means the runtime
+ *                                  installs to its own surface (e.g. cursor →
+ *                                  `.cursor/rules`), NOT a root `.md` — `init`
+ *                                  skips null entries. Nullable by design, not
+ *                                  a future-work placeholder (ID-01).
  */
 
 /** @type {RuntimeDescriptor[]} */
@@ -46,6 +58,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.claude',
 		markers: ['.claude/settings.json', '.claude/settings.local.json'],
 		cliId: 'claude-code',
+		nativeInstructionFile: 'CLAUDE.md',
 	},
 	{
 		id: 'codex',
@@ -53,6 +66,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.agents',
 		markers: ['.codex/config.toml'],
 		cliId: 'codex',
+		nativeInstructionFile: 'AGENTS.md',
 	},
 	{
 		id: 'cursor',
@@ -60,6 +74,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.cursor',
 		markers: ['.cursor/settings.json'],
 		cliId: 'cursor',
+		nativeInstructionFile: null,
 	},
 	{
 		id: 'gemini',
@@ -67,6 +82,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.gemini',
 		markers: ['.gemini/settings.json'],
 		cliId: 'gemini-cli',
+		nativeInstructionFile: 'GEMINI.md',
 	},
 	{
 		id: 'opencode',
@@ -74,6 +90,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.opencode',
 		markers: ['.opencode/config.json'],
 		cliId: 'opencode',
+		nativeInstructionFile: 'AGENTS.md',
 	},
 	{
 		id: 'pi',
@@ -81,6 +98,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.pi',
 		markers: ['.pi/settings.json', '.pi/skills', '.pi/prompts'],
 		cliId: 'pi',
+		nativeInstructionFile: null,
 	},
 	{
 		id: 'kilo',
@@ -92,6 +110,7 @@ export const RUNTIMES = Object.freeze([
 		// migration per spec ID-01). `--kilocode` is also accepted as a
 		// deprecated alias of `--kilo` at the CLI flag parser layer.
 		displayLabel: 'Kilo Code',
+		nativeInstructionFile: null,
 	},
 	{
 		id: 'copilot',
@@ -99,6 +118,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.github/copilot',
 		markers: ['.github/copilot-instructions.md'],
 		cliId: 'copilot',
+		nativeInstructionFile: null,
 	},
 	{
 		id: 'antigravity',
@@ -106,6 +126,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.antigravity',
 		markers: ['.antigravity/config.json'],
 		cliId: 'antigravity',
+		nativeInstructionFile: null,
 	},
 	{
 		id: 'windsurf',
@@ -113,6 +134,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.windsurf',
 		markers: ['.windsurfrules'],
 		cliId: 'windsurf',
+		nativeInstructionFile: null,
 	},
 	{
 		id: 'augment',
@@ -120,6 +142,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.augment',
 		markers: ['.augment/config.json'],
 		cliId: 'augment',
+		nativeInstructionFile: null,
 	},
 	{
 		id: 'trae',
@@ -127,6 +150,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.trae',
 		markers: ['.trae/config.json'],
 		cliId: 'trae',
+		nativeInstructionFile: null,
 	},
 	{
 		id: 'qwen',
@@ -134,6 +158,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.qwen',
 		markers: ['.qwen/config.json'],
 		cliId: 'qwen',
+		nativeInstructionFile: null,
 	},
 	{
 		id: 'cline',
@@ -141,6 +166,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.cline',
 		markers: ['.cline/config.json'],
 		cliId: 'cline',
+		nativeInstructionFile: null,
 	},
 	{
 		id: 'codebuddy',
@@ -148,6 +174,7 @@ export const RUNTIMES = Object.freeze([
 		installRoot: '.codebuddy',
 		markers: ['.codebuddy/config.json'],
 		cliId: 'codebuddy',
+		nativeInstructionFile: null,
 	},
 ])