@aperant/framework 0.8.0 → 0.8.4

package/src/cli/install/legacy-paths.mjs

@@ -11,18 +11,28 @@
  *     pre-manifest install still surfaces as "installed" rather than
  *     "missing-skills".
  *
- * Derivation: the codex `framework_files` list was extracted from
- * `git show 1a8dd8a8 --stat` (the original "make Codex a first-class
- * skill install surface" commit) — every `.agents/skills/…` path the
- * installer once wrote, including the `.apt-version` stamp and the
- * apt-pr-review / apt-discuss / apt-verify-proof sub-files. When the
- * codex installer was retargeted to `.codex/`, that entire tree became
- * orphaned on upgrading projects.
+ * Codex evolution: v0.7/v0.8 retargeted the codex transform to write
+ * markdown skills under `.codex/agents/` + `.codex/commands/` (with the
+ * apt-file-manifest.json next to them). Codex CLI 0.132.0 does not
+ * discover skills at either path — its documented surface is
+ * `.agents/skills/<folder>/SKILL.md` (per
+ * https://developers.openai.com/codex/skills). The v0.8.2 fix inverts
+ * this registry: the dead `.codex/` markdown tree becomes the legacy
+ * target so `runLegacyCleanup` GCs it on the next `apt-tools init`.
  *
  * Schema:
  *   { [runtimeId]: {
  *       install_root:     relative path the runtime once wrote into,
- *       version_file:     relative path of the legacy `.apt-version` stamp,
+ *       version_file:     relative path of the legacy `.apt-version` stamp
+ *                         (or a path known to never exist, when no version
+ *                         stamp was ever written for the legacy topology),
+ *       honor_manifest:   when true (default), a present apt-file-manifest.json
+ *                         at install_root signals a managed install and the
+ *                         cleanup no-ops (`reason: 'managed'`). When false,
+ *                         the legacy root is known-dead so the manifest is
+ *                         removed alongside framework files (used for surfaces
+ *                         like the v0.7/v0.8 codex misdirect that will never
+ *                         again be a managed install root).
  *       framework_files:  array of relative paths the installer once owned
  *                         (under install_root).
  *   } }
@@ -30,40 +40,153 @@
  * Frozen via Object.freeze so callers cannot mutate the shared registry.
  */
 
-/** @type {Record<string, { install_root: string, version_file: string, framework_files: ReadonlyArray<string> }>} */
+/**
+ * @typedef {Object} LegacyInstallPath
+ * @property {string} install_root
+ * @property {string} version_file
+ * @property {boolean} [honor_manifest]  default true; false for known-dead surfaces
+ * @property {ReadonlyArray<string>} framework_files
+ */
+
+/** @type {Record<string, LegacyInstallPath>} */
 export const LEGACY_INSTALL_PATHS = Object.freeze({
 	codex: Object.freeze({
-		install_root: '.agents/skills',
-		version_file: '.agents/skills/.apt-version',
+		// The v0.7/v0.8 misdirect lived under `.codex/agents/` + `.codex/commands/`
+		// (with the orphan apt-file-manifest.json at `.codex/apt-file-manifest.json`).
+		// Codex CLI 0.132.0 does not consume any of those paths — see header.
+		install_root: '.codex',
+		// No `.apt-version` was ever written under `.codex/`; point at a path
+		// that doesn't exist so `existsSync` returns false in
+		// skill-installs.mjs:67-68 (legacy version_file fallback). The bare
+		// apt-file-manifest.json (handled by framework_files) is enough to
+		// signal the legacy install.
+		version_file: '.codex/.apt-version',
+		// Known-dead surface: this `.codex/` topology will never again be
+		// a managed Aperant install root, so a manifest sitting here is
+		// always stale. Skip the no-op-on-manifest safety and remove the
+		// manifest alongside framework_files. Default-true elsewhere
+		// preserves the safety for legacy roots that could legitimately
+		// re-host a managed install.
+		honor_manifest: false,
+		// Enumerated from BOTH canonical sources (drift-checked at test time
+		// by legacy-cleanup-codex.test.ts):
+		//   - For each `packages/framework/skills/apt-*/` directory: the v0.7/v0.8
+		//     transform emitted BOTH `agents/<dir>.md` AND `commands/<dir>.md`.
+		//   - For each top-level `packages/framework/skills/apt-*.md` file
+		//     (fileType=agent in the pipeline): the transform emitted
+		//     `agents/<basename>.md`.
+		//   - For each `packages/framework/agents/apt-*.md` file: the transform
+		//     emitted `agents/<basename>.md` (last-write-wins de-dupe applied
+		//     by the pipeline for overlapping outputs).
+		//   - Plus the orphan apt-file-manifest.json the install pipeline
+		//     stamps at install_root.
+		// TODO: follow-up — derive this programmatically per spec ID-06 so
+		// new apt-* skills auto-extend the legacy set without an edit here.
 		framework_files: Object.freeze([
-			'.apt-version',
-			'apt/SKILL.md',
-			'apt-debug/SKILL.md',
-			'apt-discuss/SKILL.md',
-			'apt-discuss/examples/rationalization-example.md',
-			'apt-docs/SKILL.md',
-			'apt-execute/SKILL.md',
-			'apt-pause/SKILL.md',
-			'apt-plan/SKILL.md',
-			'apt-pr-review/SCHEMA.md',
-			'apt-pr-review/SKILL.md',
-			'apt-pr-review/prompts/fp-gate-codex.md',
-			'apt-pr-review/templates/external-comment.md',
-			'apt-quick/SKILL.md',
-			'apt-resume/SKILL.md',
-			'apt-review/SKILL.md',
-			'apt-roadmap/SKILL.md',
-			'apt-roundtable/SKILL.md',
-			'apt-run/SKILL.md',
-			'apt-scan/SKILL.md',
-			'apt-setup/SKILL.md',
-			'apt-ship/SKILL.md',
-			'apt-stress-test/SKILL.md',
-			'apt-verify/SKILL.md',
-			'apt-verify-proof/SKILL.md',
-			'apt-verify-proof/references/multi-model-setup.md',
-			'apt-verify-proof/references/multi-model-verification.md',
-			'apt-verify-proof/references/proof-capture.md',
+			'apt-file-manifest.json',
+			// agents/<dir>.md — one per skill directory (39 dirs)
+			'agents/apt.md',
+			'agents/apt-author-skill.md',
+			'agents/apt-bootstrap.md',
+			'agents/apt-caveman.md',
+			'agents/apt-classify.md',
+			'agents/apt-close-task.md',
+			'agents/apt-create-docs.md',
+			'agents/apt-debug.md',
+			'agents/apt-design.md',
+			'agents/apt-diagram.md',
+			'agents/apt-discuss.md',
+			'agents/apt-docs.md',
+			'agents/apt-execute.md',
+			'agents/apt-fan-out.md',
+			'agents/apt-handoff.md',
+			'agents/apt-improve.md',
+			'agents/apt-mockup.md',
+			'agents/apt-pause.md',
+			'agents/apt-personas.md',
+			'agents/apt-plan.md',
+			'agents/apt-pr-review.md',
+			'agents/apt-prototype.md',
+			'agents/apt-quick.md',
+			'agents/apt-release-notes.md',
+			'agents/apt-resume.md',
+			'agents/apt-review.md',
+			'agents/apt-roadmap.md',
+			'agents/apt-roundtable.md',
+			'agents/apt-run.md',
+			'agents/apt-scan.md',
+			'agents/apt-setup.md',
+			'agents/apt-ship.md',
+			'agents/apt-spar.md',
+			'agents/apt-stress-test.md',
+			'agents/apt-terminal.md',
+			'agents/apt-triage.md',
+			'agents/apt-update.md',
+			'agents/apt-verify.md',
+			'agents/apt-verify-proof.md',
+			'agents/apt-watch-ci.md',
+			'agents/apt-zoom-out.md',
+			// commands/<dir>.md — one per skill directory (mirrors agents/)
+			'commands/apt.md',
+			'commands/apt-author-skill.md',
+			'commands/apt-bootstrap.md',
+			'commands/apt-caveman.md',
+			'commands/apt-classify.md',
+			'commands/apt-close-task.md',
+			'commands/apt-create-docs.md',
+			'commands/apt-debug.md',
+			'commands/apt-design.md',
+			'commands/apt-diagram.md',
+			'commands/apt-discuss.md',
+			'commands/apt-docs.md',
+			'commands/apt-execute.md',
+			'commands/apt-fan-out.md',
+			'commands/apt-handoff.md',
+			'commands/apt-improve.md',
+			'commands/apt-mockup.md',
+			'commands/apt-pause.md',
+			'commands/apt-personas.md',
+			'commands/apt-plan.md',
+			'commands/apt-pr-review.md',
+			'commands/apt-prototype.md',
+			'commands/apt-quick.md',
+			'commands/apt-release-notes.md',
+			'commands/apt-resume.md',
+			'commands/apt-review.md',
+			'commands/apt-roadmap.md',
+			'commands/apt-roundtable.md',
+			'commands/apt-run.md',
+			'commands/apt-scan.md',
+			'commands/apt-setup.md',
+			'commands/apt-ship.md',
+			'commands/apt-spar.md',
+			'commands/apt-stress-test.md',
+			'commands/apt-terminal.md',
+			'commands/apt-triage.md',
+			'commands/apt-update.md',
+			'commands/apt-verify.md',
+			'commands/apt-verify-proof.md',
+			'commands/apt-watch-ci.md',
+			'commands/apt-zoom-out.md',
+			// agents/<basename>.md — packages/framework/agents/apt-*.md (17 files)
+			// (overlap with skills/apt-*.md top-level — same outputPath, de-dupe)
+			'agents/apt-docs-author.md',
+			'agents/apt-executor.md',
+			'agents/apt-improver.md',
+			'agents/apt-planner.md',
+			'agents/apt-pr-review-codebase-fit.md',
+			'agents/apt-pr-review-fixer.md',
+			'agents/apt-pr-review-logic.md',
+			'agents/apt-pr-review-performance.md',
+			'agents/apt-pr-review-quality.md',
+			'agents/apt-pr-review-security.md',
+			'agents/apt-pr-review-self-reviewer.md',
+			'agents/apt-pr-review-test-integrity.md',
+			'agents/apt-pr-review-validator.md',
+			'agents/apt-researcher.md',
+			'agents/apt-reviewer.md',
+			'agents/apt-team-docs-narrator.md',
+			'agents/apt-verifier.md',
 		]),
 	}),
 })

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

@@ -30,9 +30,7 @@ import { MANIFEST_FILENAME } from './manifest.mjs'
  * @property {string|null} cliId    The `cli` string `detectHost()` returns
  *                                  when this runtime's CLI is at the prompt.
  *                                  `null` when the runtime has no install
- *                                  target mapped to a host CLI (e.g. `pi`,
- *                                  which has a detectable host but no apt
- *                                  install root of its own).
+ *                                  target mapped to a host CLI.
  * @property {string} [displayLabel] Optional user-facing label (e.g. "Kilo Code").
  *                                  When unset, callers fall back to the
  *                                  capitalized form of `id`. Use for runtimes
@@ -52,7 +50,7 @@ export const RUNTIMES = Object.freeze([
 	{
 		id: 'codex',
 		flag: '--codex',
-		installRoot: '.codex',
+		installRoot: '.agents',
 		markers: ['.codex/config.toml'],
 		cliId: 'codex',
 	},
@@ -77,6 +75,13 @@ export const RUNTIMES = Object.freeze([
 		markers: ['.opencode/config.json'],
 		cliId: 'opencode',
 	},
+	{
+		id: 'pi',
+		flag: '--pi',
+		installRoot: '.pi',
+		markers: ['.pi/settings.json', '.pi/skills', '.pi/prompts'],
+		cliId: 'pi',
+	},
 	{
 		id: 'kilo',
 		flag: '--kilo',

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

@@ -2,15 +2,14 @@
  * install/runtime-migrate.mjs — at-install cleanup of legacy install
  * trees the framework no longer owns (FRAMEWORK-BUG-021).
  *
- * Codex was originally installed into `.agents/skills/` (commit 1a8dd8a8)
- * and later moved to `.codex/`. Projects that upgraded across that move
- * end up with a stale `.agents/skills/` tree that:
- *
- *   - keeps `.apt-version` on disk → the legacy fallback in
- *     `readSkillInstallState` reports a stale codex install.
- *   - shows up in `health-check` as `stale-skills`.
- *   - leaves dozens of orphaned SKILL.md files the runtime no longer
- *     reads.
+ * Codex shuffled install roots twice:
+ *   - Pre-0.7: installed at `.agents/skills/` (commit 1a8dd8a8).
+ *   - v0.7/v0.8: moved to `.codex/agents/` + `.codex/commands/` — a
+ *     misdirect, since Codex CLI 0.132.0 doesn't discover skills there.
+ *   - v0.8.2 (this fix): moved back to `.agents/skills/<folder>/SKILL.md`
+ *     (Codex's documented surface). The v0.7/v0.8 `.codex/` markdown
+ *     tree is now the legacy target — `LEGACY_INSTALL_PATHS.codex` was
+ *     re-pointed accordingly.
  *
  * `runLegacyCleanup` runs once per `apt-tools init` when codex is in the
  * requested runtime set. It is conservative by default:
@@ -20,8 +19,11 @@
  *     preserved. If anything beyond the known framework set remains,
  *     `retained[]` lists those paths.
  *   - A present-and-current `apt-file-manifest.json` is treated as the
- *     authoritative "this is a managed install, leave it alone" signal:
- *     the function no-ops with `reason: 'managed'`.
+ *     authoritative "this is a managed install, leave it alone" signal
+ *     — but ONLY when the legacy entry has `honor_manifest: true` (the
+ *     default). When `honor_manifest: false` (the current codex entry,
+ *     because `.codex/` is known-dead), the manifest is removed alongside
+ *     framework files.
  *   - The caller can suppress cleanup entirely via `--keep-legacy` at the
  *     init.mjs site; the function itself is dumb about flags.
  */
@@ -33,7 +35,8 @@ import { MANIFEST_FILENAME } from './manifest.mjs'
 
 /**
  * @typedef {Object} LegacyCodexDetection
- * @property {boolean} present              True when `.agents/skills/` exists.
+ * @property {boolean} present              True when the legacy install_root
+ *                                          (currently `.codex/`) exists.
  * @property {string[]} frameworkFiles      Subset of `framework_files` that
  *                                          actually exist on disk (relative
  *                                          to install_root).
@@ -46,9 +49,15 @@ import { MANIFEST_FILENAME } from './manifest.mjs'
  *                                          stamp is present.
  * @property {boolean} hasManifest          Whether an
  *                                          `apt-file-manifest.json` is
- *                                          present at install_root (signals
- *                                          a managed install — cleanup
- *                                          should no-op).
+ *                                          present at install_root. When the
+ *                                          legacy entry has
+ *                                          `honor_manifest: true` (default)
+ *                                          this signals a managed install
+ *                                          and cleanup no-ops; when
+ *                                          `honor_manifest: false` the
+ *                                          manifest is treated as orphan
+ *                                          and removed alongside framework
+ *                                          files.
  */
 
 const LEGACY = LEGACY_INSTALL_PATHS.codex
@@ -93,7 +102,9 @@ function walkRelative(dir) {
 }
 
 /**
- * Probe the codex legacy install tree at `<targetDir>/.agents/skills/`.
+ * Probe the codex legacy install tree at `<targetDir>/<LEGACY.install_root>`
+ * (currently `.codex/` after the v0.8.2 registry inversion — the v0.7/v0.8
+ * misdirect topology).
  *
  * @param {string} targetDir
  * @returns {LegacyCodexDetection}
@@ -142,25 +153,36 @@ function rmEmptyDir(dir) {
 }
 
 /**
- * Clean up the legacy `.agents/skills/` tree if it looks orphaned.
+ * Clean up the legacy install tree at `<targetDir>/<LEGACY.install_root>`
+ * if it looks orphaned. Post v0.8.2 the codex legacy root is `.codex/`
+ * with framework files at `agents/<file>.md` + `commands/<file>.md` +
+ * `apt-file-manifest.json`.
  *
  * Branches:
  *   1. `present: false` OR `frameworkFiles.length === 0` → no-op,
  *      `{ ran: false, reason: 'no-legacy' }`.
- *   2. `hasManifest: true` → managed install, no-op,
- *      `{ ran: false, reason: 'managed' }`.
+ *   2. `hasManifest: true` AND `LEGACY.honor_manifest !== false`
+ *      (default true) → managed install, no-op,
+ *      `{ ran: false, reason: 'managed' }`. When `honor_manifest: false`
+ *      (known-dead surface like the v0.7/v0.8 codex misdirect) the
+ *      manifest is treated as orphan and removed alongside framework
+ *      files.
  *   3. Otherwise: per-file `unlinkSync` each framework-owned file;
- *      `rmdirSync` any now-empty `apt-*` subdirectory; sweep
- *      `.agents/skills/` only if it is empty; sweep `.agents/` only if
- *      its `skills/` got removed and `.agents/` is empty.
+ *      `rmdirSync` any subdirectory left empty after the unlinks (e.g.
+ *      `.codex/agents/`, `.codex/commands/`); sweep the install_root
+ *      itself only if it is fully empty after the per-file pass; sweep
+ *      the install_root's parent only if it too became empty (relevant
+ *      for legacy topologies two levels deep, e.g. the pre-0.7
+ *      `.agents/skills/` codex layout).
  *
  * Returns `{ ran: true, removed, retained, rmdirs }` on the cleanup
  * branch:
  *   - `removed`  — relative paths under `install_root` that were unlinked.
  *   - `retained` — relative paths under `install_root` that were NOT
- *     removed (user-added skills / files not in the legacy set).
- *   - `rmdirs`   — absolute paths of directories that were removed
- *     (apt-* subdirs, the install_root itself, .agents/), in removal order.
+ *     removed (user-added skills / files not in the legacy set, e.g.
+ *     `.codex/config.toml`).
+ *   - `rmdirs`   — absolute paths of directories that were removed,
+ *     in removal order.
  *
  * Atomicity: per-file unlink is non-atomic. A partial-failure scenario
  * (process killed mid-loop) is tolerable — the next `init` run will
@@ -178,7 +200,14 @@ export function runLegacyCleanup({ targetDir, dryRun = false }) {
 	if (!detection.present || detection.frameworkFiles.length === 0) {
 		return { ran: false, reason: 'no-legacy' }
 	}
-	if (detection.hasManifest) {
+	// `honor_manifest: false` means the legacy install_root is a known-dead
+	// surface (the v0.7/v0.8 codex misdirect). A manifest sitting there is
+	// by definition stale — fall through and remove it alongside framework
+	// files. `honor_manifest: true` (default) preserves the managed-install
+	// safety for legacy roots that could legitimately re-host a managed
+	// install.
+	const honorManifest = LEGACY.honor_manifest !== false
+	if (detection.hasManifest && honorManifest) {
 		return { ran: false, reason: 'managed' }
 	}
 
@@ -233,12 +262,16 @@ export function runLegacyCleanup({ targetDir, dryRun = false }) {
 		if (rmEmptyDir(abs)) rmdirs.push(abs)
 	}
 
-	// Sweep `.agents/skills/` only if fully empty after the per-file
-	// pass — preserves any user-added skill dirs.
+	// Sweep the legacy install_root only if fully empty after the per-file
+	// pass — preserves any user-added content under it (e.g. `.codex/config.toml`
+	// when LEGACY.install_root is `.codex/`).
 	if (rmEmptyDir(installRoot)) {
 		rmdirs.push(installRoot)
-		// Sweep `.agents/` only if it became empty too (i.e. no other
-		// `.agents/<sibling>` content the user keeps there).
+		// Sweep the install_root's parent only if it became empty too
+		// (relevant for legacy topologies whose install_root sits two
+		// levels deep, e.g. the pre-0.7 `.agents/skills/` codex layout).
+		// No-op when install_root is a top-level dir like `.codex/` —
+		// rmEmptyDir refuses to remove a non-empty project root.
 		const agentsRoot = dirname(installRoot)
 		if (rmEmptyDir(agentsRoot)) rmdirs.push(agentsRoot)
 	}

package/src/cli/install/transforms/codex.mjs

@@ -2,13 +2,18 @@
  * install/transforms/codex.mjs — Codex transform.
  *
  * Codex quirks:
- *   - frontmatter strips `tools` and `color` (Codex validates strictly and
- *     rejects unknown/style-only keys).
+ *   - frontmatter is whitelisted to `KEEP = {name, description}` (Codex
+ *     validates strictly against its `allowed_properties` set and rejects
+ *     unknown keys; the whitelist is drift-proof against new framework
+ *     frontmatter keys).
  *   - body is wrapped in <codex_agent_role>…</codex_agent_role>.
  *   - slash-command refs `/apt:foo` rewritten to `/apt-foo` (Codex command
  *     names disallow `:`).
- *   - output: .codex/agents/<name>.md AND .codex/commands/<name>.md (some
- *     skills register both as agent + invocable command).
+ *   - output: skills/<folder>/SKILL.md (the documented Codex discovery
+ *     surface per https://developers.openai.com/codex/skills — resolved
+ *     against installRoot `.agents` to land at `.agents/skills/<folder>/SKILL.md`).
+ *     Markdown agents are NOT a Codex surface (custom-agents are TOML
+ *     under `.codex/agents/`); only skills are emitted.
  */
 
 import { basename, dirname } from 'node:path'
@@ -16,11 +21,16 @@ import {
 	parseFrontmatter,
 	rewriteCommandRefs,
 	serializeFrontmatter,
-	stripFields,
 	substituteVersion,
 } from './_shared.mjs'
 
-const STRIP = ['tools', 'color']
+// Codex's `allowed_properties` set (see
+// ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py:40):
+// {"name", "description", "license", "allowed-tools", "metadata"}.
+// We use the minimum viable whitelist {name, description} so adding new
+// framework frontmatter keys (a routine occurrence) doesn't break Codex
+// validation — only the 2 keys Codex actually consumes are emitted.
+const KEEP = ['name', 'description']
 
 /**
  * @param {import('../pipeline.mjs').TransformInput} input
@@ -31,7 +41,10 @@ export function transform({ canonicalContent, canonicalRelPath, version, fileTyp
 	const parsed = parseFrontmatter(subbed)
 	let payload
 	if (parsed.hasFrontmatter && parsed.fm) {
-		stripFields(parsed.fm, STRIP)
+		// Whitelist filter: drop every frontmatter key NOT in KEEP.
+		for (const k of Object.keys(parsed.fm)) {
+			if (!KEEP.includes(k)) delete parsed.fm[k]
+		}
 		const wrappedBody = `<codex_agent_role>\n${parsed.body}\n</codex_agent_role>\n`
 		payload = serializeFrontmatter({ ...parsed, body: wrappedBody })
 	} else {
@@ -41,16 +54,12 @@ export function transform({ canonicalContent, canonicalRelPath, version, fileTyp
 
 	if (fileType === 'skill') {
 		const folder = basename(dirname(canonicalRelPath))
-		// Skills emit BOTH an agent definition (for invocation context) and a
-		// command (so the user can type `/apt-foo` directly in Codex).
-		return [
-			{ outputPath: `agents/${folder}.md`, content: payload },
-			{ outputPath: `commands/${folder}.md`, content: payload },
-		]
-	}
-	if (fileType === 'agent') {
-		const file = basename(canonicalRelPath, '.md')
-		return [{ outputPath: `agents/${file}.md`, content: payload }]
+		// Codex's documented skill discovery surface is `.agents/skills/<folder>/SKILL.md`
+		// (one folder per skill, canonical SKILL.md filename).
+		return [{ outputPath: `skills/${folder}/SKILL.md`, content: payload }]
 	}
+	// Markdown agents are not a Codex surface. Codex custom-agents are TOML
+	// under `.codex/agents/`; emitting markdown there would just create
+	// another dead surface. Drop the agent branch entirely.
 	return []
 }

package/src/cli/install/transforms/pi.mjs

@@ -0,0 +1,37 @@
+/**
+ * install/transforms/pi.mjs — Pi coding agent transform.
+ *
+ * Pi uses prompt templates under `.pi/prompts/` for slash commands and
+ * root-level skills under `.pi/skills/`. Unlike Codex, Pi supports
+ * colon-form prompt names, so `/apt:foo` references are preserved.
+ */
+
+import { basename, dirname } from 'node:path'
+import { substituteVersion } from './_shared.mjs'
+
+function promptNameForSkill(folder) {
+	if (folder === 'apt') return 'apt'
+	if (folder.startsWith('apt-')) return `apt:${folder.slice('apt-'.length)}`
+	return folder
+}
+
+/**
+ * @param {import('../pipeline.mjs').TransformInput} input
+ * @returns {import('../pipeline.mjs').TransformOutput[]}
+ */
+export function transform({ canonicalContent, canonicalRelPath, version, fileType }) {
+	const content = substituteVersion(canonicalContent, version)
+	if (fileType === 'skill') {
+		const folder = basename(dirname(canonicalRelPath))
+		const promptName = promptNameForSkill(folder)
+		return [
+			{ outputPath: `skills/${folder}/SKILL.md`, content },
+			{ outputPath: `prompts/${promptName}.md`, content },
+		]
+	}
+	if (fileType === 'agent') {
+		const file = basename(canonicalRelPath)
+		return [{ outputPath: `skills/${file}`, content }]
+	}
+	return []
+}

package/src/cli/skill-author/contract.mjs

@@ -164,9 +164,9 @@ export const SkillFrontmatterSchema = z
 		// don't immediately break skills that carry them.
 		triggers: z.array(z.string()).optional(),
 		color: z.string().optional(),
-		// Pocock adoption ST-13 (AC12): optional `produces:` field enumerates
+		// ST-13 (AC12): optional `produces:` field enumerates
 		// the content-formats a skill emits (e.g. "PRD-shaped spec.md",
-		// "vertical-slice subtasks", "Pocock-format CONTEXT.md term-block").
+		// "vertical-slice subtasks", "Aperant CONTEXT.md term-block").
 		// Consumed by `apt-tools modes list` to surface what each skill ships.
 		// Additive and backward-compatible — skills without the field default
 		// to [] in modes list output.

package/src/cli/verify-proof/audit.mjs

@@ -0,0 +1,55 @@
+/**
+ * audit.mjs — append-only JSONL audit log for driver invocations.
+ *
+ * ID-05: one file per day at .aperant/events/{YYYY-MM-DD}.jsonl.
+ * One line per driver invocation:
+ *   {ts, driver_id, version, manifest_sha256, trust_tier, sandbox_profile,
+ *    decision: "allow|deny|requires_approval",
+ *    result: "success|fail|skip"}
+ *
+ * Append-only — no rewrites. Each appendDriverEvent() opens the file in
+ * 'a' mode and writes a single line; concurrent agents may interleave
+ * lines but no line is ever overwritten.
+ */
+
+import { appendFileSync, mkdirSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+
+/**
+ * Compute today's events filename relative to projectDir.
+ * @param {string} projectDir
+ * @param {Date} [now]
+ * @returns {string}
+ */
+export function dailyEventsPath(projectDir, now = new Date()) {
+	const yyyy = now.getUTCFullYear()
+	const mm = String(now.getUTCMonth() + 1).padStart(2, '0')
+	const dd = String(now.getUTCDate()).padStart(2, '0')
+	return join(resolve(projectDir), '.aperant/events', `${yyyy}-${mm}-${dd}.jsonl`)
+}
+
+/**
+ * Append a driver-invocation audit line.
+ *
+ * @param {string} projectDir
+ * @param {Object} entry
+ * @param {string} entry.driver_id
+ * @param {string} entry.version
+ * @param {string} entry.manifest_sha256
+ * @param {string} entry.trust_tier
+ * @param {string} entry.sandbox_profile
+ * @param {'allow' | 'deny' | 'requires_approval'} entry.decision
+ * @param {'success' | 'fail' | 'skip'} entry.result
+ * @param {string} [entry.verb] — IDL verb invoked (optional metadata)
+ * @param {string} [entry.reason] — decision-rationale string (optional)
+ */
+export function appendDriverEvent(projectDir, entry) {
+	const path = dailyEventsPath(projectDir)
+	mkdirSync(dirname(path), { recursive: true })
+	const line = JSON.stringify({
+		ts: new Date().toISOString(),
+		kind: 'driver_invocation',
+		...entry,
+	})
+	appendFileSync(path, line + '\n', 'utf-8')
+}