@aperant/framework 0.6.2

package/src/cli/seeds/validate.mjs

@@ -0,0 +1,177 @@
+/**
+ * seeds/validate.mjs — mutual-consistency audit between seeds.json and the
+ * per-scope milestones.json files (C12, AC6).
+ *
+ * The `seed_id` field on a milestone and the milestone ref inside
+ * `seeds.json.seeds[].milestones[]` must agree. Drift is possible when:
+ *
+ *   - a user hand-edits milestones.json and sets/clears seed_id without
+ *     running `apt-tools seed assign/unassign`
+ *   - a partial-write failure leaves one side stale (extremely rare given the
+ *     atomic writers, but the audit makes it observable)
+ *
+ * validateSeeds is a PURE function: takes the seeds file and a map of
+ * `{ scope → roadmap }` and returns a structured drift report. The CLI wires
+ * I/O around it (see commands/seed.mjs `validate`).
+ */
+
+/**
+ * @typedef {{ id: string, milestones?: Array<{scope: string, milestone_id: string}> }} SeedRec
+ * @typedef {{ id: string, seed_id?: string | null, scope?: string }} MilestoneRec
+ * @typedef {{ milestones?: MilestoneRec[] }} RoadmapRec
+ */
+
+/**
+ * Inspect seeds ↔ milestones coherence.
+ *
+ * Drift categories:
+ *   - orphan-seed-ref:   seeds.json points at (scope, milestone_id) that
+ *                        does NOT exist in any loaded roadmap.
+ *   - missing-seed-id:   seeds.json lists (scope, milestone_id), but the
+ *                        milestone on disk has a null/missing seed_id.
+ *   - wrong-seed-id:     milestone on disk has seed_id=X, but seeds.json
+ *                        lists it under a different seed Y. (Or vice versa.)
+ *   - dangling-seed-id:  milestone has seed_id=X but X is not listed in any
+ *                        seed's milestones[] array (or X is not a known seed).
+ *   - duplicate-membership: same (scope, milestone_id) appears in >1 seed
+ *                        (seed membership is one-to-many — a milestone can
+ *                        belong to AT MOST one seed).
+ *
+ * Returns:
+ *   {
+ *     ok: boolean,         // true when drift.length === 0
+ *     drift: Array<{ kind, seed_id, scope, milestone_id, expected, actual }>
+ *   }
+ *
+ * @param {{seeds?: SeedRec[]} | null} seedsFile
+ * @param {Map<string, RoadmapRec | null> | Record<string, RoadmapRec | null>} roadmapsByScope
+ */
+export function validateSeeds(seedsFile, roadmapsByScope) {
+	const drift = []
+	const seeds = (seedsFile && Array.isArray(seedsFile.seeds) ? seedsFile.seeds : []) || []
+
+	// Normalize roadmapsByScope to a Map for uniform access.
+	const roadmaps =
+		roadmapsByScope instanceof Map
+			? roadmapsByScope
+			: new Map(Object.entries(roadmapsByScope || {}))
+
+	// Build (scope, milestone_id) → seed_id(s) membership map from seeds.json.
+	// Duplicate-membership drift is flagged when >1 seed references the same
+	// milestone.
+	const seedMembership = new Map() // key = `${scope}\u0000${milestone_id}` → Set<seed_id>
+	for (const seed of seeds) {
+		for (const ref of seed.milestones || []) {
+			if (!ref || !ref.scope || !ref.milestone_id) continue
+			const key = `${ref.scope}\u0000${ref.milestone_id}`
+			if (!seedMembership.has(key)) seedMembership.set(key, new Set())
+			seedMembership.get(key).add(seed.id)
+		}
+	}
+
+	// Pass 1: seeds → milestones. Every (scope, milestone_id) in seeds.json
+	// must resolve to a real milestone, and that milestone's seed_id must
+	// agree with the seed that claims it.
+	for (const seed of seeds) {
+		for (const ref of seed.milestones || []) {
+			if (!ref || !ref.scope || !ref.milestone_id) continue
+			const rm = roadmaps.get(ref.scope)
+			const m =
+				rm && Array.isArray(rm.milestones)
+					? rm.milestones.find((x) => x && x.id === ref.milestone_id)
+					: null
+			if (!m) {
+				drift.push({
+					kind: 'orphan-seed-ref',
+					seed_id: seed.id,
+					scope: ref.scope,
+					milestone_id: ref.milestone_id,
+					expected: `milestone "${ref.milestone_id}" in scope "${ref.scope}"`,
+					actual: 'milestone not found',
+				})
+				continue
+			}
+			const onDisk = m.seed_id ?? null
+			if (onDisk == null) {
+				drift.push({
+					kind: 'missing-seed-id',
+					seed_id: seed.id,
+					scope: ref.scope,
+					milestone_id: ref.milestone_id,
+					expected: seed.id,
+					actual: null,
+				})
+			} else if (onDisk !== seed.id) {
+				drift.push({
+					kind: 'wrong-seed-id',
+					seed_id: seed.id,
+					scope: ref.scope,
+					milestone_id: ref.milestone_id,
+					expected: seed.id,
+					actual: onDisk,
+				})
+			}
+		}
+	}
+
+	// Pass 2: milestones → seeds. Every milestone with a seed_id must be
+	// claimed by a seed (and exactly one seed).
+	const seedsById = new Map(seeds.map((s) => [s.id, s]))
+	for (const [scope, rm] of roadmaps.entries()) {
+		if (!rm || !Array.isArray(rm.milestones)) continue
+		for (const m of rm.milestones) {
+			if (!m || !m.id) continue
+			const sid = m.seed_id ?? null
+			if (sid == null) continue
+			const claimingSeed = seedsById.get(sid)
+			const key = `${scope}\u0000${m.id}`
+			const membership = seedMembership.get(key)
+			if (!claimingSeed) {
+				drift.push({
+					kind: 'dangling-seed-id',
+					seed_id: sid,
+					scope,
+					milestone_id: m.id,
+					expected: 'seed to exist',
+					actual: `unknown seed "${sid}"`,
+				})
+				continue
+			}
+			if (!membership || !membership.has(sid)) {
+				drift.push({
+					kind: 'dangling-seed-id',
+					seed_id: sid,
+					scope,
+					milestone_id: m.id,
+					expected: `${sid} to list this milestone in its milestones[]`,
+					actual: 'not listed',
+				})
+			}
+		}
+	}
+
+	// Pass 3: duplicate-membership — any key with >1 seed id is a violation.
+	for (const [key, set] of seedMembership.entries()) {
+		if (set.size > 1) {
+			const [scope, milestoneId] = key.split('\u0000')
+			drift.push({
+				kind: 'duplicate-membership',
+				seed_id: Array.from(set).sort().join(','),
+				scope,
+				milestone_id: milestoneId,
+				expected: '1 seed',
+				actual: `${set.size} seeds: ${Array.from(set).sort().join(', ')}`,
+			})
+		}
+	}
+
+	// Stable output order for deterministic test assertions.
+	drift.sort((a, b) => {
+		if (a.kind !== b.kind) return a.kind.localeCompare(b.kind)
+		if (a.seed_id !== b.seed_id) return String(a.seed_id).localeCompare(String(b.seed_id))
+		if (a.scope !== b.scope) return String(a.scope).localeCompare(String(b.scope))
+		return String(a.milestone_id).localeCompare(String(b.milestone_id))
+	})
+
+	return { ok: drift.length === 0, drift }
+}

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

@@ -0,0 +1,183 @@
+/**
+ * skill-author/contract.mjs — C4 canonical SKILL.md contract.
+ *
+ * Single source of truth for what a valid Aperant skill's SKILL.md looks like.
+ * Every other module in src/cli/skill-author/ reads these constants and schemas
+ * rather than re-encoding the rules, so the contract is pinned in exactly one
+ * place.
+ *
+ * router-0.3.0 (2026-04-22): extended SkillFrontmatterSchema to enforce the
+ * fat-frontmatter shape (stage, intent, when_to_use, user_invocable, internal,
+ * spawns_agent, agent_name, allowed-tools, argument-hint, gates,
+ * default_execution_mode, execution_modes). Mirrors
+ * packages/framework/schemas/skill-frontmatter.json one-to-one. Both exist
+ * because: the JSON Schema is the ship-ready contract shipped alongside the
+ * package (referenced by docs + third-party tooling), while the Zod schema
+ * is the runtime enforcement used by the CLI. Drift between the two is
+ * covered by a test — see skill-frontmatter-schema.test.ts.
+ *
+ * Scope: v1 of the `author-skill` pipeline only covered NEW skills authored
+ * via `apt-tools author-skill`. Starting in router-0.3.0, every shipping
+ * `packages/framework/skills/apt-(slug)/SKILL.md` MUST pass
+ * SkillFrontmatterSchema; that cutover is enforced by
+ * skill-frontmatter-schema.test.ts.
+ */
+
+import { z } from 'zod'
+
+// The frontmatter `name` field is either the bare router entry "apt" OR
+// "apt:<kebab-case-slug>". Every downstream skill uses the slug form; the
+// router's own SKILL.md is the only "apt" entry.
+export const SKILL_NAME_REGEX = /^apt(?::[a-z][a-z0-9-]*)?$/
+
+/**
+ * Custom `x-*` intent prefix — for vertical-specific intents that haven't
+ * graduated to the core enum yet. See packages/framework/docs/intents.md
+ * for the promotion path (3 shipping skills using an intent → PR to core).
+ */
+export const CUSTOM_INTENT_REGEX = /^x-[a-z][a-z0-9-]*$/
+
+/**
+ * Central core-intent taxonomy. Closed set — new intents enter this array
+ * only via the promotion path documented in docs/intents.md. See D-06 in
+ * .aperant/context/notes/router-llm-first-redesign.md for the decision.
+ */
+export const CORE_INTENTS = Object.freeze([
+	'implement',
+	'capture',
+	'discuss',
+	'investigate',
+	'design',
+	'ship',
+	'configure',
+	'debug',
+])
+
+/**
+ * Lifecycle stages a skill can declare as its primary phase. Closed enum.
+ */
+export const STAGES = Object.freeze([
+	'plan',
+	'execute',
+	'verify',
+	'review',
+	'ship',
+	'discuss',
+	'debug',
+	'design',
+	'scan',
+	'quick',
+	'setup',
+	'resume',
+	'pause',
+	'ops',
+])
+
+/**
+ * Execution modes an autonomy run can be in. Shared with
+ * `packages/framework/src/cli/task/execution-mode.mjs` — kept in sync by
+ * a structural test (ensures the two lists never drift).
+ */
+export const EXECUTION_MODES = Object.freeze(['auto', 'step', 'plan-mode', 'plan-only', 'research'])
+
+/**
+ * Required XML-style section tags that MUST appear (opening + closing) in the
+ * SKILL.md body. Order is not enforced — authors can lay out the sections
+ * however they like as long as each tag pair is present.
+ */
+export const REQUIRED_SECTIONS = Object.freeze([
+	'<objective>',
+	'<your_environment>',
+	'<state_files>',
+	'<process>',
+])
+
+/**
+ * Soft-required tags — missing these emits a warning rather than an error.
+ * Encouraged by C1 (rationalization tables) and the autonomy model, but not
+ * strictly required since some skills are pure informational loops.
+ */
+export const SOFT_REQUIRED_SECTIONS = Object.freeze(['<rationalization>', '<autonomy_interaction>'])
+
+function isValidIntent(val) {
+	if (typeof val !== 'string') return false
+	if (CORE_INTENTS.includes(val)) return true
+	return CUSTOM_INTENT_REGEX.test(val)
+}
+
+const IntentSchema = z.string().refine(isValidIntent, {
+	message: `intent must be one of ${CORE_INTENTS.join('|')} OR match ${CUSTOM_INTENT_REGEX} (custom x- prefixed intent)`,
+})
+
+const StageSchema = z.enum([...STAGES])
+const ExecutionModeSchema = z.enum([...EXECUTION_MODES])
+
+/**
+ * Zod schema for the YAML frontmatter block at the top of every SKILL.md.
+ *
+ * Strict mode is intentionally NOT used: skills carry vendor-specific keys
+ * (triggers, color, apt-skill-version) and future extensions should be
+ * additive without breaking the contract. We enforce the fat-frontmatter
+ * keys below plus pass-through everything else.
+ */
+export const SkillFrontmatterSchema = z
+	.object({
+		name: z.string().regex(SKILL_NAME_REGEX, {
+			message: `frontmatter \`name\` must match ${SKILL_NAME_REGEX} (e.g. apt:foo, apt:author-skill)`,
+		}),
+		description: z.string().min(1, 'frontmatter `description` must be a non-empty string'),
+		stage: StageSchema,
+		intent: IntentSchema,
+		when_to_use: z.string().min(1, 'frontmatter `when_to_use` must be a non-empty sentence'),
+		user_invocable: z.boolean(),
+		internal: z.boolean(),
+		spawns_agent: z.boolean(),
+		agent_name: z.union([z.string().min(1), z.null()]),
+		'allowed-tools': z.string(),
+		'argument-hint': z.string(),
+		gates: z.array(z.string()),
+		default_execution_mode: ExecutionModeSchema,
+		execution_modes: z.array(ExecutionModeSchema).min(1),
+		// Legacy / optional pass-throughs — kept as opt-in so migrations
+		// don't immediately break skills that carry them.
+		triggers: z.array(z.string()).optional(),
+		color: z.string().optional(),
+		// Canonical SKILL.md files carry `apt-skill-version: {{APT_VERSION}}`,
+		// which YAML parses as a flow mapping (an object). The install
+		// pipeline rewrites this to a plain version string at transform
+		// time. Both shapes must validate — that's why we accept
+		// `string | object` rather than just `string`.
+		'apt-skill-version': z.union([z.string(), z.object({}).passthrough()]).optional(),
+		'user-invocable': z.boolean().optional(),
+	})
+	.passthrough()
+	.superRefine((data, ctx) => {
+		if (data.spawns_agent === true && (data.agent_name === null || data.agent_name === undefined)) {
+			ctx.addIssue({
+				code: z.ZodIssueCode.custom,
+				message: 'agent_name is required (non-null) when spawns_agent=true',
+				path: ['agent_name'],
+			})
+		}
+		if (
+			Array.isArray(data.execution_modes) &&
+			typeof data.default_execution_mode === 'string' &&
+			!data.execution_modes.includes(data.default_execution_mode)
+		) {
+			ctx.addIssue({
+				code: z.ZodIssueCode.custom,
+				message: `execution_modes must contain default_execution_mode ("${data.default_execution_mode}")`,
+				path: ['execution_modes'],
+			})
+		}
+	})
+
+/**
+ * Validate a parsed frontmatter object against the schema.
+ *
+ * @param {unknown} data — parsed YAML frontmatter
+ * @returns {import('zod').SafeParseReturnType<unknown, z.infer<typeof SkillFrontmatterSchema>>}
+ */
+export function validateFrontmatter(data) {
+	return SkillFrontmatterSchema.safeParse(data)
+}

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

@@ -0,0 +1,80 @@
+/**
+ * skill-author/scaffold.mjs — C4 scaffold generator.
+ *
+ * Given a skill name + description and the framework root, writes:
+ *   - packages/framework/skills/apt-{name}/SKILL.md
+ *   - packages/framework/src/__tests__/apt-{name}-skill-structure.test.ts
+ *
+ * Aborts (throws) if either target already exists — this is a one-shot tool
+ * and v1 has no overwrite mode. Use --dry-run to preview the write targets
+ * without touching disk.
+ *
+ * Pure Node; no apt-tools I/O conventions (no output() / no fail()) so the
+ * helper can be unit-tested in isolation.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { SKILL_NAME_REGEX } from './contract.mjs'
+import { renderSkillStub } from './skill-template.mjs'
+import { renderStructuralTest } from './test-template.mjs'
+
+// The CLI passes a slug WITHOUT the `apt:` prefix. The SKILL_NAME_REGEX
+// checks the full `apt:<slug>` form — we reuse it by prepending `apt:`.
+const SLUG_REGEX = /^[a-z][a-z0-9-]*$/
+
+/**
+ * @param {{
+ *   name: string,
+ *   description: string,
+ *   frameworkRoot: string,
+ *   dryRun?: boolean,
+ * }} opts
+ * @returns {{ skillPath: string, testPath: string, files: string[], dryRun: boolean }}
+ */
+export function scaffoldSkill({ name, description, frameworkRoot, dryRun = false }) {
+	if (typeof name !== 'string' || name.length === 0) {
+		throw new Error('scaffoldSkill: name is required')
+	}
+	if (!SLUG_REGEX.test(name)) {
+		throw new Error(
+			`scaffoldSkill: name "${name}" is not a valid slug — must match ${SLUG_REGEX} (and resolve to ${SKILL_NAME_REGEX} after the apt: prefix)`,
+		)
+	}
+	if (typeof description !== 'string' || description.length === 0) {
+		throw new Error('scaffoldSkill: description is required')
+	}
+	if (typeof frameworkRoot !== 'string' || frameworkRoot.length === 0) {
+		throw new Error('scaffoldSkill: frameworkRoot is required')
+	}
+
+	const skillDir = join(frameworkRoot, 'skills', `apt-${name}`)
+	const skillPath = join(skillDir, 'SKILL.md')
+	const testPath = join(frameworkRoot, 'src', '__tests__', `apt-${name}-skill-structure.test.ts`)
+
+	if (existsSync(skillDir)) {
+		throw new Error(`scaffoldSkill: skill directory already exists: ${skillDir}`)
+	}
+	if (existsSync(testPath)) {
+		throw new Error(`scaffoldSkill: structural test file already exists: ${testPath}`)
+	}
+
+	const skillContent = renderSkillStub({ name, description })
+	const testContent = renderStructuralTest({ name })
+
+	if (!dryRun) {
+		mkdirSync(skillDir, { recursive: true })
+		writeFileSync(skillPath, skillContent, 'utf-8')
+		// src/__tests__ must already exist (it's the canonical test dir) but be
+		// defensive for unusual framework roots used by tests.
+		mkdirSync(join(frameworkRoot, 'src', '__tests__'), { recursive: true })
+		writeFileSync(testPath, testContent, 'utf-8')
+	}
+
+	return {
+		skillPath,
+		testPath,
+		files: [skillPath, testPath],
+		dryRun,
+	}
+}

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

@@ -0,0 +1,91 @@
+/**
+ * skill-author/skill-template.mjs — C4 SKILL.md stub renderer.
+ *
+ * Pure function. Returns a SKILL.md string with all REQUIRED_SECTIONS
+ * (and the two SOFT_REQUIRED_SECTIONS) pre-populated as TODO stubs.
+ * The generated file is structurally valid — it passes the validator —
+ * but semantically empty. The author fills in the TODOs.
+ */
+
+/**
+ * @param {{ name: string, description: string }} opts
+ *   - name: the kebab slug AFTER `apt:` (e.g. "foo", "author-skill")
+ *   - description: short skill description
+ * @returns {string} full SKILL.md contents
+ */
+export function renderSkillStub({ name, description }) {
+	const fullName = `apt:${name}`
+	return `---
+name: ${fullName}
+description: ${description}
+stage: execute
+intent: implement
+when_to_use: "TODO: one-sentence trigger heuristic for the host LLM."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+allowed-tools: "Read, Grep, Glob"
+argument-hint: "${fullName} [args]"
+gates: []
+default_execution_mode: auto
+execution_modes:
+  - auto
+  - step
+triggers:
+  - /${fullName}
+  - ${fullName}
+---
+<objective>
+TODO: one-paragraph statement of what this skill does and when to use it.
+</objective>
+
+<your_environment>
+- **Working directory:** The project root (where you were invoked)
+- **apt-tools path:** \`node packages/framework/bin/apt-tools.mjs\`
+- **Constitution:** Read \`AGENTS.md\` in the project root if it exists
+- TODO: list every file/env var this skill reads
+</your_environment>
+
+<state_files>
+## State Files
+
+**Reads:**
+- TODO: list every file this skill reads
+
+**Writes:**
+- TODO: list every file this skill writes (including transient artifacts)
+</state_files>
+
+<rationalization>
+TODO: for each "I'll skip X because Y" pattern an agent might rationalize,
+document why skipping is wrong. See packages/framework/skills/apt-discuss/
+examples/rationalization-example.md for the pattern.
+</rationalization>
+
+<autonomy_interaction>
+TODO: describe how this skill respects the autonomy level in .aperant/config.json.
+At autonomy 0 (plan-only) the skill should not mutate files; at autonomy 1 it
+asks before destructive actions; at autonomy 2 it runs fully automatic.
+</autonomy_interaction>
+
+<process>
+
+## 1. Load Context
+
+TODO: what does the skill read before it does anything? AGENTS.md,
+.aperant/standards/*.md, task-dir artifacts, $ARGUMENTS?
+
+## 2. Do The Work
+
+TODO: the core behavior. Concrete steps — not "think about X", but
+"read file Y, apply transform Z, write file W".
+
+## 3. Report and What's Next
+
+TODO: what does the skill print on success? What's the recommended
+next step the user should invoke?
+
+</process>
+`
+}

package/src/cli/skill-author/test-template.mjs

@@ -0,0 +1,56 @@
+/**
+ * skill-author/test-template.mjs — C4 structural-test renderer.
+ *
+ * Pure function. Returns the TypeScript source of a per-skill structural test
+ * file mirroring packages/framework/src/__tests__/apt-design-skill-structure.test.ts.
+ *
+ * The generated test is intentionally minimal: it pins the contract basics
+ * (frontmatter name, four required section tags) so the skill immediately has
+ * a drift-detector after scaffold. Authors can extend the generated test with
+ * skill-specific assertions once the SKILL.md body is fleshed out.
+ */
+
+/**
+ * @param {{ name: string }} opts — name is the kebab slug AFTER `apt:`
+ * @returns {string} TypeScript source
+ */
+export function renderStructuralTest({ name }) {
+	const fullName = `apt:${name}`
+	const skillDir = `apt-${name}`
+	const describeTitle = `${fullName} SKILL.md structure`
+	return `/**
+ * apt-${name}-skill-structure.test.ts — structural test for the ${fullName} skill.
+ *
+ * Generated by \`apt-tools author-skill ${name}\`. Pins the canonical SKILL.md
+ * contract (C4) at author-time: frontmatter name + the four required section
+ * tags. Extend with skill-specific assertions as the SKILL.md body is filled in.
+ */
+
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+// __dirname = packages/framework/src/__tests__ → ../.. = packages/framework
+const FRAMEWORK_ROOT = resolve(__dirname, '..', '..')
+const SKILL_PATH = resolve(FRAMEWORK_ROOT, 'skills/${skillDir}/SKILL.md')
+
+describe('${describeTitle}', () => {
+	it('exists and has the expected frontmatter name', () => {
+		const contents = readFileSync(SKILL_PATH, 'utf-8')
+		expect(contents).toMatch(/^---\\n[\\s\\S]*?name:\\s*${fullName}/m)
+	})
+
+	it('contains <objective>, <your_environment>, <state_files>, <process> sections', () => {
+		const contents = readFileSync(SKILL_PATH, 'utf-8')
+		expect(contents).toContain('<objective>')
+		expect(contents).toContain('</objective>')
+		expect(contents).toContain('<your_environment>')
+		expect(contents).toContain('</your_environment>')
+		expect(contents).toContain('<state_files>')
+		expect(contents).toContain('</state_files>')
+		expect(contents).toContain('<process>')
+		expect(contents).toContain('</process>')
+	})
+})
+`
+}