@aperant/framework 0.6.3 → 0.6.4

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}