@ai-sdlc/orchestrator 0.5.0 → 0.9.0

package/dist/backlog-adapter.js

@@ -0,0 +1,438 @@
+/**
+ * Backlog.md tracker adapter for the admission composite.
+ *
+ * Backlog.md tasks are markdown files in `backlog/tasks/` (open) or
+ * `backlog/completed/` (archived). They carry YAML frontmatter
+ * (`id`, `title`, `status`, `priority`, `labels`, `references`,
+ * `created_date`, `updated_date`, `assignee`) plus a body that
+ * includes a `## Acceptance Criteria` checklist.
+ *
+ * This module:
+ *   1. Parses a task file into `BacklogTaskSnapshot`
+ *   2. Maps the snapshot onto `AdmissionInput` using the conventions
+ *      in the bug-fix doc (priority:p* / size:[SML] / track:* / etc.)
+ *   3. Emits `qualityFlags` for "Done with unchecked ACs" zombie closes
+ *
+ * The GitHub-shaped `mapIssueToPriorityInput` in `admission-score.ts`
+ * is left intact; the dispatch sits in `cli-admit`.
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { normalizeBacklogPriority } from './admission-score.js';
+// ── Parser ──────────────────────────────────────────────────────────
+/**
+ * Parse a Backlog.md task markdown file into `BacklogTaskSnapshot`.
+ * Throws when the frontmatter is missing or malformed.
+ */
+export function parseBacklogTask(content, sourcePath) {
+    const fm = extractFrontmatter(content);
+    if (!fm)
+        throw new Error('Backlog task is missing YAML frontmatter');
+    const id = String(fm.id ?? '').trim();
+    if (!id)
+        throw new Error('Backlog task frontmatter is missing `id`');
+    const numericId = parseNumericId(id);
+    const labels = normaliseLabels(fm.labels);
+    const references = normaliseStringArray(fm.references);
+    const dependencies = normaliseStringArray(fm.dependencies);
+    const description = extractSection(content, 'Description');
+    const acceptanceCriteria = extractAcceptanceCriteria(content);
+    return {
+        id,
+        numericId,
+        title: String(fm.title ?? '').trim(),
+        description,
+        status: String(fm.status ?? '').trim(),
+        priority: fm.priority == null ? null : String(fm.priority).trim(),
+        labels,
+        createdDate: String(fm.created_date ?? '').trim(),
+        updatedDate: String(fm.updated_date ?? '').trim(),
+        createdBy: fm.created_by ? String(fm.created_by).trim() : undefined,
+        acceptanceCriteria,
+        references,
+        dependencies,
+        sourcePath,
+    };
+}
+/**
+ * Resolve a Backlog task id ("AISDLC-42" or "task-42") to a snapshot
+ * by searching the `backlog/tasks/` and `backlog/completed/` directories
+ * under `backlogRoot` (typically the project root).
+ */
+export function loadBacklogTaskFromRoot(backlogRoot, id) {
+    const idLower = id.toLowerCase();
+    const candidates = [
+        join(backlogRoot, 'backlog', 'tasks'),
+        join(backlogRoot, 'backlog', 'completed'),
+    ];
+    for (const dir of candidates) {
+        if (!existsSync(dir))
+            continue;
+        for (const entry of readdirSync(dir)) {
+            if (!entry.toLowerCase().startsWith(`${idLower} `) &&
+                !entry.toLowerCase().startsWith(`${idLower}.`)) {
+                continue;
+            }
+            const path = join(dir, entry);
+            const content = readFileSync(path, 'utf-8');
+            return parseBacklogTask(content, path);
+        }
+    }
+    return undefined;
+}
+// ── Frontmatter helpers (no external YAML dep — handle the subset
+// Backlog.md emits: scalar, sequence, null, "Done"-quoted strings) ──
+function extractFrontmatter(content) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match)
+        return undefined;
+    return parseSimpleYaml(match[1]);
+}
+function parseSimpleYaml(src) {
+    const out = {};
+    const lines = src.split(/\r?\n/);
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (!line.trim() || line.trim().startsWith('#')) {
+            i++;
+            continue;
+        }
+        const m = line.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*:\s*(.*)$/);
+        if (!m) {
+            i++;
+            continue;
+        }
+        const key = m[1];
+        let value = m[2].trim();
+        if (value === '' || value === '[]') {
+            // Inline empty or block sequence follows.
+            const seq = [];
+            let j = i + 1;
+            while (j < lines.length && /^\s+-\s+/.test(lines[j])) {
+                seq.push(lines[j]
+                    .replace(/^\s+-\s+/, '')
+                    .trim()
+                    .replace(/^['"]|['"]$/g, ''));
+                j++;
+            }
+            out[key] = value === '[]' ? [] : seq.length > 0 ? seq : '';
+            i = j;
+            continue;
+        }
+        // Strip wrapping quotes if present.
+        if ((value.startsWith("'") && value.endsWith("'")) ||
+            (value.startsWith('"') && value.endsWith('"'))) {
+            value = value.slice(1, -1);
+        }
+        out[key] = value;
+        i++;
+    }
+    return out;
+}
+function normaliseLabels(raw) {
+    if (Array.isArray(raw))
+        return raw.map((s) => String(s).trim()).filter(Boolean);
+    if (typeof raw === 'string' && raw.trim())
+        return [raw.trim()];
+    return [];
+}
+function normaliseStringArray(raw) {
+    if (Array.isArray(raw))
+        return raw.map((s) => String(s).trim()).filter(Boolean);
+    return [];
+}
+function parseNumericId(id) {
+    const m = id.match(/(\d+)$/);
+    return m ? Number(m[1]) : 0;
+}
+function extractSection(content, name) {
+    // Match `## <name>` until the next `## ` header or end of file.
+    const re = new RegExp(`##\\s+${name}[\\s\\S]*?(?=\\n##\\s|$)`, 'i');
+    const match = content.match(re);
+    if (!match)
+        return '';
+    return match[0].replace(/^##\s+\S+\s*/i, '').trim();
+}
+function extractAcceptanceCriteria(content) {
+    const section = extractSection(content, 'Acceptance Criteria');
+    if (!section)
+        return [];
+    const out = [];
+    for (const line of section.split(/\r?\n/)) {
+        const m = line.match(/^\s*-\s+\[([ x])\]\s+(?:#(\d+)\s+)?(.*)$/i);
+        if (!m)
+            continue;
+        out.push({
+            index: m[2] ? Number(m[2]) : out.length + 1,
+            checked: m[1].toLowerCase() === 'x',
+            text: m[3].trim(),
+        });
+    }
+    return out;
+}
+const DEFAULT_SOUL_TRACKS = {
+    // Generic defaults — projects override via `.ai-sdlc/soul-tracks.json`.
+    'track:ops': 0.55,
+    'track:infra': 0.55,
+    'track:hygiene': 0.55,
+};
+/**
+ * Map a Backlog snapshot onto an `AdmissionInput` plus the
+ * `PriorityInput` overrides cli-admit feeds into the composite.
+ * The label-mapping table is the load-bearing piece; tests in
+ * `backlog-adapter.test.ts` pin each row.
+ */
+export function mapBacklogTaskToAdmissionInput(snap, options = {}) {
+    const labels = snap.labels;
+    const labelSet = new Set(labels.map((l) => l.toLowerCase()));
+    const tracks = { ...DEFAULT_SOUL_TRACKS, ...(options.soulTracks ?? {}) };
+    const authorAssociation = snap.createdBy && options.maintainers?.includes(snap.createdBy) ? 'OWNER' : 'MEMBER';
+    // Defaults — overridden below as labels apply.
+    let soulAlignment = 0.5;
+    let bugSeverity;
+    let complexity;
+    // ── Priority labels → explicit priority signal ────────────────
+    // priority:p0..p3 + frontmatter `priority:` field.
+    let explicitPriority;
+    if (labelSet.has('priority:p0'))
+        explicitPriority = 1.0;
+    else if (labelSet.has('priority:p1'))
+        explicitPriority = 0.75;
+    else if (labelSet.has('priority:p2'))
+        explicitPriority = 0.5;
+    else if (labelSet.has('priority:p3'))
+        explicitPriority = 0.25;
+    else if (snap.priority?.toLowerCase() === 'high')
+        explicitPriority = 0.75;
+    else if (snap.priority?.toLowerCase() === 'medium')
+        explicitPriority = 0.5;
+    else if (snap.priority?.toLowerCase() === 'low')
+        explicitPriority = 0.25;
+    // ── Size labels → complexity ─────────────────────────────────
+    if (labelSet.has('size:s'))
+        complexity = 2;
+    else if (labelSet.has('size:m'))
+        complexity = 5;
+    else if (labelSet.has('size:l'))
+        complexity = 7;
+    else if (labelSet.has('size:xl'))
+        complexity = 9;
+    // Otherwise derive from AC count below.
+    // ── Soul-alignment signals ────────────────────────────────────
+    if (labelSet.has('source:rfc') || labelSet.has('source:spec')) {
+        soulAlignment = Math.max(soulAlignment, 0.9);
+    }
+    if (labelSet.has('governance') || labelSet.has('compliance')) {
+        soulAlignment = Math.max(soulAlignment, 0.85);
+    }
+    for (const label of labels) {
+        const key = label.toLowerCase();
+        if (key.startsWith('track:') && tracks[key] !== undefined) {
+            soulAlignment = Math.max(soulAlignment, tracks[key]);
+        }
+    }
+    // ── Bug-class labels ──────────────────────────────────────────
+    if (labelSet.has('bug') || labelSet.has('regression') || labelSet.has('defect')) {
+        bugSeverity = 3;
+    }
+    if (labelSet.has('security') || labelSet.has('vulnerability')) {
+        bugSeverity = 5;
+        soulAlignment = Math.max(soulAlignment, 0.7);
+    }
+    if (labelSet.has('critical') || labelSet.has('p0')) {
+        bugSeverity = Math.max(bugSeverity ?? 0, 5);
+    }
+    // ── AC progress → complexity proxy + quality flags ───────────
+    const acTotal = snap.acceptanceCriteria.length;
+    const acChecked = snap.acceptanceCriteria.filter((a) => a.checked).length;
+    const acProgress = acTotal === 0 ? null : acChecked / acTotal;
+    if (complexity === undefined && acTotal > 0) {
+        // 1 AC → 1.6, 5 ACs → 4, 9 ACs → 6.4, 13 ACs → 8.8 (capped at 9).
+        complexity = Math.min(1 + acTotal * 0.6, 9);
+    }
+    const qualityFlags = [];
+    let defectRiskFactor;
+    const isZombieClose = snap.status.toLowerCase() === 'done' && acTotal > 0 && acProgress !== null && acProgress < 1.0;
+    if (isZombieClose) {
+        const severity = acProgress < 0.5 ? 'high' : 'medium';
+        qualityFlags.push({
+            kind: 'unchecked-acs-on-done',
+            detail: `${acTotal - acChecked}/${acTotal} ACs unchecked`,
+            severity,
+        });
+        defectRiskFactor = severity === 'high' ? 0.3 : 0.15;
+    }
+    // ── Demand / drift / consensus heuristics ─────────────────────
+    let demandSignal;
+    let competitiveDrift = 0;
+    for (const label of labels) {
+        const key = label.toLowerCase();
+        if (key.startsWith('source:') && key.includes('-tonight')) {
+            demandSignal = Math.max(demandSignal ?? 0, 0.7);
+            competitiveDrift += 0.2;
+        }
+        if (key === 'scope:v1-ship' || key === 'scope:v1') {
+            competitiveDrift += 0.6;
+        }
+    }
+    competitiveDrift = Math.min(competitiveDrift, 1);
+    // teamConsensus: someone is on the hook.
+    const teamConsensus = snap.createdBy ? 0.4 : undefined;
+    // builderConviction: anchored in references? Multiple references to
+    // existing files = author did the homework.
+    const builderConviction = snap.references.length >= 2 ? 0.7 : snap.references.length === 1 ? 0.6 : undefined;
+    // commentCount / reactionCount have no Backlog analog yet; default 0.
+    const reactionCount = 0;
+    const commentCount = 0;
+    // Construct the body the existing scorer expects (Description +
+    // Acceptance Criteria) — preserves the GitHub mapper's complexity
+    // regex for callers that bypass the Backlog mapping path.
+    const renderedBody = buildAdmissionBody(snap, complexity);
+    const input = {
+        issueNumber: snap.numericId,
+        title: snap.title,
+        body: renderedBody,
+        labels,
+        reactionCount,
+        commentCount,
+        createdAt: normaliseIsoDate(snap.createdDate),
+        authorAssociation,
+        authorLogin: snap.createdBy,
+        backlogContext: {
+            priority: normalizeBacklogPriority(snap.priority),
+            dependencyCount: snap.dependencies.length,
+            referenceCount: snap.references.length,
+            acceptanceCriteriaCount: snap.acceptanceCriteria.length,
+            status: snap.status,
+        },
+    };
+    const priorityInputOverrides = {};
+    if (soulAlignment !== 0.5)
+        priorityInputOverrides.soulAlignment = soulAlignment;
+    if (bugSeverity !== undefined)
+        priorityInputOverrides.bugSeverity = bugSeverity;
+    if (complexity !== undefined)
+        priorityInputOverrides.complexity = complexity;
+    if (explicitPriority !== undefined)
+        priorityInputOverrides.explicitPriority = explicitPriority;
+    if (demandSignal !== undefined)
+        priorityInputOverrides.demandSignal = demandSignal;
+    if (competitiveDrift > 0)
+        priorityInputOverrides.competitiveDrift = competitiveDrift;
+    if (teamConsensus !== undefined)
+        priorityInputOverrides.teamConsensus = teamConsensus;
+    if (builderConviction !== undefined)
+        priorityInputOverrides.builderConviction = builderConviction;
+    if (defectRiskFactor !== undefined)
+        priorityInputOverrides.defectRiskFactor = defectRiskFactor;
+    if (qualityFlags.length > 0)
+        priorityInputOverrides.qualityFlags = qualityFlags;
+    return { input, priorityInputOverrides, qualityFlags };
+}
+function buildAdmissionBody(snap, complexity) {
+    const parts = [];
+    if (snap.description)
+        parts.push(snap.description);
+    if (complexity !== undefined) {
+        parts.push('');
+        parts.push('### Complexity');
+        parts.push('');
+        parts.push(String(Math.round(complexity)));
+    }
+    if (snap.acceptanceCriteria.length > 0) {
+        parts.push('');
+        parts.push('### Acceptance Criteria');
+        parts.push('');
+        for (const ac of snap.acceptanceCriteria) {
+            parts.push(`- [${ac.checked ? 'x' : ' '}] ${ac.text}`);
+        }
+    }
+    return parts.join('\n');
+}
+function normaliseIsoDate(raw) {
+    // Backlog stores '2026-03-08 22:27' — coerce to ISO for `cli-admit`.
+    if (!raw)
+        return new Date().toISOString();
+    if (/T\d{2}:\d{2}/.test(raw))
+        return raw;
+    const m = raw.match(/^(\d{4}-\d{2}-\d{2})[\s T](\d{2}:\d{2})(?::(\d{2}))?$/);
+    if (!m)
+        return new Date(raw).toISOString();
+    return `${m[1]}T${m[2]}:${m[3] ?? '00'}Z`;
+}
+// ── Soul-tracks loader ─────────────────────────────────────────────
+/**
+ * Load `.ai-sdlc/soul-tracks.json` from the given config root.
+ * Format: `{ "track:enchantment": 0.85, "track:reflect": 0.85, ... }`.
+ * Missing file → empty object (caller falls back to DEFAULT_SOUL_TRACKS).
+ */
+export function loadSoulTracks(configRoot) {
+    const path = join(configRoot, '.ai-sdlc', 'soul-tracks.json');
+    if (!existsSync(path))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        const out = {};
+        for (const [key, value] of Object.entries(parsed)) {
+            if (typeof value === 'number' && value >= 0 && value <= 1)
+                out[key] = value;
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Load `.ai-sdlc/maintainers.yaml` from the given config root.
+ *
+ * Accepts either of two shapes:
+ *
+ *   maintainers:
+ *     - alice
+ *     - bob
+ *
+ * or with metadata (only `login` is read, the rest is forward-looking):
+ *
+ *   maintainers:
+ *     - login: alice
+ *       role: owner
+ *     - login: bob
+ *
+ * A bare top-level list (`- alice\n- bob`) is also accepted. Returns
+ * an empty array on missing file or any parse error — callers can
+ * still pass `--maintainers` explicitly to override.
+ */
+export function loadMaintainers(configRoot) {
+    const path = join(configRoot, '.ai-sdlc', 'maintainers.yaml');
+    if (!existsSync(path))
+        return [];
+    try {
+        const doc = parseYaml(readFileSync(path, 'utf-8'));
+        const list = Array.isArray(doc)
+            ? doc
+            : doc &&
+                typeof doc === 'object' &&
+                Array.isArray(doc.maintainers)
+                ? doc.maintainers
+                : [];
+        const out = [];
+        for (const entry of list) {
+            if (typeof entry === 'string' && entry.trim()) {
+                out.push(entry.trim());
+            }
+            else if (entry && typeof entry === 'object' && 'login' in entry) {
+                const login = String(entry.login).trim();
+                if (login)
+                    out.push(login);
+            }
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=backlog-adapter.js.map

package/dist/calibration.d.ts

@@ -0,0 +1,43 @@
+/**
+ * C6 — Category-scoped calibration (RFC-0008 §10 Amendment 6).
+ *
+ * Replaces PPA v1.0's scalar calibrationCoefficient with per-category
+ * coefficients derived from feedback signals. Categories are
+ * PillarContribution labels (product / design / engineering) or
+ * arbitrary labels the caller chooses.
+ *
+ *   Cκ_category = clamp([0.7, 1.3], 1.0 + (accepts - escalates) / max(1, total) × 0.3)
+ *
+ * Per v1.1 note: this adjusts the multiplicative Cκ term, NOT SA-2
+ * directly. Per-dimension calibration lands in PPA v1.1 §17.
+ */
+import type { SaDimension } from './state/types.js';
+import type { SAFeedbackStore } from './sa-scoring/feedback-store.js';
+export declare const CALIBRATION_MIN = 0.7;
+export declare const CALIBRATION_MAX = 1.3;
+/** Slope of the feedback-driven adjustment. Spec §10 uses 0.3. */
+export declare const CALIBRATION_SLOPE = 0.3;
+export interface CategoryFeedback {
+    accepts: number;
+    dismisses: number;
+    escalates: number;
+    overrides?: number;
+}
+export declare function computeCalibrationCoefficient(feedback: CategoryFeedback): number;
+export interface BuildCategoryCoefficientsInput {
+    /** Which SA dimension to pull feedback from. Defaults to SA-1. */
+    dimension?: SaDimension;
+    /** Trailing-window filter. */
+    since?: string;
+    /** Categories to evaluate; when absent, uses all seen in the window. */
+    categories?: readonly string[];
+    /** Minimum feedback count per category before returning a coefficient. */
+    minSampleSize?: number;
+}
+/**
+ * Aggregate feedback rows by category and return `{category: coefficient}`.
+ * Categories with fewer than `minSampleSize` samples are omitted — the
+ * scalar fallback applies to them.
+ */
+export declare function buildCategoryCoefficients(feedback: SAFeedbackStore, input?: BuildCategoryCoefficientsInput): Record<string, number>;
+//# sourceMappingURL=calibration.d.ts.map

package/dist/calibration.js

@@ -0,0 +1,76 @@
+/**
+ * C6 — Category-scoped calibration (RFC-0008 §10 Amendment 6).
+ *
+ * Replaces PPA v1.0's scalar calibrationCoefficient with per-category
+ * coefficients derived from feedback signals. Categories are
+ * PillarContribution labels (product / design / engineering) or
+ * arbitrary labels the caller chooses.
+ *
+ *   Cκ_category = clamp([0.7, 1.3], 1.0 + (accepts - escalates) / max(1, total) × 0.3)
+ *
+ * Per v1.1 note: this adjusts the multiplicative Cκ term, NOT SA-2
+ * directly. Per-dimension calibration lands in PPA v1.1 §17.
+ */
+export const CALIBRATION_MIN = 0.7;
+export const CALIBRATION_MAX = 1.3;
+/** Slope of the feedback-driven adjustment. Spec §10 uses 0.3. */
+export const CALIBRATION_SLOPE = 0.3;
+export function computeCalibrationCoefficient(feedback) {
+    const total = feedback.accepts + feedback.dismisses + feedback.escalates;
+    if (total === 0)
+        return 1.0;
+    const delta = (feedback.accepts - feedback.escalates) / Math.max(1, total);
+    return clamp(1.0 + delta * CALIBRATION_SLOPE, CALIBRATION_MIN, CALIBRATION_MAX);
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+/**
+ * Aggregate feedback rows by category and return `{category: coefficient}`.
+ * Categories with fewer than `minSampleSize` samples are omitted — the
+ * scalar fallback applies to them.
+ */
+export function buildCategoryCoefficients(feedback, input = {}) {
+    const window = {
+        dimension: input.dimension,
+        since: input.since,
+    };
+    const events = feedback.list(window).filter((e) => e.category);
+    const buckets = new Map();
+    for (const e of events) {
+        const key = e.category;
+        if (input.categories && !input.categories.includes(key))
+            continue;
+        const current = buckets.get(key) ?? {
+            accepts: 0,
+            dismisses: 0,
+            escalates: 0,
+            overrides: 0,
+        };
+        switch (e.signal) {
+            case 'accept':
+                current.accepts++;
+                break;
+            case 'dismiss':
+                current.dismisses++;
+                break;
+            case 'escalate':
+                current.escalates++;
+                break;
+            case 'override':
+                current.overrides = (current.overrides ?? 0) + 1;
+                break;
+        }
+        buckets.set(key, current);
+    }
+    const minSize = input.minSampleSize ?? 1;
+    const result = {};
+    for (const [category, f] of buckets) {
+        const samples = f.accepts + f.dismisses + f.escalates;
+        if (samples < minSize)
+            continue;
+        result[category] = computeCalibrationCoefficient(f);
+    }
+    return result;
+}
+//# sourceMappingURL=calibration.js.map

package/dist/cli/commands/agents.d.ts

@@ -1,6 +1,30 @@
 /**
  * ai-sdlc agents [name] — show agent roster, autonomy levels, performance.
+ *
+ * AISDLC-78 (AC #10): in addition to the autonomy ledger (which only
+ * shows agents that have actually executed at least once), we now also
+ * scan the project's .ai-sdlc directory for AgentRole resources and
+ * surface declared-but-not-executed agents. Fresh installs that ran
+ * `ai-sdlc init` previously saw an empty roster even though
+ * `agent-role.yaml` declared `default-agent`; now the user sees the
+ * declared roster + a "(declared, not yet executed)" hint.
  */
 import { Command } from 'commander';
+interface DeclaredAgent {
+    agentName: string;
+    currentLevel: number;
+    totalTasks: number;
+    successCount: number;
+    failureCount: number;
+    lastTaskAt?: string;
+    declaredOnly: true;
+}
+/**
+ * Scan the config directory for AgentRole YAML resources and return the
+ * declared agent metadata. Errors are swallowed (the autonomy ledger
+ * is the primary source of truth — declared agents are a hint).
+ */
+export declare function loadDeclaredAgents(configDir: string): DeclaredAgent[];
 export declare const agentsCommand: Command;
+export {};
 //# sourceMappingURL=agents.d.ts.map

package/dist/cli/commands/agents.js

@@ -1,9 +1,67 @@
 /**
  * ai-sdlc agents [name] — show agent roster, autonomy levels, performance.
+ *
+ * AISDLC-78 (AC #10): in addition to the autonomy ledger (which only
+ * shows agents that have actually executed at least once), we now also
+ * scan the project's .ai-sdlc directory for AgentRole resources and
+ * surface declared-but-not-executed agents. Fresh installs that ran
+ * `ai-sdlc init` previously saw an empty roster even though
+ * `agent-role.yaml` declared `default-agent`; now the user sees the
+ * declared roster + a "(declared, not yet executed)" hint.
  */
 import { Command } from 'commander';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
 import { Orchestrator } from '../../orchestrator.js';
 import { formatOutput } from '../formatters/index.js';
+/**
+ * Scan the config directory for AgentRole YAML resources and return the
+ * declared agent metadata. Errors are swallowed (the autonomy ledger
+ * is the primary source of truth — declared agents are a hint).
+ */
+export function loadDeclaredAgents(configDir) {
+    const dir = resolve(configDir);
+    if (!existsSync(dir))
+        return [];
+    let files;
+    try {
+        files = readdirSync(dir).filter((f) => f.endsWith('.yaml') || f.endsWith('.yml'));
+    }
+    catch {
+        return [];
+    }
+    const declared = [];
+    for (const file of files) {
+        try {
+            const raw = readFileSync(join(dir, file), 'utf-8');
+            const docs = raw
+                .split(/^---\s*$/m)
+                .map((s) => s.trim())
+                .filter(Boolean);
+            for (const docText of docs) {
+                const doc = parseYaml(docText);
+                if (!doc || doc.kind !== 'AgentRole')
+                    continue;
+                const name = doc.metadata?.name;
+                if (!name)
+                    continue;
+                declared.push({
+                    agentName: name,
+                    currentLevel: 0,
+                    totalTasks: 0,
+                    successCount: 0,
+                    failureCount: 0,
+                    declaredOnly: true,
+                });
+            }
+        }
+        catch {
+            // ignore malformed YAML — surfaced by `ai-sdlc validate`
+        }
+    }
+    return declared;
+}
 export const agentsCommand = new Command('agents')
     .description('Show agent roster with autonomy levels and performance')
     .argument('[name]', 'Filter by agent name')
@@ -11,12 +69,19 @@ export const agentsCommand = new Command('agents')
     .action(async (name, opts, cmd) => {
     const globalOpts = cmd.parent?.opts() ?? {};
     const format = globalOpts.format ?? 'table';
+    const configDir = globalOpts.config ?? '.ai-sdlc';
     const orchestrator = new Orchestrator({
         configDir: globalOpts.config,
         statePath: opts.state,
     });
     try {
-        let agents = await orchestrator.agents();
+        const ledger = await orchestrator.agents();
+        const executedNames = new Set(ledger.map((a) => a.agentName));
+        const declared = loadDeclaredAgents(configDir).filter((d) => !executedNames.has(d.agentName));
+        let agents = [
+            ...ledger.map((a) => ({ ...a, declaredOnly: false })),
+            ...declared.map((d) => ({ ...d })),
+        ];
         if (name) {
             agents = agents.filter((a) => a.agentName === name);
         }