@aperant/framework 0.6.5 → 0.6.7

package/src/cli/release-notes/ship-autodraft.mjs

@@ -0,0 +1,106 @@
+/**
+ * release-notes/ship-autodraft.mjs — apt-ship Section 2.6 helper.
+ *
+ * Deterministic, unit-testable shape: given a feature-registry diff +
+ * personas envelope + persona_filter mode, decide whether the PR body
+ * should grow a `Release note: …` line OR ship should block.
+ *
+ * This module is intentionally pure — the apt-ship SKILL.md body shells
+ * `apt-tools features-audit . --diff-since <base> --json` and feeds the
+ * envelope here. Keeping the decision pure makes TD-4 trivial: fixture in,
+ * decision out, no I/O.
+ */
+
+import { buildPersonaTierMap, classifyFragment } from './persona-filter.mjs'
+
+/**
+ * @typedef {Object} FeatureDiffEntry
+ * @property {string} feature_id
+ * @property {string} [area]
+ * @property {string[]} [personas]
+ */
+
+/**
+ * @typedef {Object} AutodraftInput
+ * @property {FeatureDiffEntry[]} featureDiff
+ * @property {{ personas?: Array<{ ui_json?: unknown }> } | null} personasEnvelope
+ * @property {'primary' | 'primary+secondary' | 'all'} personaFilter
+ * @property {boolean} requirePrField
+ */
+
+/**
+ * @typedef {{
+ *   status: 'draft',
+ *   line: string,
+ *   persona: string,
+ *   matchedFeatures: string[],
+ * } | {
+ *   status: 'block',
+ *   reason: 'no-feature-match' | 'no-persona-signal',
+ *   message: string,
+ * } | {
+ *   status: 'warn',
+ *   reason: 'no-feature-match' | 'no-persona-signal',
+ *   message: string,
+ * }} AutodraftResult
+ */
+
+const BLOCK_MESSAGE =
+	'[APT] No release-note signal found — author manual note in PR body or label PR no-notes'
+
+/**
+ * Compute the autodraft decision.
+ *
+ * @param {AutodraftInput} input
+ * @returns {AutodraftResult}
+ */
+export function decideAutodraft(input) {
+	const tierMap = buildPersonaTierMap(input.personasEnvelope)
+
+	if (!Array.isArray(input.featureDiff) || input.featureDiff.length === 0) {
+		return failClassify(input, 'no-feature-match')
+	}
+
+	// Walk the diff; the first feature whose persona resolves into the
+	// filter mode wins. (Multi-persona dispatch is intentionally out of
+	// scope here — host LLM-side narrative can refine per persona; the
+	// CLI just picks a clean signal so ship is decisive.)
+	for (const feature of input.featureDiff) {
+		if (!Array.isArray(feature.personas) || feature.personas.length === 0) continue
+		for (const personaTag of feature.personas) {
+			const decision = classifyFragment(personaTag, tierMap, input.personaFilter)
+			if (decision.bucket === 'body' && decision.resolvedTier) {
+				return {
+					status: 'draft',
+					line: `Release note: ${feature.feature_id} — ships for ${personaTag}.`,
+					persona: personaTag,
+					matchedFeatures: [feature.feature_id],
+				}
+			}
+		}
+	}
+
+	// No persona signal anywhere — features exist but none carry a tag
+	// that the roster + filter accept.
+	return failClassify(input, 'no-persona-signal')
+}
+
+/**
+ * Translate a failure reason into the right envelope shape based on
+ * `require_pr_field`. require=true → block; require=false → warn (skill
+ * proceeds without the line).
+ *
+ * @param {AutodraftInput} input
+ * @param {'no-feature-match' | 'no-persona-signal'} reason
+ * @returns {AutodraftResult}
+ */
+function failClassify(input, reason) {
+	if (input.requirePrField) {
+		return { status: 'block', reason, message: BLOCK_MESSAGE }
+	}
+	return {
+		status: 'warn',
+		reason,
+		message: `[APT] auto-draft skipped (${reason}) — release_notes.require_pr_field is false; proceeding without a Release note line.`,
+	}
+}

package/src/cli/roadmap/conductor-view.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Type declarations for the .mjs conductor-view helper.
+ * Hand-authored — the import path points at src/.mjs directly.
+ */
+
+export interface ConductorRoadmapView {
+	scopes: Array<{ scope: string; roadmap: unknown }>
+}
+
+export function buildConductorRoadmapView(projectRoot: string): ConductorRoadmapView

package/src/cli/roadmap/conductor-view.mjs

@@ -0,0 +1,31 @@
+/**
+ * conductor-view.mjs — read-only roadmap surface for the Aperant
+ * Conductor's `getRoadmap` tool.
+ *
+ * Wraps `loadRoadmapForScope` + `listRoadmapScopes` so the Conductor sees
+ * the same overlay-aware view every framework command sees. Direct reads
+ * of `.aperant/roadmap/*\/phases/*.json` or `milestones.json` would miss
+ * the dual-write overlay (seed_id from legacy blob, etc.) — Codex
+ * roundtable correction #3.
+ *
+ * Step 5 of Conductor v2 ship order.
+ */
+
+import { loadRoadmapForScope } from './io.mjs'
+import { listRoadmapScopes } from './paths.mjs'
+
+/**
+ * Build a flat per-scope roadmap snapshot for the Conductor.
+ *
+ * @param {string} projectRoot
+ * @returns {{ scopes: Array<{ scope: string, roadmap: unknown }> }}
+ */
+export function buildConductorRoadmapView(projectRoot) {
+	const scopes = listRoadmapScopes(projectRoot)
+	const out = []
+	for (const scope of scopes) {
+		const roadmap = loadRoadmapForScope(projectRoot, scope)
+		if (roadmap !== null) out.push({ scope, roadmap })
+	}
+	return { scopes: out }
+}

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

@@ -29,6 +29,7 @@ import {
 } from 'node:fs'
 import { isAbsolute, join, relative, resolve } from 'node:path'
 import { parse as parseYaml } from 'yaml'
+import { sanitizeAptVersionForYamlParse } from '../install/version-header.mjs'
 import { SkillFrontmatterSchema } from '../skill-author/contract.mjs'
 
 const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n/
@@ -126,7 +127,7 @@ function readSkill(file) {
 	}
 	let parsed
 	try {
-		parsed = parseYaml(m[1])
+		parsed = parseYaml(sanitizeAptVersionForYamlParse(m[1]))
 	} catch (err) {
 		return {
 			ok: false,

package/src/cli/task/ids.mjs

@@ -9,8 +9,7 @@ import { join, resolve } from 'node:path'
  * Supported formats: YY-MM-DD (default, sorts chronologically), DD-MM-YY, MM-DD-YY
  * Uses hyphens as separators for filesystem safety.
  */
-export function formatDateForTask(dateFormat) {
-	const now = new Date()
+export function formatDateForTask(dateFormat, now = new Date()) {
 	const yy = String(now.getFullYear()).slice(2)
 	const mm = String(now.getMonth() + 1).padStart(2, '0')
 	const dd = String(now.getDate()).padStart(2, '0')
@@ -27,20 +26,23 @@ export function formatDateForTask(dateFormat) {
 
 /**
  * Generate a short task ID from description + timestamp.
- * Format: {date}_{slug}-{4-char-hash}
- * Date comes first so tasks sort chronologically in file explorers.
+ * Format: {slug}_{date}
+ * Slug comes first so task lists scan by verb instead of by date.
  * Date format is configurable via preferences.date_format in config.
+ * Same-day same-slug collisions are disambiguated by the caller
+ * (see commands/task.mjs) via a numeric -2, -3, … suffix; this
+ * generator never emits a counter or a random hash.
  */
-export function generateTaskId(description, config) {
-	const slug = description
-		.toLowerCase()
-		.replace(/[^a-z0-9]+/g, '-')
-		.replace(/^-|-$/g, '')
-		.slice(0, 40)
+export function generateTaskId(description, config, now = new Date()) {
+	const slug =
+		description
+			.toLowerCase()
+			.replace(/[^a-z0-9]+/g, '-')
+			.slice(0, 40)
+			.replace(/^-|-$/g, '') || 'task'
 	const dateFormat = config?.preferences?.date_format || 'YY-MM-DD'
-	const date = formatDateForTask(dateFormat)
-	const hash = Math.random().toString(36).slice(2, 6)
-	return `${date}_${slug}-${hash}`
+	const date = formatDateForTask(dateFormat, now)
+	return `${slug}_${date}`
 }
 
 export function getTaskDir(projectDir, taskId) {

package/templates/config.json

@@ -1,5 +1,5 @@
 {
-	"version": 4,
+	"version": 5,
 	"project_type": "unknown",
 	"share": {
 		"$comment": "Artifact-sharing policy (C35). Source of truth: packages/framework/src/cli/config/share-policy.mjs. visibility = 'solo' | 'team' | 'oss' preset; individual share.* toggles override it. share.digests = null inherits from config.digests.enabled.",
@@ -107,12 +107,37 @@
 		"debate_mode": "auto"
 	},
 	"diagram": {
-		"mode": "file",
-		"mcpConsent": null
+		"mode": "file"
 	},
 	"docs_policy": {
 		"$comment": "C33 docs-coherence policy. Override via /apt:setup Batch 7. Keys are globs/paths; values are 'auto-update' | 'flag-drift' | 'skip'. Missing block → defaults from packages/framework/templates/docs-policy-defaults.json apply."
 	},
+	"changelog": {
+		"$comment": "v5 — persona-aware changelog + release-notes system. Two surfaces: dev changelog (CHANGELOG.md from commits, default ON) and user-facing release notes (docs/releases, default OFF). Opt in per project via /apt:setup Batch 9. See packages/framework/skills/apt-release-notes/SKILL.md.",
+		"dev": {
+			"enabled": true,
+			"file": "CHANGELOG.md",
+			"format": "keep-a-changelog",
+			"source": "commits"
+		},
+		"release_notes": {
+			"enabled": false,
+			"audience": null,
+			"output_dir": "docs/releases",
+			"persona_filter": "primary+secondary",
+			"require_pr_field": true,
+			"draft": {
+				"on_pr_merge": true,
+				"fragments_dir": "docs/releases/_unreleased"
+			},
+			"compile": {
+				"on_tag": true
+			},
+			"publish": {
+				"targets": ["github-release"]
+			}
+		}
+	},
 	"router": {
 		"llm": {
 			"enabled": true,

package/workflows/docs.md

@@ -90,6 +90,18 @@ Gather facts from the actual codebase. The depth depends on doc type:
 - Conventional commit messages to categorize changes
 - Breaking changes (commits with `BREAKING CHANGE` or `!:`)
 
+> **Two-skill split (v0.7.0+).** `/apt:docs changelog` owns the
+> dev-flavored `CHANGELOG.md` surface — internal task IDs, file paths,
+> schema-bump notes, process trivia. For the user-facing complement,
+> projects can opt in to `/apt:release-notes` via `/apt:setup` →
+> Batch 9. That skill produces persona-voice-tuned release notes
+> (towncrier-style fragments at PR-merge time, compiled per tag, pushed
+> to GitHub Releases). The two skills coexist intentionally: a single
+> `--audience` flag inside `/apt:docs changelog` drifts to a
+> lowest-common-denominator artifact that satisfies neither audience.
+> See `packages/framework/skills/apt-release-notes/SKILL.md` for the
+> opt-in surface and the three modes (draft / compile / publish).
+
 ### For Contributing
 - Development setup steps (verified by checking file existence)
 - Test commands (verified by running them)