@aperant/framework 0.6.2 → 0.6.4

package/skills/apt-ship/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: require-existing
 default_execution_mode: auto
 execution_modes:
   - auto
@@ -288,6 +289,8 @@ Capture the PR URL from the output into `pr_url` (for example, the last line of
 node packages/framework/bin/apt-tools.mjs task update . --id {task-id} --pr-url {PR_URL}
 ```
 
+This same call **atomically flips `lifecycle_phase` from `reviewing` to `shipped-pending-merge`** when the task is in `reviewing` and no explicit `--lifecycle-phase` flag is passed. Section 6 is now the single load-bearing step that both records the PR and transitions the lifecycle; Section 8 below documents the semantics but no longer issues a separate command.
+
 Display the resolution so users see which branch/base was used:
 
 ```
@@ -338,7 +341,7 @@ suggest_mode=$(jq -r '.pr_review.suggest_after_ship // "always"' .aperant/config
   ```
   [APT:ship] Run /apt:pr-review --pr {pr_number} now for deep multi-agent review? [Y/n]
   ```
-  On `Y` (or empty enter), invoke `/apt:pr-review --pr {pr_number}` inline after Section 8 flips the task to `shipped-pending-merge` — do NOT block the lifecycle transition. On `N` or any other response, proceed silently to Section 8.
+  On `Y` (or empty enter), invoke `/apt:pr-review --pr {pr_number}` inline — the task has already been flipped to `shipped-pending-merge` atomically by the `--pr-url` recording in Section 6, so the deep-review hint does NOT need to block on Section 8. On `N` or any other response, proceed silently to Section 8.
 
 - **`never`** — silent. Proceed directly to Section 8.
 
@@ -346,11 +349,9 @@ suggest_mode=$(jq -r '.pr_review.suggest_after_ship // "always"' .aperant/config
 
 ## 8. Transition lifecycle to `shipped-pending-merge` (C56 B5)
 
-Ship is NOT the final closer. The PR has just been opened — it won't merge for minutes, hours, or days, and no agent will be present on merge. Instead of closing the task now, flip its lifecycle to `shipped-pending-merge` — the intermediate state between `reviewing` and `completed`. `/apt:close-task` runs post-merge (either manually via `/apt:close-task --all` or by the user when they return to the repo) and performs the actual closeout: phase flip, documentation narration, worktree GC, per-PR config strip, task archive.
+Ship is NOT the final closer. The PR has just been opened — it won't merge for minutes, hours, or days, and no agent will be present on merge. The task lifecycle is now `shipped-pending-merge` — the intermediate state between `reviewing` and `completed`. `/apt:close-task` runs post-merge (either manually via `/apt:close-task --all` or by the user when they return to the repo) and performs the actual closeout: phase flip, documentation narration, worktree GC, per-PR config strip, task archive.
 
-```bash
-node packages/framework/bin/apt-tools.mjs task update . --id {task-id} --lifecycle-phase shipped-pending-merge
-```
+Section 6 already performed this transition atomically as part of `task update --pr-url`. This section documents the semantics; no separate command is required.
 
 The task stays in `state.active_tasks[*]` with `lifecycle_phase: "shipped-pending-merge"`. Do NOT call `task close` here — that would mark it `completed` before the PR is actually merged, producing the same artifact drift C56 was built to eliminate.
 

package/skills/apt-stress-test/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: require-existing
 default_execution_mode: step
 execution_modes:
   - auto

package/skills/apt-terminal/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: none
 default_execution_mode: step
 execution_modes:
   - auto

package/skills/apt-update/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: none
 default_execution_mode: auto
 execution_modes:
   - auto
@@ -69,6 +70,8 @@ Build the flags list from the runtime ids (e.g. `--claude --codex`) and run:
 node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs init . <flags>
 ```
 
+**Do NOT add `--yes`, `--solo`, `--team`, or any other Class A flag.** This command is meant to refresh runtime files only — adding `--yes` triggers a config schema migration that can silently flip `share.visibility` to `solo` and re-write `.gitignore`, which is exactly the 0.6.0/0.6.1 dogfood bug. If `init` returns a `requires_input` envelope (schema drift), surface it to the user verbatim and stop; let them decide team vs solo with the explicit flag. From 0.6.4 onward `--yes` infers visibility from existing git tracking, but the skill must still not add it — keep this command scoped to runtime refresh.
+
 Parse the init JSON. Capture for each runtime:
 - `install_root` (shortened to the basename, e.g. `.claude`)
 - `file_count`

package/skills/apt-verify/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: true
 agent_name: "apt-verifier"
+task_context: require-existing
 default_execution_mode: auto
 execution_modes:
   - auto

package/skills/apt-verify-proof/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: require-existing
 default_execution_mode: auto
 execution_modes:
   - auto

package/src/cli/artifacts/classification.mjs

@@ -174,6 +174,11 @@ const RULES = Object.freeze([
 		class: ARTIFACT_CLASS.EPHEMERAL,
 		why: 'Append-only daily log of lifecycle transitions.',
 	},
+	{
+		pattern: '.aperant/install/**',
+		class: ARTIFACT_CLASS.EPHEMERAL,
+		why: 'Install telemetry/summaries (last-init/last-install) — runtime artifacts.',
+	},
 	{
 		pattern: '.aperant/team-status/**',
 		class: ARTIFACT_CLASS.EPHEMERAL,
@@ -249,6 +254,11 @@ const RULES = Object.freeze([
 		class: ARTIFACT_CLASS.EPHEMERAL,
 		why: 'Design-scan outputs (tokens, extracted repo, synthesis) — rebuildable.',
 	},
+	{
+		pattern: '.aperant/product-context.json',
+		class: ARTIFACT_CLASS.EPHEMERAL,
+		why: 'Derived/read-through sidecar used by CLI flows; rebuilt from onboarding context.',
+	},
 	// ── Explicit ephemeral: secrets/tokens MUST never classify committable ─
 	{
 		pattern: '.aperant/secrets/**',

package/src/cli/commands/init.mjs

@@ -15,6 +15,7 @@
  * half is replaced.
  */
 
+import { execSync } from 'node:child_process'
 import {
 	copyFileSync,
 	existsSync,
@@ -222,6 +223,51 @@ function buildRerunWithHint(projectDir, parsedFlags, requiresExplicit) {
 	return `apt-tools init ${projectDir} ${flags.join(' ')}`.trim()
 }
 
+/**
+ * Infer `share.visibility` from the target's git tracking state.
+ *
+ * Repos that already track files inside `.aperant/` or any runtime root
+ * (`.claude/`, `.codex/`, …) are *behaviourally* team-mode: contributors
+ * pull the framework's installed files via git, not via local
+ * `apt-tools init`. Treating them as solo on an upgrade (the old `--yes`
+ * default did exactly this — bumped the schema, silently wrote
+ * `visibility: 'solo'`, and the project-gitignore allow-list flipped)
+ * is a destructive, non-obvious surprise. The 0.6.0/0.6.1 dogfood
+ * incidents both hit this rake.
+ *
+ * Returns:
+ *   - `'team'` when any tracked file lives under `.aperant/` or a runtime
+ *     root.
+ *   - `'solo'` when the dir is a git repo but no such tracked file
+ *     exists.
+ *   - `undefined` when the target isn't a git repo (caller falls back to
+ *     the descriptor default, which preserves greenfield behaviour).
+ *
+ * @param {string} targetDir
+ * @returns {'team'|'solo'|undefined}
+ */
+function inferVisibilityFromGit(targetDir) {
+	try {
+		execSync('git rev-parse --is-inside-work-tree 2>/dev/null', {
+			cwd: targetDir,
+			stdio: ['ignore', 'ignore', 'ignore'],
+		})
+	} catch {
+		return undefined
+	}
+	const probePaths = ['.aperant', ...RUNTIMES.map((r) => r.installRoot)]
+	try {
+		const out = execSync(`git ls-files -- ${probePaths.map((p) => `'${p}'`).join(' ')}`, {
+			cwd: targetDir,
+			encoding: 'utf8',
+			stdio: ['ignore', 'pipe', 'ignore'],
+		}).trim()
+		return out.length > 0 ? 'team' : 'solo'
+	} catch {
+		return 'solo'
+	}
+}
+
 /**
  * Apply Class A defaults that were collapsed under --yes /
  * --accept-new-defaults back into the migrated config so finishInit
@@ -243,21 +289,36 @@ function buildRerunWithHint(projectDir, parsedFlags, requiresExplicit) {
  * writes — keeps the prototype-pollution guard and dot-path semantics in
  * one place.
  *
+ * `overrides` lets callers substitute the descriptor default for a
+ * specific shortKey — used in the upgrade path to honour
+ * `inferVisibilityFromGit`, so a team repo that ran `--yes` doesn't get
+ * silently flipped to solo.
+ *
  * @param {{ migrated: Record<string, unknown>, applied_defaults: Array<{ key: string, value: unknown, why: string, source?: string }> }} migration
  * @param {Array<{ key: string, why: string, default?: unknown }>} collapsedEntries
  * @param {string} source              `--yes` or `--accept-new-defaults`.
  * @param {unknown} templateVersion    Template's version, applied to migrated.
+ * @param {Record<string, unknown>} [overrides]  shortKey → inferred value.
  */
-function applyCollapsedClassAToMigration(migration, collapsedEntries, source, templateVersion) {
+function applyCollapsedClassAToMigration(
+	migration,
+	collapsedEntries,
+	source,
+	templateVersion,
+	overrides = {},
+) {
 	for (const r of collapsedEntries) {
 		const desc = findClassDescriptor(r.key)
 		if (!desc) continue
-		setAt(migration.migrated, desc.key, desc.default)
+		const hasOverride = Object.hasOwn(overrides, desc.shortKey)
+		const value = hasOverride ? overrides[desc.shortKey] : desc.default
+		const recordedSource = hasOverride ? `${source} (inferred from git tracking)` : source
+		setAt(migration.migrated, desc.key, value)
 		migration.applied_defaults.push({
 			key: desc.shortKey,
-			value: desc.default,
+			value,
 			why: r.why,
-			source,
+			source: recordedSource,
 		})
 	}
 	if (templateVersion !== undefined) {
@@ -318,7 +379,24 @@ function nonInteractiveAnswers(targetDir, canonicalRoot, archetype, parsedFlags)
 		// solo-mode — re-introducing the 0.6.0 dogfood bug.
 		let requires = migration.requires_explicit
 		if (parsedFlags.yes && requires.length > 0) {
-			applyCollapsedClassAToMigration(migration, requires, '--yes', templateConfig.version)
+			// Prefer evidence over descriptor defaults: a repo that already
+			// tracks `.aperant/` or any runtime root is team-mode by
+			// behaviour. Without this, `--yes` flips long-tracked repos to
+			// solo on the v3→v4 schema bump (0.6.0/0.6.1 dogfood incidents).
+			// Explicit --solo/--team in parsedFlags wins; only collapse-time
+			// inference runs here.
+			const overrides = {}
+			if (!parsedFlags.visibility && requires.some((r) => r.key === 'visibility')) {
+				const inferred = inferVisibilityFromGit(targetDir)
+				if (inferred !== undefined) overrides.visibility = inferred
+			}
+			applyCollapsedClassAToMigration(
+				migration,
+				requires,
+				'--yes',
+				templateConfig.version,
+				overrides,
+			)
 			requires = []
 		} else if (parsedFlags.accept_new_defaults && requires.length > 0) {
 			// --accept-new-defaults applies template defaults for new Class A

package/src/cli/commands/pr-review-audit-fixer.mjs

@@ -117,7 +117,8 @@ function extractTopLevelSection(markdown, heading) {
 }
 
 /**
- * Parse a fixes-applied.md produced by apt-pr-review-fixer. Returns
+ * Parse a fixes-applied.md produced by apt-pr-review-fixer OR a
+ * self-review.md produced by apt-pr-review-self-reviewer. Returns
  * `{ fixes: Array<{id, title, file, verification}>, skipped: Array<{id}>, exists: true }`.
  * Non-existent or empty report returns `{ exists: false, fixes: [], skipped: [] }`.
  *
@@ -125,24 +126,57 @@ function extractTopLevelSection(markdown, heading) {
  * `### <id>` block. We strip any trailing `(created)` / `(modify)` etc
  * annotation the fixer template shows as free-form text so the intersect
  * step can match against `git diff --name-only` output cleanly.
+ *
+ * Dual-schema support (PR #95 Defect 2):
+ *  - Fixer reports use `## Fixes Applied` with `### <ID> — title` headers
+ *    (e.g. `### QUA-001 — title`). Real finding ids carry through.
+ *  - Self-reviewer reports use `## Fixes Applied by Self-Reviewer` with
+ *    `### Fix N: description` headers. These have no real finding id, so
+ *    we synthesize `self-reviewer-fix-${N}` to satisfy the
+ *    `report.fixes.length > 0` guard in decideVerdict rule 3 while
+ *    letting the diff-intersect step (the real check) decide the verdict.
+ *
+ * The two heading texts are disjoint — fixers emit one, self-reviewers
+ * emit the other. If both somehow appear in the same file (not expected
+ * in practice), both are parsed and fixer entries come first.
  */
 export function parseFixesAppliedMarkdown(md) {
 	if (!md || typeof md !== 'string' || !md.trim()) {
-		return { exists: false, fixes: [], skipped: [] }
+		return { exists: false, fixes: [], skipped: [], schema: 'fixer' }
 	}
 	const fixesSection = extractTopLevelSection(md, 'Fixes Applied')
+	const selfReviewerSection = extractTopLevelSection(md, 'Fixes Applied by Self-Reviewer')
 	const skippedSection = extractTopLevelSection(md, 'Skipped')
-	const fixes = parseFixEntries(fixesSection)
+	const fixes = [
+		...parseFixEntries(fixesSection),
+		...parseSelfReviewerFixEntries(selfReviewerSection),
+	]
 	const skipped = parseSkippedEntries(skippedSection)
-	return { exists: true, fixes, skipped }
+	// Detect which heading was present; fixer takes precedence when both appear.
+	const schema = fixesSection ? 'fixer' : 'self-reviewer'
+	return { exists: true, fixes, skipped, schema }
 }
 
-function parseFixEntries(section) {
+/**
+ * Parse the body of a `## Fixes Applied by Self-Reviewer` section into
+ * entries shaped like fixer entries (id, title, file, files, verification).
+ *
+ * The self-reviewer agent emits `### Fix N: description` per fix instead
+ * of `### ID — title`, because the reviewer doesn't carry the original
+ * finding ids forward. We synthesize id `self-reviewer-fix-${N}` so the
+ * rest of the audit pipeline (decideVerdict rule 3 guard, audit.json
+ * envelope) stays schema-agnostic. The body shape — `- **File**:` /
+ * `- **Change**:` — is identical to fixer entries, so we reuse
+ * extractFileFields verbatim. Verification is not part of the self-
+ * reviewer schema (their PASS/FAIL signal lives in `## Verification
+ * Results` and is already covered by parseFixerStatusLine), so we leave
+ * `verification: null` and let the gate's diff-intersect step decide.
+ */
+function parseSelfReviewerFixEntries(section) {
 	if (!section) return []
-	// `### <id> — <title>` OR `### <id> -- <title>` OR `### <id>` alone.
-	// The fixer template uses em-dash + space; we tolerate either.
+	// `### Fix 1: description` / `### Fix 2: description`.
 	const entries = []
-	const headerRx = /^###\s+([A-Z]+-\d+)(?:\s*[—-]{1,2}\s*(.+))?$/gm
+	const headerRx = /^###\s+Fix\s+(\d+)(?:\s*:\s*(.+))?$/gm
 	const matches = [...section.matchAll(headerRx)]
 	for (let i = 0; i < matches.length; i++) {
 		const m = matches[i]
@@ -151,10 +185,8 @@ function parseFixEntries(section) {
 		const body = section.slice(start, nextStart)
 		const files = extractFileFields(body)
 		entries.push({
-			id: m[1],
+			id: `self-reviewer-fix-${m[1]}`,
 			title: m[2] ? m[2].trim() : null,
-			// Back-compat: single-path consumers + tests still see `file`
-			// (the first extracted path). New code should prefer `files`.
 			file: files[0] ?? null,
 			files,
 			verification: extractVerificationField(body),
@@ -163,6 +195,48 @@ function parseFixEntries(section) {
 	return entries
 }
 
+function parseFixEntries(section) {
+	if (!section) return []
+	// `### <id> — <title>` OR `### <id> -- <title>` OR `### <id>` alone.
+	// The fixer template uses em-dash + space; we tolerate either.
+	//
+	// PR #95 (2026-05-12) widened the capture to accept combined-id headers
+	// like `### QUA-003 + FIT-001 — title` where one body explains multiple
+	// findings. The locked separator alphabet is `+`, `,`, and ` and ` —
+	// the exact set observed in live fixer reports. We do NOT widen to a
+	// generic `\W+` splitter; the alphabet stays narrow so a typo like
+	// `### QUA-003-foo` cannot be mis-parsed as id `QUA-003`. Combined
+	// headers produce one entry per id, all sharing the same body fields
+	// (files, verification, title).
+	const entries = []
+	const headerRx =
+		/^###\s+([A-Z]+-\d+(?:\s*(?:\+|,|\s+and\s+)\s*[A-Z]+-\d+)*)(?:\s*[—-]{1,2}\s*(.+))?$/gm
+	const idSplitRx = /\s*(?:\+|,|\s+and\s+)\s*/
+	const matches = [...section.matchAll(headerRx)]
+	for (let i = 0; i < matches.length; i++) {
+		const m = matches[i]
+		const start = m.index
+		const nextStart = i + 1 < matches.length ? matches[i + 1].index : section.length
+		const body = section.slice(start, nextStart)
+		const files = extractFileFields(body)
+		const title = m[2] ? m[2].trim() : null
+		const verification = extractVerificationField(body)
+		const ids = m[1].split(idSplitRx)
+		for (const id of ids) {
+			entries.push({
+				id,
+				title,
+				// Back-compat: single-path consumers + tests still see `file`
+				// (the first extracted path). New code should prefer `files`.
+				file: files[0] ?? null,
+				files,
+				verification,
+			})
+		}
+	}
+	return entries
+}
+
 function parseSkippedEntries(section) {
 	if (!section) return []
 	const entries = []
@@ -518,12 +592,14 @@ export function decideVerdict({ statusLine, fixesApplied, diffFiles }) {
 	// fail-closed trap. The report could be scaffolded with headers but
 	// no actual entries.
 	if (claimed.fixed > 0 && report.fixes.length === 0) {
+		const heading =
+			report.schema === 'self-reviewer' ? '## Fixes Applied by Self-Reviewer' : '## Fixes Applied'
 		return {
 			verdict: 'hallucinated',
 			reason:
 				`fixer claimed FIXED=${claimed.fixed} but fixes-applied.md has zero ` +
 				`### <id>` +
-				` entries under ## Fixes Applied`,
+				` entries under ${heading}`,
 			claimed,
 			matched: [],
 			unmatched: [],
@@ -551,10 +627,13 @@ export function decideVerdict({ statusLine, fixesApplied, diffFiles }) {
 	// Main rule: FIXED > 0 AND PASS — intersect claimed files with the
 	// worktree diff. Empty intersection = hallucination.
 	if (claimed.fixed > 0 && claimed.verification === 'PASS') {
-		const claimedFiles = report.fixes.flatMap((f) =>
-			Array.isArray(f.files) ? f.files : f.file ? [f.file] : [],
-		)
-		const { matched, unmatched } = intersectClaimedAndStaged(claimedFiles, diffFiles)
+		const claimedFiles = [
+			...new Set(
+				report.fixes.flatMap((f) => (Array.isArray(f.files) ? f.files : f.file ? [f.file] : [])),
+			),
+		]
+		const { matched: rawMatched, unmatched } = intersectClaimedAndStaged(claimedFiles, diffFiles)
+		const matched = [...new Set(rawMatched)]
 		if (matched.length === 0) {
 			return {
 				verdict: 'hallucinated',

package/src/cli/commands/route.mjs

@@ -138,7 +138,7 @@ const PR_REVIEW_SIGNAL = /(?:\bPR\s*#?\s*\d+|#\d+|\bpull\s*request\s*#?\s*\d+)\b
  * so this keeps the two paths consistent.
  *
  * @param {import('../route/skill-discover.mjs').DiscoveredSkill[]} skills
- * @returns {{ agentOf: (slug: string) => string|null, spawnsAgent: (slug: string) => boolean, knownSlugs: Set<string>, isUserInvocable: (slug: string) => boolean }}
+ * @returns {{ agentOf: (slug: string) => string|null, spawnsAgent: (slug: string) => boolean, taskContextOf: (slug: string) => string|null, defaultTrackOf: (slug: string) => string|null, knownSlugs: Set<string>, isUserInvocable: (slug: string) => boolean }}
  */
 function skillIndex(skills) {
 	const byName = new Map()
@@ -160,6 +160,12 @@ function skillIndex(skills) {
 		spawnsAgent(slug) {
 			return Boolean(byName.get(slug)?.spawns_agent)
 		},
+		taskContextOf(slug) {
+			return byName.get(slug)?.task_context ?? null
+		},
+		defaultTrackOf(slug) {
+			return byName.get(slug)?.default_track ?? null
+		},
 		isUserInvocable(slug) {
 			return userInvocableSlugs.has(slug)
 		},
@@ -322,6 +328,7 @@ export function cmdRoute(projectDir, extraArgs) {
 	if (!isPrReviewFreetext && index.knownSlugs.has(firstWord)) {
 		const shouldSpawn = index.spawnsAgent(firstWord)
 		const gate_preview = previewGatesFor(firstWord)
+		const defaultTrack = index.defaultTrackOf(firstWord)
 		return ok({
 			status: 'ok',
 			command: 'route',
@@ -330,6 +337,8 @@ export function cmdRoute(projectDir, extraArgs) {
 			skill_args: remainingArgs || null,
 			spawn_agent: shouldSpawn,
 			agent: shouldSpawn ? index.agentOf(firstWord) || `apt-${firstWord}` : null,
+			task_context: index.taskContextOf(firstWord),
+			...(defaultTrack ? { default_track: defaultTrack } : {}),
 			host_capabilities,
 			task_isolation,
 			update_check,

package/src/cli/commands/task.mjs

@@ -779,6 +779,13 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 					// C56 A2 — `--pr-url <url>` records the GitHub PR URL opened by
 					// apt:ship. Downstream consumers: task close (auto_close_phase
 					// gate) and `task close-merged` (/apt:close-task).
+					//
+					// Defect fix (12-05-26): when the caller does NOT also pass
+					// `--lifecycle-phase` and the task is currently in `reviewing`,
+					// auto-flip lifecycle to `shipped-pending-merge` atomically.
+					// This collapses the two-call apt:ship contract into a single
+					// load-bearing call so orchestrators can't drop the lifecycle
+					// transition. Idempotent / no-op on any other phase.
 					if (flags.has('pr-url')) {
 						const url = flags.get('pr-url')
 						if (!url || typeof url !== 'string') {
@@ -794,6 +801,26 @@ export function cmdTask(subcommand, projectDir, extraArgs) {
 							return
 						}
 						task.pr_url = url
+						if (!flags.has('lifecycle-phase') && task.lifecycle_phase === 'reviewing') {
+							task.lifecycle_phase = 'shipped-pending-merge'
+							if (!Array.isArray(task.lifecycle_history)) task.lifecycle_history = []
+							task.lifecycle_history.push({
+								phase: 'shipped-pending-merge',
+								at: new Date().toISOString(),
+								reason: 'auto-flip on --pr-url',
+							})
+							store.appendEvent({
+								op: 'task.lifecycle.shipped-pending-merge',
+								task: taskId,
+								data: {
+									lifecycle_phase: 'shipped-pending-merge',
+									scope: task.scope || 'project',
+									milestone_id: task.milestone_id ?? null,
+									phase_id: task.phase_id ?? null,
+									reason: 'auto-flip on --pr-url',
+								},
+							})
+						}
 					}
 					if (flags.has('subtasks-total'))
 						task.progress.subtasks_total = parseInt(flags.get('subtasks-total'), 10)

package/src/cli/design/frontmatter-schema.mjs

@@ -83,7 +83,9 @@ export const TypographySchema = z
 	.object({
 		families: TypographyFamiliesSchema,
 		scale: z.array(PixelOrRem).min(3), // at least {body, heading, display}
-		weights: z.array(z.number().int().positive()).optional(),
+		weights: z
+			.union([z.array(z.number().int().positive()), z.record(z.string(), z.number().positive())])
+			.optional(),
 		lineHeight: z.record(z.string(), NonEmptyString).optional(),
 	})
 	.passthrough()

package/src/cli/route/skill-discover.mjs

@@ -47,6 +47,8 @@ const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n/
  * @property {string[]} gates
  * @property {string} default_execution_mode
  * @property {string[]} execution_modes
+ * @property {'create-new'|'require-existing'|'self-managed'|'none'} task_context
+ * @property {('QUICK'|'STANDARD'|'DEEP'|'DEBUG')|undefined} default_track
  * @property {string} file_path           absolute path to the SKILL.md
  */
 
@@ -165,6 +167,8 @@ function readSkill(file) {
 			gates: Array.isArray(d.gates) ? [...d.gates] : [],
 			default_execution_mode: d.default_execution_mode,
 			execution_modes: Array.isArray(d.execution_modes) ? [...d.execution_modes] : [],
+			task_context: d.task_context,
+			default_track: d.default_track,
 			file_path: file,
 		},
 	}
@@ -206,11 +210,38 @@ function walkSkillRoot(root) {
 	return out
 }
 
+/**
+ * Redact raw attacker-controlled values from Zod validation error strings
+ * before they are written to the log (SEC-002). Zod enum rejection messages
+ * embed the received value verbatim: "Invalid enum value. Expected ...,
+ * received 'evil-payload'". We strip the received portion and replace it
+ * with a byte-length indicator so downstream log consumers never see the
+ * raw attacker string.
+ *
+ * @param {string[]} errors
+ * @returns {string[]}
+ */
+function redactErrors(errors) {
+	if (!Array.isArray(errors)) return errors
+	return errors.map((msg) => {
+		if (typeof msg !== 'string') return msg
+		// Replace ", received '<anything>'" with a length annotation.
+		// The regex is anchored to the literal Zod enum error suffix so
+		// only the received-value fragment is removed, not diagnostic context.
+		return msg.replace(/, received '([^']*)'/g, (_, v) => `, received [${v.length} chars redacted]`)
+	})
+}
+
 /**
  * Append one dropped record to .aperant/logs/route-dropped.jsonl. Best-
  * effort — if the log dir can't be created we swallow the error (the
  * router still returns the envelope without the skill).
  *
+ * SEC-002: the `errors` array may contain raw attacker-controlled field
+ * values from Zod enum rejections. redactErrors() strips the received-value
+ * fragment before the record is serialized so log consumers (dashboards,
+ * alert rules) never see the raw attacker string.
+ *
  * @param {string} targetDir
  * @param {DiscoveredDrop} drop
  */
@@ -218,9 +249,11 @@ function logDropped(targetDir, drop) {
 	try {
 		const logDir = join(targetDir, '.aperant', 'logs')
 		mkdirSync(logDir, { recursive: true })
+		const safeErrors = drop.errors ? redactErrors(drop.errors) : undefined
+		const record = safeErrors !== undefined ? { ...drop, errors: safeErrors } : drop
 		appendFileSync(
 			join(logDir, 'route-dropped.jsonl'),
-			`${JSON.stringify({ ts: new Date().toISOString(), ...drop })}\n`,
+			`${JSON.stringify({ ts: new Date().toISOString(), ...record })}\n`,
 			'utf-8',
 		)
 	} catch {

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

@@ -80,6 +80,26 @@ export const STAGES = Object.freeze([
  */
 export const EXECUTION_MODES = Object.freeze(['auto', 'step', 'plan-mode', 'plan-only', 'research'])
 
+/**
+ * Skill-passthrough policy values (router-0.4 / G25 fix). The `apt/SKILL.md`
+ * orchestrator dispatches on this frontmatter field — missing values fail
+ * closed so new skills can't silently bypass task registration. See
+ * docs/frameworks/spec-gaps.md#g25 for the defect that motivated this.
+ */
+export const TASK_CONTEXTS = Object.freeze([
+	'create-new',
+	'require-existing',
+	'self-managed',
+	'none',
+])
+
+/**
+ * Optional default track for skills with `task_context: create-new`. The
+ * router falls back to a per-slug hardcoded table when this field is omitted;
+ * declaring it here lets a skill own its default without a router code change.
+ */
+export const TRACK_VALUES = Object.freeze(['QUICK', 'STANDARD', 'DEEP', 'DEBUG'])
+
 /**
  * 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
@@ -138,6 +158,8 @@ export const SkillFrontmatterSchema = z
 		gates: z.array(z.string()),
 		default_execution_mode: ExecutionModeSchema,
 		execution_modes: z.array(ExecutionModeSchema).min(1),
+		task_context: z.enum([...TASK_CONTEXTS]),
+		default_track: z.enum([...TRACK_VALUES]).optional(),
 		// Legacy / optional pass-throughs — kept as opt-in so migrations
 		// don't immediately break skills that carry them.
 		triggers: z.array(z.string()).optional(),

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

@@ -25,13 +25,14 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
-allowed-tools: "Read, Grep, Glob"
-argument-hint: "${fullName} [args]"
-gates: []
+task_context: create-new  # one of: create-new | require-existing | self-managed | none — see packages/framework/docs/skill-passthrough.md
 default_execution_mode: auto
 execution_modes:
   - auto
   - step
+allowed-tools: "Read, Grep, Glob"
+argument-hint: "${fullName} [args]"
+gates: []
 triggers:
   - /${fullName}
   - ${fullName}