cyber-sdd 0.6.1 → 0.7.1

package/skills/concept-index/scripts/concept-index.mts

@@ -1,246 +0,0 @@
-#!/usr/bin/env node
-// concept-index — project-spec/concept-index's concrete engine. Scans one project-spec for every node's
-// `concept:` frontmatter and renders the by-concept view (concept → its nodes across every folder),
-// which re-unifies a cross-cutting concern the capability folder tree scatters
-// (the concept axis).
-//
-// Pure derivation from the `concept:` tags: rendering twice is byte-identical, and the generated
-// block in the root spec.md is the only thing a --write touches. Frontmatter only — no node body
-// reaches the output. No dependencies (the repo's node-≥23.6 / no-deps convention). Pure functions
-// are exported for node:test; running the file directly drives the CLI.
-
-import { existsSync, readdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
-import { join, relative } from 'node:path'
-import { pathToFileURL } from 'node:url'
-
-export const BEGIN_MARKER = '<!-- BEGIN generated: by-concept (project-spec/concept-index) -->'
-export const END_MARKER = '<!-- END generated: by-concept -->'
-// Where the block is inserted when the markers are absent: just before this heading.
-const ANCHOR_HEADING = '## Invariants'
-
-const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', '.turbo', '.next', 'coverage'])
-
-export type FacetKind = 'rule' | 'workflow' | 'reference' | 'behavior' | 'index'
-
-export interface NodeRecord {
-	/** Path relative to the spec directory (POSIX). */
-	relPath: string
-	/** Display form — a README.md node shows its folder, a design doc shows the file. */
-	display: string
-	concepts: string[]
-	facet: FacetKind
-}
-
-export interface NodeFrontmatter {
-	concepts: string[]
-	specType?: string
-	model: boolean
-}
-
-// ── Frontmatter parse (a minimal YAML subset — only the node classification schema) ──
-// Reads the leading `---` … `---` block for `concept` (scalar | flow list | block list),
-// `spec-type`, and `model`. Returns null when there is no frontmatter block.
-export function parseFrontmatter(text: string): NodeFrontmatter | null {
-	const m = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/.exec(text)
-	if (!m) return null
-	const fm: NodeFrontmatter = { concepts: [], model: false }
-	const lines = m[1].split('\n').map((l) => l.replace(/\r$/, ''))
-	for (let i = 0; i < lines.length; i++) {
-		const line = lines[i]
-		if (line.trim() === '' || line.trim().startsWith('#')) continue
-		if (line.length - line.trimStart().length !== 0) continue // only top-level keys
-		const [key, ...rest] = line.trim().split(':')
-		const value = rest.join(':').trim()
-		if (key === 'spec-type') fm.specType = unquote(value)
-		else if (key === 'model') fm.model = unquote(value) === 'true'
-		else if (key === 'concept') {
-			if (value === '' || value === '|' || value === '>') {
-				// block list on following more-indented `- item` lines
-				for (let j = i + 1; j < lines.length; j++) {
-					const item = lines[j]
-					if (item.trim() === '') continue
-					if (item.length - item.trimStart().length === 0) break
-					const dash = /^\s*-\s+(.*)$/.exec(item)
-					if (dash) fm.concepts.push(unquote(dash[1].trim()))
-				}
-			} else {
-				fm.concepts.push(...parseScalarOrFlow(value))
-			}
-		}
-	}
-	return fm
-}
-
-// `resolution` | `[governance, resolution]` → string[]
-export function parseScalarOrFlow(value: string): string[] {
-	const v = value.trim()
-	if (v.startsWith('[') && v.endsWith(']')) {
-		return v
-			.slice(1, -1)
-			.split(',')
-			.map((s) => unquote(s.trim()))
-			.filter((s) => s.length > 0)
-	}
-	const single = unquote(v)
-	return single.length > 0 ? [single] : []
-}
-
-function unquote(v: string): string {
-	return v.replace(/^["']|["']$/g, '')
-}
-
-// ── Facet kind — where this node's facet sits, mechanically ──
-export function facetKind(relPath: string, specType: string | undefined): FacetKind {
-	const p = relPath.replace(/\\/g, '/')
-	if (p.startsWith('design/')) return 'rule'
-	if (p.startsWith('workflows/')) return 'workflow'
-	if (specType === 'reference') return 'reference'
-	if (specType === 'behavioral') return 'behavior'
-	return 'index'
-}
-
-function displayPath(relPath: string): string {
-	const p = relPath.replace(/\\/g, '/')
-	return p.endsWith('/README.md') ? p.slice(0, -'README.md'.length) : p
-}
-
-// ── Scan the project-spec — every *.md node carrying a concept tag ──
-export function scanProjectSpec(specDir: string): NodeRecord[] {
-	const records: NodeRecord[] = []
-	walk(specDir, specDir, records)
-	return records
-}
-
-function walk(dir: string, specDir: string, out: NodeRecord[]): void {
-	for (const entry of readdirSync(dir, { withFileTypes: true })) {
-		if (entry.name.startsWith('.') || SKIP_DIRS.has(entry.name)) continue
-		const full = join(dir, entry.name)
-		if (entry.isDirectory()) {
-			walk(full, specDir, out)
-		} else if (entry.name.endsWith('.md')) {
-			const fm = parseFrontmatter(readFileSync(full, 'utf8'))
-			if (!fm || fm.concepts.length === 0) continue
-			const relPath = relative(specDir, full).replace(/\\/g, '/')
-			out.push({
-				relPath,
-				display: displayPath(relPath),
-				concepts: fm.concepts,
-				facet: facetKind(relPath, fm.specType),
-			})
-		}
-	}
-}
-
-// ── Group + render ──
-export function groupByConcept(records: NodeRecord[]): Map<string, NodeRecord[]> {
-	const grouped = new Map<string, NodeRecord[]>()
-	for (const rec of records) {
-		for (const concept of rec.concepts) {
-			const list = grouped.get(concept) ?? []
-			list.push(rec)
-			grouped.set(concept, list)
-		}
-	}
-	// stable order: concepts alphabetical, nodes by display path
-	return new Map(
-		[...grouped.entries()]
-			.sort(([a], [b]) => a.localeCompare(b))
-			.map(([k, v]) => [k, [...v].sort((x, y) => x.display.localeCompare(y.display))]),
-	)
-}
-
-export function renderTable(grouped: Map<string, NodeRecord[]>): string {
-	const rows = [...grouped.entries()].map(([concept, nodes]) => {
-		const facets = nodes.map((n) => `\`${n.display}\` (${n.facet})`).join(' · ')
-		return `| \`${concept}\` | ${facets} |`
-	})
-	return ['| Concept | Facets |', '|---|---|', ...rows].join('\n')
-}
-
-// The full generated section, markers included.
-export function renderSection(grouped: Map<string, NodeRecord[]>): string {
-	return [
-		BEGIN_MARKER,
-		'',
-		'## By concept',
-		'',
-		'> Generated from `concept:` frontmatter by `project-spec/concept-index` — do not edit by hand.',
-		'',
-		renderTable(grouped),
-		'',
-		END_MARKER,
-	].join('\n')
-}
-
-// ── spec.md block maintenance ──
-// Replace the BEGIN…END block with `section`; insert at the anchor (or append) when absent.
-export function applySection(specText: string, section: string): string {
-	const begin = specText.indexOf(BEGIN_MARKER)
-	const end = specText.indexOf(END_MARKER)
-	if (begin !== -1 && end !== -1 && end > begin) {
-		const before = specText.slice(0, begin)
-		const after = specText.slice(end + END_MARKER.length)
-		return before + section + after
-	}
-	const anchor = specText.indexOf(ANCHOR_HEADING)
-	if (anchor !== -1) {
-		return specText.slice(0, anchor) + section + '\n\n' + specText.slice(anchor)
-	}
-	const trimmed = specText.replace(/\s*$/, '')
-	return `${trimmed}\n\n${section}\n`
-}
-
-// Extract the current block (BEGIN…END inclusive), or null when absent.
-export function extractSection(specText: string): string | null {
-	const begin = specText.indexOf(BEGIN_MARKER)
-	const end = specText.indexOf(END_MARKER)
-	if (begin === -1 || end === -1 || end < begin) return null
-	return specText.slice(begin, end + END_MARKER.length)
-}
-
-// ── CLI ──
-function parseArgs(argv: string[]): { specDir: string; mode: 'print' | 'write' | 'check' } {
-	let specDir = '.'
-	let mode: 'print' | 'write' | 'check' = 'print'
-	for (let i = 0; i < argv.length; i++) {
-		const a = argv[i]
-		if (a === '--spec-dir') specDir = argv[++i] ?? '.'
-		else if (a === '--write') mode = 'write'
-		else if (a === '--check') mode = 'check'
-	}
-	return { specDir, mode }
-}
-
-export function main(argv: string[]): number {
-	const { specDir, mode } = parseArgs(argv)
-	const grouped = groupByConcept(scanProjectSpec(specDir))
-	const section = renderSection(grouped)
-	const specPath = join(specDir, 'spec.md')
-	if (mode === 'print') {
-		process.stdout.write(`${section}\n`)
-		return 0
-	}
-	if (!existsSync(specPath)) {
-		process.stderr.write(`concept-index: no spec.md at ${specPath}\n`)
-		return 2
-	}
-	const specText = readFileSync(specPath, 'utf8')
-	if (mode === 'check') {
-		const current = extractSection(specText)
-		if (current === section) {
-			process.stdout.write('concept-index: no drift\n')
-			return 0
-		}
-		process.stderr.write('concept-index: drift — spec.md by-concept block is stale; run --write\n')
-		return 1
-	}
-	// write
-	const next = applySection(specText, section)
-	if (next !== specText) writeFileSync(specPath, next)
-	process.stdout.write(`concept-index: ${next === specText ? 'unchanged' : 'updated'} ${specPath}\n`)
-	return 0
-}
-
-if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
-	process.exit(main(process.argv.slice(2)))
-}

package/skills/discover-plans/scripts/discover-plans.mts

@@ -1,215 +0,0 @@
-#!/usr/bin/env node
-// discover-plans — intake/plan-discovery's concrete frontmatter engine. Scans the SDD
-// plan directory (.agents/plans) for *.plan.md mission briefs, parses each plan's
-// frontmatter (name + the todos tally by status) plus the lead line of its `## NEXT`
-// resume anchor, and emits a TOON list of the unretired / resumable missions.
-//
-// Recognition is location-bounded AND shape-confirmed:
-//   - a file named `<cr-ref>.plan.md` sitting directly under <root>/.agents/plans/ is a
-//     mission brief. A present plan brief is by definition UNRETIRED — the doctrine loop's
-//     plan-retirement deletes a plan once its CR is done/merged AND distilled — so every
-//     plan the scan finds is a resumable mission.
-//   - shape: the file must carry a frontmatter block (the basic plan template intake
-//     scaffolds). A `*.plan.md` with no frontmatter is skipped (a stray, not a brief).
-// Sibling files in the same directory that are NOT `*.plan.md` (a combat log `*.log.jsonl`,
-// a loose `*.md`) are never plan briefs and are ignored.
-//
-// Pure functions are exported for node:test; running the file directly drives the CLI.
-// No dependencies (the repo's node-≥23.6 / no-deps convention). --format json for a flat
-// array; default output is TOON (the token-efficient tabular form the gateway scans).
-
-import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs'
-import { join } from 'node:path'
-import { pathToFileURL } from 'node:url'
-
-export const TODO_STATUSES = new Set(['pending', 'in_progress', 'completed'])
-
-/** The default mission dispatch status — the meaning of an absent top-level `status`. */
-export const DEFAULT_PLAN_STATUS = 'active'
-
-export interface PlanRecord {
-	/** The CR ref — the plan's filename without the `.plan.md` suffix. */
-	cr: string
-	/** Frontmatter `name`, or '' when absent. */
-	name: string
-	/** Total todos in the brief. */
-	total: number
-	/** Todos with status `completed`. */
-	completed: number
-	/** Todos with status `in_progress`. */
-	inProgress: number
-	/** The mission dispatch flag — the top-level `status` (`active` when unset). */
-	status: string
-	/** The lead line of the `## NEXT` resume anchor, or '' when there is none. */
-	next: string
-}
-
-export interface PlanFrontmatter {
-	name: string
-	/** The mission dispatch flag — the top-level `status` (`active` when unset). */
-	status: string
-	total: number
-	completed: number
-	inProgress: number
-	pending: number
-}
-
-// ── Frontmatter parse (a minimal YAML subset — only the plan-brief schema) ──
-// Extracts the leading `---` … `---` block and reads `name` plus the `todos:` list's tally
-// by `status`. Returns null when there is no frontmatter block at all (a stray file).
-export function parsePlanFrontmatter(text: string): PlanFrontmatter | null {
-	const m = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/.exec(text)
-	if (!m) return null
-	const fm: PlanFrontmatter = {
-		name: '',
-		status: DEFAULT_PLAN_STATUS,
-		total: 0,
-		completed: 0,
-		inProgress: 0,
-		pending: 0,
-	}
-	let inTodos = false // currently inside the top-level `todos:` block
-	for (const raw of m[1].split('\n')) {
-		const line = raw.replace(/\r$/, '')
-		if (line.trim() === '' || line.trim().startsWith('#')) continue
-		const indent = line.length - line.trimStart().length
-		const trimmed = line.trim()
-		if (indent === 0) {
-			inTodos = false
-			const [key, ...rest] = trimmed.split(':')
-			const value = rest.join(':').trim()
-			if (key === 'name') fm.name = unquote(value)
-			// The top-level `status` is the plan's dispatch flag (distinct from a todo's
-			// `status`, which sits indented inside `todos:`). An empty value stays the default.
-			else if (key === 'status') {
-				const v = unquote(value)
-				if (v !== '') fm.status = v
-			} else if (key === 'todos') inTodos = true // value is empty; the list follows, indented
-			continue
-		}
-		// Inside the todos list — count each item's status. A list item's keys sit at
-		// indent ≥ 2 (`- id:` / `status:`); the status line is `status: <value>`.
-		if (inTodos) {
-			const sm = /^(?:-\s+)?status:\s*(.+)$/.exec(trimmed)
-			if (sm) {
-				const status = unquote(sm[1].trim())
-				fm.total++
-				if (status === 'completed') fm.completed++
-				else if (status === 'in_progress') fm.inProgress++
-				else if (status === 'pending') fm.pending++
-			}
-		}
-	}
-	return fm
-}
-
-function unquote(v: string): string {
-	return v.replace(/^["']|["']$/g, '')
-}
-
-// ── The `## NEXT` resume anchor lead ──
-// Find the `## NEXT` section (the resume anchor pause-mission writes) and return its first
-// content line — the next concrete action — trimmed of markdown bullet/emphasis markers and
-// capped. Returns '' when there is no NEXT section or it is empty. Body read is bounded to
-// this one section; the rest of the body is never parsed.
-export function nextLead(text: string): string {
-	const lines = text.split('\n')
-	let i = lines.findIndex((l) => /^##\s+NEXT\b/i.test(l.trim()))
-	if (i === -1) return ''
-	for (i += 1; i < lines.length; i++) {
-		const l = lines[i].replace(/\r$/, '').trim()
-		if (l === '') continue
-		if (l.startsWith('#')) return '' // hit the next heading with no content between
-		const cleaned = l
-			.replace(/^[-*]\s+/, '')
-			.replace(/\*\*/g, '')
-			.trim()
-		return cleaned.length > 200 ? `${cleaned.slice(0, 197)}...` : cleaned
-	}
-	return ''
-}
-
-// ── Scan ──
-// List the plan-brief filenames (relative names) directly under <root>/.agents/plans. Only
-// files ending `.plan.md` are briefs; a missing plans dir yields the empty set.
-function discoverPlanFiles(root: string): string[] {
-	const dir = join(root, '.agents', 'plans')
-	if (!existsSync(dir)) return []
-	let entries: import('node:fs').Dirent[]
-	try {
-		entries = readdirSync(dir, { withFileTypes: true })
-	} catch {
-		return []
-	}
-	return entries
-		.filter((e) => e.isFile() && e.name.endsWith('.plan.md'))
-		.map((e) => e.name)
-		.sort()
-}
-
-// ── Collect ──
-// The list of resumable missions: every plan brief carrying a frontmatter block, keyed by
-// its CR ref, with its todo tally and NEXT lead. Sorted by cr ref for stable output.
-export function collectPlans(root: string): PlanRecord[] {
-	const out: PlanRecord[] = []
-	for (const name of discoverPlanFiles(root)) {
-		let text: string
-		try {
-			text = readFileSync(join(root, '.agents', 'plans', name), 'utf8')
-		} catch {
-			continue
-		}
-		const fm = parsePlanFrontmatter(text)
-		if (!fm) continue // no frontmatter — a stray, not a brief
-		out.push({
-			cr: name.replace(/\.plan\.md$/, ''),
-			name: fm.name,
-			total: fm.total,
-			completed: fm.completed,
-			inProgress: fm.inProgress,
-			status: fm.status,
-			next: nextLead(text),
-		})
-	}
-	return out.sort((a, b) => (a.cr < b.cr ? -1 : a.cr > b.cr ? 1 : 0))
-}
-
-// ── Filter ──
-// Narrow a plan set to one dispatch status — the opt-in selector the gateway's dispatch loop
-// uses to build the approved queue. Records already carry a concrete `status` (unset → the
-// default `active`), so a filter to `active` includes the unset briefs and a value no brief
-// carries (an off-enum or simply-absent status) yields the empty set.
-export function filterByStatus(plans: PlanRecord[], status: string): PlanRecord[] {
-	return plans.filter((p) => p.status === status)
-}
-
-// ── Output ──
-const COLUMNS = ['cr', 'name', 'total', 'completed', 'inProgress', 'status', 'next'] as const
-
-// Quote a TOON field only when it carries the delimiter, a quote, or edge whitespace.
-function toonField(v: string): string {
-	if (v === '' || /[",]/.test(v) || v !== v.trim()) return `"${v.replace(/"/g, '""')}"`
-	return v
-}
-
-export function toToon(plans: PlanRecord[]): string {
-	const header = `plans[${plans.length}]{${COLUMNS.join(',')}}:`
-	const rows = plans.map((p) => `  ${COLUMNS.map((c) => toonField(String(p[c]))).join(',')}`)
-	return [header, ...rows].join('\n')
-}
-
-export function main(argv: string[]): number {
-	const root = argv.includes('--root') ? (argv[argv.indexOf('--root') + 1] ?? '.') : '.'
-	const format = argv.includes('--format') ? argv[argv.indexOf('--format') + 1] : 'toon'
-	const statusFilter = argv.includes('--status') ? argv[argv.indexOf('--status') + 1] : undefined
-	let plans = collectPlans(root)
-	// Opt-in: `--status <value>` narrows to the dispatch queue; absent, no status filter is applied.
-	if (statusFilter !== undefined) plans = filterByStatus(plans, statusFilter)
-	const out = format === 'json' ? JSON.stringify(plans, null, 2) : toToon(plans)
-	process.stdout.write(`${out}\n`)
-	return 0
-}
-
-if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
-	process.exit(main(process.argv.slice(2)))
-}