@event4u/agent-config 16.5.0 → 17.0.0

package/src/scripts/ai_council/seat_resume.ts

@@ -0,0 +1,40 @@
+/**
+ * Whether a council seat continues its CLI session — road-to-a-cold-start-paid-once 5.2.
+ *
+ * Only a non-blind follow-up to the same seat resumes, and only inside the
+ * window the provider's prompt cache lives for. A blind round never resumes:
+ * the session holds the reviewer's earlier position, and an anonymised round
+ * exists precisely so the reviewer cannot recognise it.
+ */
+
+export interface SeatSession {
+    readonly id: string;
+    readonly at_ms: number;
+}
+
+/** The prompt-cache lifetime a resume is worth paying for. */
+export const SEAT_RESUME_TTL_MS = 5 * 60_000;
+
+/** Extra argv for a resumed call; `[]` means a fresh session. */
+export function seatResumeArgs(
+    provider: string,
+    session: SeatSession | null,
+    ctx: { readonly blind: boolean; readonly now_ms: number; readonly ttl_ms?: number },
+): string[] {
+    if (ctx.blind || session === null || session.id === '') return [];
+    const age = ctx.now_ms - session.at_ms;
+    if (age < 0 || age >= (ctx.ttl_ms ?? SEAT_RESUME_TTL_MS)) return [];
+    if (provider === 'anthropic') return ['--resume', session.id];
+    if (provider === 'openai') return ['resume', session.id];
+    return [];
+}
+
+/**
+ * `codex exec resume` refuses `--sandbox` (measured on codex-cli 0.148.0), so a
+ * resumed seat carries the same bound as a config override instead of dropping it.
+ */
+export function resumeBound(bound: readonly string[]): string[] {
+    const i = bound.indexOf('--sandbox');
+    if (i < 0 || bound[i + 1] === undefined) return [...bound];
+    return [...bound.slice(0, i), '-c', `sandbox_mode="${bound[i + 1]}"`, ...bound.slice(i + 2)];
+}

package/src/scripts/ai_council/shadow_dispatch.ts

@@ -18,7 +18,9 @@
 import * as fs from 'node:fs';
 
 import type { PyRandom } from '../_lib/py_random.js';
+import { parseTokens } from '../_lib/egress_token.js';
 import { redact } from './bundler.js';
+import { CouncilEgress } from './council_egress.js';
 import { createHash } from 'node:crypto';
 
 export const SHADOW_LOG_PATH = 'agents/runtime/council/shadow-log.jsonl';
@@ -67,8 +69,14 @@ const _defaultRandom: RandomLike = {
     },
 };
 
+// Shadow rows are this module's own record, not a council request: a scope of
+// their own keeps them out of the run's final-check state.
+function _redact(query: string): string {
+    return redact(query, new CouncilEgress());
+}
+
 function _hashQuery(query: string): string {
-    const redacted = redact(query);
+    const redacted = _redact(query);
     return createHash('sha256').update(Buffer.from(redacted, 'utf-8')).digest('hex').slice(0, 16);
 }
 
@@ -77,7 +85,9 @@ function _privacyDropped(redacted: string): boolean {
     if (!stripped) {
         return true;
     }
-    return stripped.startsWith('[redacted');
+    // Any replaced value drops the row: a placeholder in a shadow query means the
+    // query carried something the bundler would not send.
+    return parseTokens(redacted).length > 0;
 }
 
 export interface RecordShadowDecisionOptions {
@@ -106,7 +116,7 @@ export function record_shadow_decision(
     const escalated = opts.escalated ?? false;
     const escalationReason = opts.escalationReason ?? 'ok';
 
-    const redactedQ = redact(query);
+    const redactedQ = _redact(query);
     if (_privacyDropped(redactedQ)) {
         return null;
     }

package/src/scripts/ai_council/spend_gate.ts

@@ -58,7 +58,7 @@ export class OverrunEvent {
     projected_total_usd: number; // spent_usd + next_estimate.total_usd
     daily_spent_usd: number; // rolling 24h spend BEFORE this member (D3)
     daily_limit_usd: number; // the configured daily cap (0 = disabled)
-    breach_kind: string; // "session" | "daily" | "tokens"
+    breach_kind: string; // "session" | "daily" | "tokens" | "unpriced"
 
     constructor(args: {
         member_index: number;
@@ -91,12 +91,25 @@ export function _total_usd(e: CostEstimate): number {
     return e.input_usd + e.output_usd;
 }
 
-export type BreachKind = 'tokens' | 'daily' | 'session' | null;
+export type BreachKind = 'tokens' | 'unpriced' | 'daily' | 'session' | null;
+
+/** The error a refused seat carries. `unpriced` is named apart so the report says why. */
+export function breachErrorTag(kind: Exclude<BreachKind, null>): string {
+    if (kind === 'daily') return 'daily_budget_exceeded';
+    if (kind === 'unpriced') return 'cost_budget_unpriced';
+    return 'cost_budget_exceeded';
+}
 
 /**
  * The projected-spend verdict. One implementation because the round head and
  * the fallback's metered retry must gate on the SAME rules — two copies of
  * four comparisons is how they drift.
+ *
+ * Both callers reach it only for a BILLABLE seat (a non-billable one skips the
+ * gate in `orchestrator.ts`), which is what makes `unpriced` a refusal: under a
+ * USD ceiling a person set, an estimate with no price row is not $0, it is
+ * unknown, and a ceiling an unknown passes is not that ceiling (D2). With no
+ * USD ceiling set nothing here changes (ADR-279).
  */
 export function _breach(
     est: CostEstimate | null,
@@ -118,6 +131,9 @@ export function _breach(
     ) {
         return 'tokens';
     }
+    if (est && !est.priced && (budget.daily_limit_usd > 0 || budget.max_total_usd > 0)) {
+        return 'unpriced';
+    }
     if (budget.daily_limit_usd > 0 && _would_exceed_daily(budget.daily_limit_usd, usd)) {
         return 'daily';
     }

package/src/scripts/ai_council/status_surface.ts

@@ -16,6 +16,8 @@
 import type { EnvironmentReport } from '../_lib/environment_detector.js';
 import { detectEnvironment } from '../_lib/environment_detector.js';
 import { DEFAULT_SEAT_CEILING, type ContentClass } from './content_ceiling.js';
+import { resolve_api_key } from './config.js';
+import { resolveRouteTransport, type RouteSpec } from './free_route.js';
 import type { PolicyExclusion } from './seat_policy.js';
 import { resolveMemberTransport } from './transport_resolver.js';
 
@@ -24,6 +26,8 @@ interface SeatLike {
     readonly api_key_ref: string | null;
     readonly policy_exclusion?: PolicyExclusion | null;
     readonly content_ceiling?: ContentClass;
+    readonly route?: RouteSpec | null;
+    readonly model?: string;
 }
 
 interface ConfigLike {
@@ -46,6 +50,16 @@ export function resolvedTransportFor(
     report?: EnvironmentReport,
     contentClass?: ContentClass | null,
 ): ReturnType<typeof resolveMemberTransport> {
+    if (member.route !== undefined && member.route !== null) {
+        const resolved = resolveRouteTransport({
+            name,
+            route: member.route,
+            model: member.model ?? '',
+            contentClass: contentClass ?? null,
+            keyPresent: keyResolves(member.api_key_ref),
+        });
+        return { ...resolved, configuredMode: 'api' };
+    }
     return resolveMemberTransport({
         provider: name,
         report: report ?? detectEnvironment(),
@@ -77,3 +91,26 @@ export function disabledSeats(cfg: ConfigLike | null): Record<string, string> {
     );
 }
 
+
+/** True when `ref` resolves to a non-empty key right now. */
+export function keyResolves(ref: string | null): boolean {
+    if (ref === null) return false;
+    try {
+        return resolve_api_key(ref) !== '';
+    } catch {
+        return false;
+    }
+}
+
+/** One `route` line per route member: where it points and how it bills. */
+export function routeStatusLines(
+    members: readonly (readonly [string, SeatLike])[],
+    report?: EnvironmentReport,
+): string[] {
+    return members
+        .filter(([, m]) => m.route !== undefined && m.route !== null)
+        .map(([n, m]) => {
+            const t = resolvedTransportFor(n, m, report, 'public-artifact');
+            return `  route            ${n}: ${m.route?.base_url ?? ''} · ${t.billing}`;
+        });
+}

package/src/scripts/ai_council/transport_resolver.ts

@@ -51,6 +51,7 @@ import {
 import { resolve_mode } from './modes.js';
 import {
     admitsContent,
+    DEFAULT_CONTENT_CLASS,
     DEFAULT_SEAT_CEILING,
     type ContentClass,
 } from './content_ceiling.js';
@@ -134,10 +135,7 @@ export interface ResolveTransportOptions {
     readonly policyExclusion?: PolicyExclusion | null;
     /** The seat's content ceiling (2.2). Defaults to `project-content`. */
     readonly seatCeiling?: ContentClass | null;
-    /**
-     * The class of what this pass would send. Omitted → no content check runs,
-     * which is what keeps every existing caller's behaviour identical.
-     */
+    /** The class of what this pass would send. Omitted → `project-content`. */
     readonly contentClass?: ContentClass | null;
 }
 
@@ -197,19 +195,17 @@ export function resolveTransport(opts: ResolveTransportOptions): ResolvedTranspo
     if (exclusion !== null) {
         return unavailable(provider, billing, policyExclusionReason(exclusion, provider), exclusion);
     }
-    // Content ceiling (2.2). Only runs when the caller declared what it would
-    // send; an undeclared pass is unchanged, not silently refused.
-    const contentClass = opts.contentClass ?? null;
-    if (contentClass !== null) {
-        const verdict = admitsContent(opts.seatCeiling ?? DEFAULT_SEAT_CEILING, contentClass);
-        if (!verdict.admitted) {
-            return unavailable(
-                provider,
-                billing,
-                `${provider}: ${verdict.reason ?? 'content ceiling refused the payload'}`,
-                'policy_content_ceiling',
-            );
-        }
+    // Content ceiling (2.2). An undeclared payload is project-content: a seat
+    // cleared only for public artefacts refuses it, and a default seat is unchanged.
+    const contentClass = opts.contentClass ?? DEFAULT_CONTENT_CLASS;
+    const verdict = admitsContent(opts.seatCeiling ?? DEFAULT_SEAT_CEILING, contentClass);
+    if (!verdict.admitted) {
+        return unavailable(
+            provider,
+            billing,
+            `${provider}: ${verdict.reason ?? 'content ceiling refused the payload'}`,
+            'policy_content_ceiling',
+        );
     }
 
     if (mode === 'manual') {
@@ -538,7 +534,8 @@ export function classifyCliFailure(raw: string): CliFailureClass {
     if (s === 'auth_expired' || s === 'auth_rejected' || s === 'unauthorized') {
         return 'auth_rejected';
     }
-    if (s === 'cli_unsupported' || s === 'unsupported' || s === 'parse_failed') {
+    // `parse_failed` is NOT here: answered-unreadably, so a replay pays twice.
+    if (s === 'cli_unsupported' || s === 'unsupported') {
         return 'cli_unsupported';
     }
     // Prefix match, not equality: the detail carries the operator-facing reason

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 };
+}