@event4u/agent-config 16.5.0 → 17.1.0

package/src/scripts/analysis_analysts.ts

@@ -0,0 +1,226 @@
+/**
+ * analysis_analysts.ts — the analyst class of the analysis doors: a planned
+ * count, one shared brief, independence-stamped outputs and the `handoff-v1`
+ * drops external sessions leave under `agents/tmp/<round-id>/`.
+ *
+ * An analyst is neither a council seat nor an implementer: it reads the scope,
+ * writes only into its own round folder and never pushes. Diversity comes from
+ * model family, so every analyst runs the same brief and the stamp records the
+ * family honestly — a same-family subagent can never read as cross-family.
+ */
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { parse as parseYaml } from 'yaml';
+
+import { independenceFields, type ContextRelation, type IndependenceFields } from './_lib/review_independence.js';
+import { ANALYST_BOUNDS } from './ai_council/cli_agency_bounds.js';
+
+export const DEFAULT_ANALYSTS = 3;
+export const MAX_ANALYSTS = 5;
+export const DROPS_REL = 'agents/tmp';
+
+export type AnalystMode = 'subagent' | 'external' | 'cli';
+export type AnalystPhase = 'seed' | 'deepen';
+export const HANDOFF_PHASES = ['seed', 'deepen', 'exchange'] as const;
+export type HandoffPhase = (typeof HANDOFF_PHASES)[number];
+
+/** Providers whose family `review_independence.ts` can place. */
+const KNOWN_FAMILIES = new Set(['anthropic', 'openai', 'gemini', 'xai', 'perplexity']);
+
+export class AnalystError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'AnalystError';
+    }
+}
+
+export interface AnalystPlan {
+    count: number;
+    exchange: boolean;
+    reason: 'default' | 'quick' | 'small-scope';
+}
+
+export function planAnalysts(opts: {
+    quick?: boolean;
+    analysts?: number;
+    scopeFiles?: number;
+    smallScopeFiles?: number;
+}): AnalystPlan {
+    const count = opts.analysts ?? DEFAULT_ANALYSTS;
+    if (!Number.isInteger(count) || count < 1 || count > MAX_ANALYSTS) {
+        throw new AnalystError(`analyst count must be an integer from 1 to ${MAX_ANALYSTS}, got ${count}`);
+    }
+    if (opts.quick === true) return { count: 1, exchange: false, reason: 'quick' };
+    if (opts.scopeFiles !== undefined && opts.smallScopeFiles !== undefined && opts.scopeFiles < opts.smallScopeFiles) {
+        return { count: 1, exchange: false, reason: 'small-scope' };
+    }
+    return { count, exchange: count > 1, reason: 'default' };
+}
+
+export function briefDigest(brief: string): string {
+    return `sha256:${createHash('sha256').update(brief).digest('hex')}`;
+}
+
+export interface AnalystOutput extends IndependenceFields {
+    analyst_id: string;
+    mode: AnalystMode;
+    family: string;
+    phase: AnalystPhase;
+    brief_digest: string;
+    body: string;
+    /** Analyst ids whose output this one read. Empty for every seed and deepen output. */
+    consulted: string[];
+}
+
+export function stampOutput(input: {
+    analyst_id: string;
+    mode: AnalystMode;
+    hostFamily: string;
+    family?: string | undefined;
+    context_relation?: ContextRelation;
+    phase: AnalystPhase;
+    brief: string;
+    body: string;
+    consulted: string[];
+}): AnalystOutput {
+    let family: string;
+    if (input.mode === 'cli') {
+        if (input.family === undefined || !KNOWN_FAMILIES.has(input.family)) {
+            throw new AnalystError(`${input.analyst_id}: a cli analyst needs a known provider family, got ${String(input.family)}`);
+        }
+        family = input.family;
+    } else if (input.mode === 'subagent') {
+        if (input.family !== undefined && input.family !== input.hostFamily) {
+            throw new AnalystError(
+                `${input.analyst_id}: a subagent analyst runs in the host family ${input.hostFamily}, not ${input.family}`,
+            );
+        }
+        family = input.hostFamily;
+    } else {
+        family = input.family ?? 'unknown';
+    }
+    const relation: ContextRelation = input.context_relation ?? (input.mode === 'external' ? 'unknown' : 'fresh');
+    const members = KNOWN_FAMILIES.has(family) && KNOWN_FAMILIES.has(input.hostFamily) ? [input.hostFamily, family] : [];
+    return {
+        analyst_id: input.analyst_id,
+        mode: input.mode,
+        family,
+        phase: input.phase,
+        brief_digest: briefDigest(input.brief),
+        body: input.body,
+        consulted: [...input.consulted],
+        ...independenceFields(members, relation),
+    };
+}
+
+export interface CliAnalystCommand {
+    binary: string;
+    argv: readonly string[];
+    promptVia: 'stdin' | 'argv';
+}
+
+/**
+ * The spawn line of a `cli:<provider>` analyst, from the read-only analyst
+ * profile — never the seat bound. A member whose profile was refused or never
+ * probed has no analyst mode at all.
+ */
+export function cliAnalystCommand(member: string): CliAnalystCommand {
+    const b = ANALYST_BOUNDS.find((x) => x.member === member);
+    if (b === undefined || b.bound.length === 0) {
+        throw new AnalystError(`${member}: no probed read-only analyst profile in cli_agency_bounds.ts`);
+    }
+    return { binary: b.binary, argv: [...b.bound], promptVia: b.prompt_via };
+}
+
+/** Every reason a round's seed and deepen outputs are not independent. Empty means clean. */
+export function roundViolations(outputs: readonly AnalystOutput[]): string[] {
+    const out: string[] = [];
+    const first = outputs[0];
+    const ids = new Set(outputs.map((o) => o.analyst_id));
+    for (const o of outputs) {
+        if (first !== undefined && o.brief_digest !== first.brief_digest) {
+            out.push(`${o.analyst_id} (${o.phase}) ran on a different brief than ${first.analyst_id}`);
+        }
+        for (const c of o.consulted) {
+            if (c !== o.analyst_id && ids.has(c)) out.push(`${o.analyst_id} (${o.phase}) consulted ${c} before the exchange`);
+        }
+        if (o.mode === 'subagent' && o.review_independence === 'cross-family') {
+            out.push(`${o.analyst_id} is a subagent stamped cross-family`);
+        }
+    }
+    return out;
+}
+
+export interface Handoff {
+    analyst_id: string;
+    file: string;
+    phase: HandoffPhase;
+    loop: number;
+    pin: string;
+    family: string | undefined;
+    consolidates: string[];
+    body: string;
+}
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
+
+export function parseHandoff(text: string, file: string): Handoff {
+    const m = FRONTMATTER_RE.exec(text);
+    if (m === null) throw new AnalystError(`${file}: no frontmatter`);
+    const fm = (parseYaml(m[1] as string) ?? {}) as Record<string, unknown>;
+    if (fm['handoff'] !== 'v1') throw new AnalystError(`${file}: handoff must be v1, got ${JSON.stringify(fm['handoff'])}`);
+    const phase = fm['phase'];
+    if (!HANDOFF_PHASES.includes(phase as HandoffPhase)) {
+        throw new AnalystError(`${file}: phase must be one of ${HANDOFF_PHASES.join(', ')}`);
+    }
+    const loop = fm['loop'];
+    if (typeof loop !== 'number' || !Number.isInteger(loop) || loop < 0) throw new AnalystError(`${file}: loop must be an integer`);
+    const pin = fm['pin'];
+    if (typeof pin !== 'string' || pin.length === 0) throw new AnalystError(`${file}: pin is required`);
+    const consolidates = Array.isArray(fm['consolidates']) ? fm['consolidates'].map(String) : [];
+    return {
+        analyst_id: `ext:${path.basename(file, '.md')}`,
+        file,
+        phase: phase as HandoffPhase,
+        loop,
+        pin,
+        family: typeof fm['family'] === 'string' ? fm['family'] : undefined,
+        consolidates,
+        body: m[2] as string,
+    };
+}
+
+/**
+ * Reads the owner's drops for one round. Source names live only in
+ * `*.annex.md`, which is never an output; anything else without a valid
+ * `handoff: v1` header is skipped with its reason rather than guessed at.
+ */
+export function readExternalDrops(
+    projectRoot: string,
+    roundId: string,
+    /** The run's pinned commit; a drop pinned elsewhere is skipped, never read as current. */
+    expectedPin?: string,
+): { handoffs: Handoff[]; skipped: Array<{ file: string; reason: string }> } {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(roundId) || roundId.includes('..')) {
+        throw new AnalystError(`round id ${JSON.stringify(roundId)} is not a single folder name`);
+    }
+    const dir = path.join(projectRoot, DROPS_REL, roundId);
+    if (!fs.existsSync(dir)) return { handoffs: [], skipped: [] };
+    const handoffs: Handoff[] = [];
+    const skipped: Array<{ file: string; reason: string }> = [];
+    for (const file of fs.readdirSync(dir).sort()) {
+        if (!file.endsWith('.md') || file.endsWith('.annex.md')) continue;
+        try {
+            const h = parseHandoff(fs.readFileSync(path.join(dir, file), 'utf8'), file);
+            if (expectedPin !== undefined && h.pin !== expectedPin) {
+                throw new AnalystError(`${file}: pinned to ${h.pin}, the run is pinned to ${expectedPin}`);
+            }
+            handoffs.push(h);
+        } catch (err) {
+            skipped.push({ file, reason: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    return { handoffs, skipped };
+}

package/src/scripts/analysis_anchors.ts

@@ -0,0 +1,140 @@
+/**
+ * analysis_anchors.ts — the anchor table of the analysis doors for any project
+ * (step 4.3, ADR-288): what the scope already says is wrong or wanted, read in
+ * a fixed order, each row typed so an opportunity is never presented as a
+ * defect.
+ *
+ * Order: skipped tests, open issues (passed in; the door reads them with `gh`
+ * when present), the FIXME/TODO census, open roadmap steps, ADRs, then
+ * `docs/CLAIMS.md`. A scope carrying `docs/CLAIMS.md` keeps this package's own
+ * profile (the door's § 1b). No row at all → feature mode, anchored on
+ * `--goal`; without one the door has to ask for it.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export const ANCHOR_TYPES = [
+    'defect',
+    'capability_gap',
+    'product_opportunity',
+    'maintainability',
+    'security',
+    'performance',
+] as const;
+export type AnchorType = (typeof ANCHOR_TYPES)[number];
+
+export const SOURCE_ORDER = ['skipped-tests', 'issues', 'todo-fixme', 'roadmaps', 'adrs', 'claims'] as const;
+export const MAX_ROWS_PER_SOURCE = 50;
+
+export interface AnchorRow {
+    type: AnchorType;
+    source: 'skipped-test' | 'issue' | 'fixme' | 'todo' | 'roadmap' | 'goal';
+    anchor: string;
+    text: string;
+}
+
+export interface Issue {
+    number: number;
+    title: string;
+    labels: string[];
+}
+
+export interface AnchorTable {
+    profile: 'package' | 'consumer';
+    mode: 'anchored' | 'feature' | 'feature-needs-goal';
+    rows: AnchorRow[];
+    sources_read: string[];
+    /** ADR files present — decisions the rows must not contradict, never rows themselves. */
+    adrs: number;
+}
+
+const SKIP_DIRS = new Set(['node_modules', 'vendor', 'dist', 'build', 'coverage', 'target', 'out']);
+const TEXT_EXT = /\.(ts|tsx|js|jsx|mjs|cjs|py|php|rb|go|rs|java|kt|swift|cs|c|h|cpp|vue|svelte|sh)$/;
+const TEST_FILE = /(\.|_)(test|spec)\.[a-z]+$|^test_.*\.py$|Test\.php$/;
+const SKIPPED = /\b(?:it|test|describe)\.skip\(|\bxit\(|@pytest\.mark\.skip|markTestSkipped\(|\bt\.Skip\(/;
+const MARKER = /\b(FIXME|TODO)\b[:(]?\s*(.*)$/;
+
+/** Every non-hidden file under `root`, relative and sorted, skipping build and dependency trees. */
+export function walk(root: string, rel = ''): string[] {
+    const out: string[] = [];
+    for (const entry of fs.readdirSync(path.join(root, rel), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (entry.name.startsWith('.') || SKIP_DIRS.has(entry.name)) continue;
+        const r = rel === '' ? entry.name : `${rel}/${entry.name}`;
+        if (entry.isDirectory()) out.push(...walk(root, r));
+        else if (entry.isFile()) out.push(r);
+    }
+    return out;
+}
+
+function lines(root: string, rel: string): string[] {
+    return fs.readFileSync(path.join(root, rel), 'utf8').split('\n');
+}
+
+export function typeIssue(labels: readonly string[]): AnchorType {
+    const l = labels.map((x) => x.toLowerCase());
+    if (l.some((x) => x.includes('security'))) return 'security';
+    if (l.some((x) => x === 'bug' || x.includes('defect') || x.includes('regression'))) return 'defect';
+    if (l.some((x) => x.includes('perf'))) return 'performance';
+    if (l.some((x) => x.includes('debt') || x.includes('refactor') || x.includes('cleanup'))) return 'maintainability';
+    return 'product_opportunity';
+}
+
+export function buildAnchorTable(input: { root: string; goal?: string; issues?: readonly Issue[] }): AnchorTable {
+    const { root } = input;
+    const files = walk(root);
+    const code = files.filter((f) => TEXT_EXT.test(f));
+    const cap = (rows: AnchorRow[]): AnchorRow[] => rows.slice(0, MAX_ROWS_PER_SOURCE);
+
+    const skipped: AnchorRow[] = [];
+    for (const f of code.filter((x) => TEST_FILE.test(path.basename(x)) || x.split('/').includes('tests'))) {
+        lines(root, f).forEach((line, i) => {
+            if (SKIPPED.test(line)) skipped.push({ type: 'defect', source: 'skipped-test', anchor: `${f}:${String(i + 1)}`, text: line.trim() });
+        });
+    }
+
+    const issues: AnchorRow[] = (input.issues ?? []).map((i) => ({
+        type: typeIssue(i.labels),
+        source: 'issue',
+        anchor: `#${String(i.number)}`,
+        text: i.title,
+    }));
+
+    const markers: AnchorRow[] = [];
+    for (const f of code) {
+        lines(root, f).forEach((line, i) => {
+            const m = MARKER.exec(line);
+            if (m === null) return;
+            const fixme = m[1] === 'FIXME';
+            markers.push({
+                type: fixme ? 'defect' : 'maintainability',
+                source: fixme ? 'fixme' : 'todo',
+                anchor: `${f}:${String(i + 1)}`,
+                text: (m[2] ?? '').trim(),
+            });
+        });
+    }
+
+    const roadmaps: AnchorRow[] = [];
+    for (const f of files.filter((x) => /^agents\/roadmaps\/[^/]+\.md$/.test(x))) {
+        lines(root, f).forEach((line, i) => {
+            if (/^- \[ \] /.test(line)) {
+                roadmaps.push({ type: 'capability_gap', source: 'roadmap', anchor: `${f}:${String(i + 1)}`, text: line.slice(6).trim() });
+            }
+        });
+    }
+
+    const adrs = files.filter((x) => /^docs\/(decisions|adrs?)\/.+\.md$/.test(x) && !/(INDEX|README)\.md$/.test(x)).length;
+    const profile = fs.existsSync(path.join(root, 'docs/CLAIMS.md')) ? 'package' : 'consumer';
+    const rows = [...cap(skipped), ...cap(issues), ...cap(markers), ...cap(roadmaps)];
+
+    if (rows.length > 0) return { profile, mode: 'anchored', rows, sources_read: [...SOURCE_ORDER], adrs };
+    const goal = input.goal?.trim();
+    if (goal === undefined || goal === '') return { profile, mode: 'feature-needs-goal', rows: [], sources_read: [...SOURCE_ORDER], adrs };
+    return {
+        profile,
+        mode: 'feature',
+        rows: [{ type: 'product_opportunity', source: 'goal', anchor: '--goal', text: goal }],
+        sources_read: [...SOURCE_ORDER],
+        adrs,
+    };
+}

package/src/scripts/analysis_and_optimize.ts

@@ -0,0 +1,44 @@
+/**
+ * analysis_and_optimize.ts — what `analyze:and-optimize` reads (step 4.5,
+ * ADR-288 D1).
+ *
+ * The door's scope is the one `analysis_target.ts` resolved, never a path the
+ * caller names: inside a module every reader — the anchor table and the code
+ * the analysts open — stays under the module root, while `project_root` stays
+ * the outer project for settings and publication. The read set includes code,
+ * not only roadmaps and ADRs.
+ */
+import * as path from 'node:path';
+
+import { buildAnchorTable, walk, type AnchorTable, type Issue } from './analysis_anchors.js';
+import { isInside, type AnalysisTarget } from './analysis_target.js';
+
+const CODE_EXT = /\.(ts|tsx|js|jsx|mjs|cjs|py|php|rb|go|rs|java|kt|swift|cs|c|h|cpp|vue|svelte|sh)$/;
+
+export interface ReadSet {
+    scope_root: string;
+    anchors: AnchorTable;
+    /** Absolute paths of the code files the analysts read. */
+    code: string[];
+    /** Every absolute path a reader of this run opens. */
+    readers: string[];
+}
+
+export function readSet(target: AnalysisTarget, opts: { goal?: string; issues?: readonly Issue[] } = {}): ReadSet {
+    const root = target.scope_root;
+    const anchors = buildAnchorTable({
+        root,
+        ...(opts.goal === undefined ? {} : { goal: opts.goal }),
+        ...(opts.issues === undefined ? {} : { issues: opts.issues }),
+    });
+    const code = walk(root)
+        .filter((f) => CODE_EXT.test(f))
+        .map((f) => path.join(root, f));
+    const anchored = anchors.rows
+        .filter((r) => r.source !== 'issue' && r.source !== 'goal')
+        .map((r) => path.join(root, r.anchor.replace(/:\d+$/u, '')));
+    const readers = [...new Set([...code, ...anchored])].sort();
+    const escaped = readers.filter((p) => !isInside(p, root));
+    if (escaped.length > 0) throw new Error(`reader outside the scope root ${root}: ${escaped.join(', ')}`);
+    return { scope_root: root, anchors, code, readers };
+}

package/src/scripts/analysis_emit.ts

@@ -0,0 +1,150 @@
+/**
+ * analysis_emit.ts — turns a round's surviving findings into what lands
+ * locally: owner-first arrivals on existing roadmaps, and at most one new
+ * central roadmap with every other finding as a phase.
+ *
+ * Owner-first is the growth cap: a finding whose subject already has a
+ * roadmap becomes a step plus an `Arrivals:` line there, so a round adds at
+ * most one file to the estate. New roadmaps land `ready`, except above the
+ * harvest intake limit, where they land `draft` and the run says so in one
+ * line. Nothing here validates or writes; `analysis_validate.ts` gates the
+ * result before anything leaves the machine.
+ */
+import type { EvidenceTier } from './analysis_ledger.js';
+
+/** More `ready` roadmaps than this at 0 ticked steps make a new roadmap land `draft`. */
+export const INTAKE_LIMIT = 8;
+
+export interface FindingStep {
+    text: string;
+    verify: string;
+}
+
+export interface Finding {
+    id: string;
+    title: string;
+    claim: string;
+    anchor: string;
+    tier: EvidenceTier;
+    steps: FindingStep[];
+    /** Slug (without `road-to-`) of the roadmap that already owns the subject. */
+    owner?: string;
+    blocked_until?: string;
+}
+
+export interface EmittedRoadmap {
+    slug: string;
+    status: 'ready' | 'draft';
+    body: string;
+}
+
+export interface Arrival {
+    slug: string;
+    finding_id: string;
+    step: string;
+    arrivals_line: string;
+}
+
+export interface EmitResult {
+    roadmaps: EmittedRoadmap[];
+    arrivals: Arrival[];
+    estate_delta: number;
+    status_note: string | null;
+}
+
+export interface EmitInput {
+    roundId: string;
+    date: string;
+    slug: string;
+    findings: readonly Finding[];
+    readyAtZero: number;
+    intakeLimit?: number;
+    /** The phase number an arrival opens in its owner roadmap; needed when any finding has an owner. */
+    ownerNextPhase?: (slug: string) => number | null;
+}
+
+function stepLines(n: string, step: FindingStep): string {
+    return `- [ ] **${n} ${step.text}.**\n      verify: ${step.verify}`;
+}
+
+function phaseHeading(i: number, f: Finding): string {
+    return `Phase ${String(i + 1)} — ${f.title}`;
+}
+
+function roadmapBody(input: EmitInput, findings: readonly Finding[], status: 'ready' | 'draft'): string {
+    const phases = findings.map((f, i) => {
+        const steps = f.steps.map((s, k) => stepLines(`${String(i + 1)}.${String(k + 1)}`, s)).join('\n');
+        const blocked = f.blocked_until === undefined ? '' : `> Blocked until ${f.blocked_until}.\n\n`;
+        return `## ${phaseHeading(i, f)}\n\n${f.claim} Evidence (${f.tier}): \`${f.anchor}\`.\n\n${blocked}${steps}\n`;
+    });
+    const risks = findings.map(
+        (f, i) =>
+            `| ${String(i + 1)} | ${f.title} not delivered | implementation | The claim at \`${f.anchor}\` still holds after the phase | each step carries its \`verify:\` line | ${phaseHeading(i, f)} |`,
+    );
+    const acs = findings.map(
+        (f, i) => `- [ ] AC-${String(i + 1)} — ${f.title}: the claim of Phase ${String(i + 1)} no longer holds at the tree.`,
+    );
+    return [
+        '---',
+        'complexity: lightweight',
+        `status: ${status}`,
+        'execution:',
+        '  mode: phase-checkpoints',
+        '---',
+        `# Road to ${input.slug.replace(/-/g, ' ')}`,
+        '',
+        `> **Source:** analysis round \`${input.roundId}\` (${input.date}).`,
+        '',
+        '## Goal',
+        '',
+        `Every finding of round \`${input.roundId}\` below is resolved against the tree.`,
+        '',
+        ...phases,
+        '## Risk Register',
+        `<!-- risk-review: v1 | reviewed: ${input.date} | reviewer: claude/host -->`,
+        '',
+        '| Rank | Item | Risk type | Description | Mitigation | Anchored under |',
+        '|------|------|-----------|-------------|------------|----------------|',
+        ...risks,
+        '',
+        '## Acceptance Criteria',
+        '',
+        ...acs,
+        '',
+    ].join('\n');
+}
+
+export function emitRound(input: EmitInput): EmitResult {
+    const limit = input.intakeLimit ?? INTAKE_LIMIT;
+    const owned = input.findings.filter((f) => f.owner !== undefined);
+    const fresh = input.findings.filter((f) => f.owner === undefined);
+
+    const arrivals = owned.map((f) => {
+        const slug = f.owner as string;
+        // A literal placeholder would land in the owner roadmap as its step id.
+        const phase = input.ownerNextPhase?.(slug) ?? null;
+        if (phase === null || !Number.isInteger(phase) || phase < 1) {
+            throw new Error(`analysis_emit: no next phase number for owner roadmap road-to-${slug} (finding ${f.id})`);
+        }
+        return {
+            slug,
+            finding_id: f.id,
+            step: f.steps.map((s, k) => stepLines(`${String(phase)}.${String(k + 1)}`, s)).join('\n'),
+            arrivals_line: `> **Arrivals:** latest \`${input.roundId}\` (${input.date}) — ${f.id}`,
+        };
+    });
+
+    if (fresh.length === 0) return { roadmaps: [], arrivals, estate_delta: 0, status_note: null };
+
+    const draft = input.readyAtZero > limit;
+    const status = draft ? 'draft' : 'ready';
+    const status_note = draft
+        ? `draft: ${String(input.readyAtZero)} ready roadmaps sit at 0 ticked steps, above the intake limit of ${String(limit)}`
+        : null;
+    return {
+        roadmaps: [{ slug: input.slug, status, body: roadmapBody(input, fresh, status) }],
+        arrivals,
+        estate_delta: 1,
+        status_note,
+    };
+}