code-ai-installer 2.5.0 → 4.0.0

package/dist/mcp/tools/advance_gate.js

@@ -0,0 +1,82 @@
+import { getGateConfig, getNextGate, loadPipeline } from "../pipeline.js";
+import { latestSignoff, readTaskState, writeTaskState } from "../task_state.js";
+const DEFAULT_DOMAIN = "development";
+/**
+ * Advances the task from `from_gate` to `to_gate`.
+ *
+ * Preconditions:
+ *   - Task exists and is at from_gate.
+ *   - from_gate has a sign-off (matching its policy).
+ *   - to_gate is the next gate in the mode sequence (no skipping) UNLESS
+ *     to_gate=DEV and we're coming from REV/OPS/TEST — that's a rollback,
+ *     handled separately (see below).
+ *
+ * Rollback semantics: when to_gate=DEV and from_gate ∈ {REV, OPS, TEST}, this
+ * is a Fix Cycle. dev_rollback_count++. If the count reaches the circuit
+ * breaker threshold (default 2), advance_gate REFUSES and the caller must
+ * invoke the architect deep audit instead.
+ *
+ * RG completion: when advancing INTO RG and RG signs, task is marked completed.
+ * Future call resets dev_rollback_count if pipeline.reset_on includes rg_pass.
+ */
+export async function advanceGate(input) {
+    const pipeline = await loadPipeline(DEFAULT_DOMAIN);
+    const state = await readTaskState(input.task_id);
+    if (!state) {
+        throw new Error(`advance_gate: no task state for ${input.task_id}`);
+    }
+    if (state.current_gate !== input.from_gate) {
+        throw new Error(`advance_gate: task ${input.task_id} is at ${state.current_gate}, not ${input.from_gate}`);
+    }
+    if (state.mode !== input.mode) {
+        throw new Error(`advance_gate: task ${input.task_id} mode is ${state.mode}, not ${input.mode}`);
+    }
+    const fromCfg = getGateConfig(pipeline, state.mode, input.from_gate);
+    const fromSignoff = latestSignoff(state, input.from_gate);
+    if (!fromSignoff) {
+        throw new Error(`advance_gate: gate ${input.from_gate} has no sign-off (sign_off_policy=${fromCfg.sign_off_policy})`);
+    }
+    const isRollbackToDev = input.to_gate === "DEV" && ["REV", "OPS", "TEST"].includes(input.from_gate);
+    if (isRollbackToDev) {
+        const nextCount = state.dev_rollback_count + 1;
+        if (pipeline.circuit_breaker.enabled &&
+            nextCount >= pipeline.circuit_breaker.dev_rollback_threshold) {
+            // Mark task as audit-required and persist BEFORE throwing so downstream
+            // tools (audit_trail, list_artifacts) can see the state.
+            state.audit_required_at = new Date().toISOString();
+            await writeTaskState(state);
+            const skills = pipeline.circuit_breaker.audit_required_skills.join(", ");
+            throw new Error([
+                `advance_gate: circuit breaker tripped — dev_rollback_count would reach ${nextCount} (threshold ${pipeline.circuit_breaker.dev_rollback_threshold}).`,
+                `Recommended: run the audit in a FRESH session (clean-context principle — see wing_codex_product/decisions 2026-05-23, "SUBAGENTS FOR CONSISTENCY CHECKS"). In-session retry from the same Claude that just hit the wall reproduces the blind spot that caused the rollback in the first place.`,
+                `Required next steps:`,
+                `  1) load_role(role_name="${pipeline.circuit_breaker.audit_role}", domain="${pipeline.domain}")`,
+                `  2) Read skills: ${skills}`,
+                `  3) Produce architect audit (root-cause analysis, not patch attempt).`,
+                `  4) record_decision(task_id="${input.task_id}", gate="ARCH", ...) — new ARCH ADR resets dev_rollback_count to 0 via reset_on=new_arch_adr.`,
+                `  5) After reset, re-run sign_off("DEV", "den") + advance_gate(DEV → ${input.from_gate}).`,
+            ].join("\n"));
+        }
+        state.dev_rollback_count = nextCount;
+    }
+    else {
+        const expectedNext = getNextGate(pipeline, state.mode, input.from_gate);
+        if (expectedNext !== input.to_gate) {
+            throw new Error(`advance_gate: invalid transition ${input.from_gate} → ${input.to_gate} (expected ${expectedNext ?? "terminal"})`);
+        }
+    }
+    state.current_gate = input.to_gate;
+    if (state.completed_at === undefined && input.to_gate === "RG") {
+        // entered RG; completion happens when RG itself is signed; left as a marker
+    }
+    // Reset rollback counter on RG entry per reset_on policy (treat RG entry as rg_pass moment for prototype)
+    if (input.to_gate === "RG" && pipeline.circuit_breaker.reset_on.includes("rg_pass")) {
+        state.dev_rollback_count = 0;
+    }
+    await writeTaskState(state);
+    return {
+        task_id: input.task_id,
+        current_gate: input.to_gate,
+        allowed_tools: [],
+    };
+}

package/dist/mcp/tools/audit_trail.d.ts

@@ -0,0 +1,20 @@
+import type { AuditTrailInput, AuditTrailOutput } from "../../shared/index.js";
+/**
+ * Reconstructs the timeline for a task by merging:
+ *   - task_state classifications (kind: "classify_gate")
+ *   - task_state signoffs (kind: "sign_off")
+ *   - audit_required_at (kind: "circuit_breaker_trip")
+ *   - decisions.jsonl entries for this task (kind: "record_decision")
+ *
+ * Events are returned sorted asc by timestamp. Empty if the task doesn't exist.
+ *
+ * Not yet recorded (TODO for full instrumentation):
+ *   - "advance_gate" events — implicit in sign_off→next-gate; would require
+ *     extending TaskState with an explicit transition log.
+ *   - "submit_artifact" events — partially captured via .code-ai/state/
+ *     artifacts/<task_id>.jsonl when gate is provided.
+ *   - "request_decision" events — pending requests are not persisted yet.
+ *     report_exception entries are surfaced via report_exception output, but
+ *     also folded into the audit trail when present.
+ */
+export declare function auditTrail(input: AuditTrailInput): Promise<AuditTrailOutput>;

package/dist/mcp/tools/audit_trail.js

@@ -0,0 +1,124 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { readTaskState } from "../task_state.js";
+import { buildDecisionStore } from "../stores/index.js";
+/**
+ * Reconstructs the timeline for a task by merging:
+ *   - task_state classifications (kind: "classify_gate")
+ *   - task_state signoffs (kind: "sign_off")
+ *   - audit_required_at (kind: "circuit_breaker_trip")
+ *   - decisions.jsonl entries for this task (kind: "record_decision")
+ *
+ * Events are returned sorted asc by timestamp. Empty if the task doesn't exist.
+ *
+ * Not yet recorded (TODO for full instrumentation):
+ *   - "advance_gate" events — implicit in sign_off→next-gate; would require
+ *     extending TaskState with an explicit transition log.
+ *   - "submit_artifact" events — partially captured via .code-ai/state/
+ *     artifacts/<task_id>.jsonl when gate is provided.
+ *   - "request_decision" events — pending requests are not persisted yet.
+ *     report_exception entries are surfaced via report_exception output, but
+ *     also folded into the audit trail when present.
+ */
+export async function auditTrail(input) {
+    const state = await readTaskState(input.task_id);
+    const events = [];
+    if (state) {
+        for (const c of state.classifications) {
+            events.push({
+                timestamp: c.timestamp,
+                kind: "classify_gate",
+                gate: c.gate,
+                details: { outcome: c.outcome, rationale: c.rationale },
+            });
+        }
+        for (const s of state.signoffs) {
+            events.push({
+                timestamp: s.timestamp,
+                kind: "sign_off",
+                gate: s.gate,
+                details: { signer: s.signer, evidence: s.evidence ?? null },
+            });
+        }
+        if (state.audit_required_at) {
+            events.push({
+                timestamp: state.audit_required_at,
+                kind: "circuit_breaker_trip",
+                details: { dev_rollback_count: state.dev_rollback_count },
+            });
+        }
+    }
+    // decisions for this task via DecisionStore (canonical JSONL + optional MemPalace mirror)
+    const store = await buildDecisionStore();
+    const decisions = await store.readDecisions({
+        task_id: input.task_id,
+        includePending: true,
+    });
+    for (const entry of decisions) {
+        const kind = entry.adr_id.startsWith("ADR-PENDING-")
+            ? "request_decision"
+            : "record_decision";
+        events.push({
+            timestamp: entry.timestamp,
+            kind,
+            gate: entry.gate,
+            details: {
+                adr_id: entry.adr_id,
+                question: entry.question,
+                chosen_option_id: entry.chosen_option_id,
+                signer: entry.signer,
+            },
+        });
+    }
+    // submit_artifact events (when gate-indexed)
+    const safe = input.task_id.replace(/[^A-Za-z0-9_.-]/g, "_");
+    const artifactsPath = join(process.cwd(), ".code-ai", "state", "artifacts", `${safe}.jsonl`);
+    const rawArt = await readFile(artifactsPath, "utf8").catch(() => "");
+    if (rawArt) {
+        for (const line of rawArt.split("\n")) {
+            if (!line)
+                continue;
+            try {
+                const obj = JSON.parse(line);
+                events.push({
+                    timestamp: obj.timestamp,
+                    kind: "submit_artifact",
+                    gate: obj.gate,
+                    details: { class: obj.class, path: obj.path, line_count: obj.line_count },
+                });
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    // exceptions.jsonl entries for this task
+    const excPath = join(process.cwd(), ".code-ai", "state", "exceptions.jsonl");
+    const rawExc = await readFile(excPath, "utf8").catch(() => "");
+    if (rawExc) {
+        for (const line of rawExc.split("\n")) {
+            if (!line)
+                continue;
+            try {
+                const obj = JSON.parse(line);
+                if (obj.task_id !== input.task_id)
+                    continue;
+                events.push({
+                    timestamp: obj.timestamp,
+                    kind: "report_exception",
+                    gate: obj.gate,
+                    details: {
+                        exception_id: obj.exception_id,
+                        what_failed: obj.what_failed,
+                        breakdown: obj.breakdown,
+                    },
+                });
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    events.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+    return { events };
+}

package/dist/mcp/tools/classify_gate.d.ts

@@ -0,0 +1,14 @@
+import { type ClassifyGateInput, type ClassifyGateOutput } from "../../shared/index.js";
+/**
+ * Records the classification for the current gate. Must be called before the
+ * artifact is produced when the gate has classify_required=true.
+ *
+ * Outcomes map to next_required_action:
+ *   auto_resolve → produce_artifact (silent path)
+ *   fork         → open_request_decision (DEN must choose)
+ *   exception    → open_report_exception (auto-check failed; needs DEN review)
+ *
+ * No-op-safe if called multiple times for the same gate — each call appends
+ * a new classification entry. latestClassification() returns the most recent.
+ */
+export declare function classifyGate(input: ClassifyGateInput): Promise<ClassifyGateOutput>;

package/dist/mcp/tools/classify_gate.js

@@ -0,0 +1,42 @@
+import { loadPipeline, getInitialGate } from "../pipeline.js";
+import { createTaskState, readTaskState, writeTaskState, } from "../task_state.js";
+const DEFAULT_DOMAIN = "development";
+/**
+ * Records the classification for the current gate. Must be called before the
+ * artifact is produced when the gate has classify_required=true.
+ *
+ * Outcomes map to next_required_action:
+ *   auto_resolve → produce_artifact (silent path)
+ *   fork         → open_request_decision (DEN must choose)
+ *   exception    → open_report_exception (auto-check failed; needs DEN review)
+ *
+ * No-op-safe if called multiple times for the same gate — each call appends
+ * a new classification entry. latestClassification() returns the most recent.
+ */
+export async function classifyGate(input) {
+    const pipeline = await loadPipeline(DEFAULT_DOMAIN);
+    let state = await readTaskState(input.task_id);
+    if (!state) {
+        state = await createTaskState({
+            task_id: input.task_id,
+            mode: pipeline.default_mode,
+            initial_gate: getInitialGate(pipeline, pipeline.default_mode),
+        });
+    }
+    if (state.current_gate !== input.gate) {
+        throw new Error(`classify_gate: task ${input.task_id} is at gate ${state.current_gate}, not ${input.gate}`);
+    }
+    state.classifications.push({
+        gate: input.gate,
+        outcome: input.outcome,
+        rationale: input.rationale,
+        timestamp: new Date().toISOString(),
+    });
+    await writeTaskState(state);
+    const next_required_action = input.outcome === "auto_resolve"
+        ? "produce_artifact"
+        : input.outcome === "fork"
+            ? "open_request_decision"
+            : "open_report_exception";
+    return { acknowledged: true, next_required_action };
+}

package/dist/mcp/tools/current_gate.d.ts

@@ -0,0 +1,14 @@
+import { type CurrentGateInput, type CurrentGateOutput } from "../../shared/index.js";
+/**
+ * Returns the task's current gate. Auto-creates the task state with the
+ * pipeline's default_mode and initial gate if no state file exists yet —
+ * there is no separate start_task tool in the v0 surface, so first-touch
+ * is implicit.
+ *
+ * The contract output includes allowed_tools and required_handoff_fields.
+ * For the prototype both are derived from the gate config in pipeline.yaml:
+ *   allowed_tools: empty array — hook layer resolves real tool allowlists.
+ *   required_handoff_fields: ["summary", "deliverable_path", "next_role"]
+ *   classification_pending: true if classify_required && no classification yet.
+ */
+export declare function currentGate(input: CurrentGateInput): Promise<CurrentGateOutput>;

package/dist/mcp/tools/current_gate.js

@@ -0,0 +1,35 @@
+import { loadPipeline, getGateConfig, getInitialGate } from "../pipeline.js";
+import { createTaskState, latestClassification, readTaskState } from "../task_state.js";
+const DEFAULT_DOMAIN = "development";
+/**
+ * Returns the task's current gate. Auto-creates the task state with the
+ * pipeline's default_mode and initial gate if no state file exists yet —
+ * there is no separate start_task tool in the v0 surface, so first-touch
+ * is implicit.
+ *
+ * The contract output includes allowed_tools and required_handoff_fields.
+ * For the prototype both are derived from the gate config in pipeline.yaml:
+ *   allowed_tools: empty array — hook layer resolves real tool allowlists.
+ *   required_handoff_fields: ["summary", "deliverable_path", "next_role"]
+ *   classification_pending: true if classify_required && no classification yet.
+ */
+export async function currentGate(input) {
+    const pipeline = await loadPipeline(DEFAULT_DOMAIN);
+    let state = await readTaskState(input.task_id);
+    if (!state) {
+        state = await createTaskState({
+            task_id: input.task_id,
+            mode: pipeline.default_mode,
+            initial_gate: getInitialGate(pipeline, pipeline.default_mode),
+        });
+    }
+    const gateCfg = getGateConfig(pipeline, state.mode, state.current_gate);
+    const cls = latestClassification(state, state.current_gate);
+    return {
+        mode: state.mode,
+        gate: state.current_gate,
+        allowed_tools: [],
+        required_handoff_fields: ["summary", "deliverable_path", "next_role"],
+        classification_pending: gateCfg.classify_required && cls === null,
+    };
+}

package/dist/mcp/tools/get_artifact.d.ts

@@ -0,0 +1,11 @@
+import type { GetArtifactInput, GetArtifactOutput } from "../../shared/index.js";
+/**
+ * Resolves (task_id, gate) → artifact file content. Uses the per-task index
+ * .code-ai/state/artifacts/<task_id>.jsonl. If multiple writes happened at the
+ * same gate, returns the LATEST one (jsonl order).
+ *
+ * format=summary returns the first 5 lines of the content prepended with a
+ * heading; format=raw returns the full body. v1 keeps summary very simple —
+ * a fancier summarizer (per artifact class) is a future enhancement.
+ */
+export declare function getArtifact(input: GetArtifactInput): Promise<GetArtifactOutput>;

package/dist/mcp/tools/get_artifact.js

@@ -0,0 +1,46 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * Resolves (task_id, gate) → artifact file content. Uses the per-task index
+ * .code-ai/state/artifacts/<task_id>.jsonl. If multiple writes happened at the
+ * same gate, returns the LATEST one (jsonl order).
+ *
+ * format=summary returns the first 5 lines of the content prepended with a
+ * heading; format=raw returns the full body. v1 keeps summary very simple —
+ * a fancier summarizer (per artifact class) is a future enhancement.
+ */
+export async function getArtifact(input) {
+    const safe = input.task_id.replace(/[^A-Za-z0-9_.-]/g, "_");
+    const indexPath = join(process.cwd(), ".code-ai", "state", "artifacts", `${safe}.jsonl`);
+    const raw = await readFile(indexPath, "utf8").catch(() => "");
+    if (!raw)
+        return { exists: false };
+    let latestPath = null;
+    for (const line of raw.split("\n")) {
+        if (!line)
+            continue;
+        try {
+            const obj = JSON.parse(line);
+            if (obj.gate === input.gate && typeof obj.path === "string") {
+                latestPath = obj.path; // overwrite — last match wins
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    if (!latestPath)
+        return { exists: false };
+    const content = await readFile(latestPath, "utf8").catch(() => null);
+    if (content === null)
+        return { exists: false };
+    if (input.format === "summary") {
+        const head = content.split("\n").slice(0, 5).join("\n");
+        return {
+            exists: true,
+            path: latestPath,
+            content: `=== summary of ${latestPath} ===\n${head}`,
+        };
+    }
+    return { exists: true, path: latestPath, content };
+}

package/dist/mcp/tools/get_skill.d.ts

@@ -0,0 +1,17 @@
+import { type GetSkillInput, type GetSkillOutput } from "../../shared/index.js";
+/**
+ * Reads a single SKILL.md from disk, validates its frontmatter against
+ * SkillFrontmatter (zod), and returns { frontmatter, body }.
+ *
+ * Throws:
+ *   - if the file does not exist (caller passed a name that has no SKILL.md)
+ *   - if the frontmatter block is missing
+ *   - if the YAML is malformed
+ *   - if the frontmatter fails SkillFrontmatter validation
+ *
+ * The body is everything AFTER the closing `---` of the frontmatter, with the
+ * BOM (if any) stripped from the file head. Line cap is NOT enforced here —
+ * `submit_artifact` validates writes; `get_skill` is read-only and surfaces
+ * whatever is on disk so callers can audit oversized bodies.
+ */
+export declare function getSkill(input: GetSkillInput): Promise<GetSkillOutput>;

package/dist/mcp/tools/get_skill.js

@@ -0,0 +1,47 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { SkillFrontmatter, } from "../../shared/index.js";
+import { resolveSkillsRoot } from "../paths.js";
+/**
+ * Reads a single SKILL.md from disk, validates its frontmatter against
+ * SkillFrontmatter (zod), and returns { frontmatter, body }.
+ *
+ * Throws:
+ *   - if the file does not exist (caller passed a name that has no SKILL.md)
+ *   - if the frontmatter block is missing
+ *   - if the YAML is malformed
+ *   - if the frontmatter fails SkillFrontmatter validation
+ *
+ * The body is everything AFTER the closing `---` of the frontmatter, with the
+ * BOM (if any) stripped from the file head. Line cap is NOT enforced here —
+ * `submit_artifact` validates writes; `get_skill` is read-only and surfaces
+ * whatever is on disk so callers can audit oversized bodies.
+ */
+export async function getSkill(input) {
+    const file = join(resolveSkillsRoot(input.domain), input.name, "SKILL.md");
+    const raw = await readFile(file, "utf8").catch((err) => {
+        if (err.code === "ENOENT") {
+            throw new Error(`get_skill: SKILL.md not found for '${input.name}' in domain '${input.domain}' (expected at ${file})`);
+        }
+        throw err;
+    });
+    const stripped = raw.startsWith("") ? raw.slice(1) : raw;
+    const m = stripped.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+    if (!m) {
+        throw new Error(`get_skill: no frontmatter block found in ${file}`);
+    }
+    let parsedYaml;
+    try {
+        parsedYaml = parseYaml(m[1]);
+    }
+    catch (err) {
+        throw new Error(`get_skill: malformed YAML frontmatter in ${file} — ${err.message}`);
+    }
+    const fm = SkillFrontmatter.safeParse(parsedYaml);
+    if (!fm.success) {
+        throw new Error(`get_skill: frontmatter validation failed for ${file} — ${fm.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`);
+    }
+    const body = stripped.slice(m[0].length);
+    return { frontmatter: fm.data, body };
+}

package/dist/mcp/tools/list_artifacts.d.ts

@@ -0,0 +1,8 @@
+import type { ListArtifactsInput, ListArtifactsOutput } from "../../shared/index.js";
+/**
+ * Returns artifacts written via submit_artifact with `gate` provided.
+ * Source: .code-ai/state/artifacts/<task_id>.jsonl (one line per write).
+ * Empty array if no artifacts were indexed for this task (older callers may
+ * have written without the gate field; those won't show up here).
+ */
+export declare function listArtifacts(input: ListArtifactsInput): Promise<ListArtifactsOutput>;

package/dist/mcp/tools/list_artifacts.js

@@ -0,0 +1,35 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * Returns artifacts written via submit_artifact with `gate` provided.
+ * Source: .code-ai/state/artifacts/<task_id>.jsonl (one line per write).
+ * Empty array if no artifacts were indexed for this task (older callers may
+ * have written without the gate field; those won't show up here).
+ */
+export async function listArtifacts(input) {
+    const safe = input.task_id.replace(/[^A-Za-z0-9_.-]/g, "_");
+    const indexPath = join(process.cwd(), ".code-ai", "state", "artifacts", `${safe}.jsonl`);
+    const raw = await readFile(indexPath, "utf8").catch(() => "");
+    if (!raw)
+        return { artifacts: [] };
+    const artifacts = [];
+    for (const line of raw.split("\n")) {
+        if (!line)
+            continue;
+        try {
+            const obj = JSON.parse(line);
+            if (typeof obj.gate !== "string" || typeof obj.class !== "string")
+                continue;
+            artifacts.push({
+                gate: obj.gate,
+                class: obj.class,
+                path: obj.path,
+                line_count: obj.line_count,
+            });
+        }
+        catch {
+            continue;
+        }
+    }
+    return { artifacts };
+}

package/dist/mcp/tools/list_skills.d.ts

@@ -0,0 +1,8 @@
+import { type ListSkillsInput, type ListSkillsOutput } from "../../shared/index.js";
+/**
+ * Reads every SKILL.md under the given domain's `.agents/skills/<name>/SKILL.md`
+ * and returns the subset matching the filter. Frontmatter is parsed via the YAML
+ * lib (BOM-aware) and the type-narrowing is done at the filter step — we don't
+ * fail the whole call if one skill has a malformed frontmatter; we just skip it.
+ */
+export declare function listSkills(input: ListSkillsInput): Promise<ListSkillsOutput>;

package/dist/mcp/tools/list_skills.js

@@ -0,0 +1,54 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { resolveSkillsRoot } from "../paths.js";
+/**
+ * Reads every SKILL.md under the given domain's `.agents/skills/<name>/SKILL.md`
+ * and returns the subset matching the filter. Frontmatter is parsed via the YAML
+ * lib (BOM-aware) and the type-narrowing is done at the filter step — we don't
+ * fail the whole call if one skill has a malformed frontmatter; we just skip it.
+ */
+export async function listSkills(input) {
+    const domain = input.domain ?? "development";
+    const root = resolveSkillsRoot(domain);
+    const dirs = (await readdir(root, { withFileTypes: true })).filter((d) => d.isDirectory());
+    const out = [];
+    for (const dir of dirs) {
+        const md = await readFile(join(root, dir.name, "SKILL.md"), "utf8").catch(() => null);
+        if (!md)
+            continue;
+        const fm = parseFrontmatter(md);
+        if (!fm)
+            continue;
+        if (input.type && fm.type !== input.type)
+            continue;
+        if (input.gate && !(fm.gates ?? []).includes(input.gate))
+            continue;
+        if (input.tech && !(fm.tech ?? []).includes(input.tech))
+            continue;
+        if (input.topic && !(fm.topic ?? []).includes(input.topic))
+            continue;
+        if (input.owner && !(fm.owners ?? []).includes(input.owner))
+            continue;
+        out.push({
+            name: fm.name,
+            description: fm.description,
+            type: fm.type,
+            gates: fm.gates ?? [],
+        });
+    }
+    out.sort((a, b) => a.name.localeCompare(b.name));
+    return { skills: out };
+}
+function parseFrontmatter(raw) {
+    const stripped = raw.startsWith("") ? raw.slice(1) : raw;
+    const m = stripped.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!m)
+        return null;
+    try {
+        return parseYaml(m[1]);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/mcp/tools/load_role.d.ts

@@ -0,0 +1,14 @@
+import { type LoadRoleInput, type LoadRoleOutput } from "../../shared/index.js";
+/**
+ * SessionStart loader for an agent role.
+ *
+ * For pre-req #3, persona files live in docs/architecture-redesign/ (not yet
+ * migrated to installer/domains/<domain>/persona/ — awaiting DEN sign-off).
+ * Path is hard-coded here; will become configurable once persona moves into
+ * the installer ship.
+ *
+ * User-layer persona is currently always absent (persona-user-denis.md is
+ * gitignored and not loaded by name match). Future versions read the user
+ * handle from env or config.
+ */
+export declare function loadRole(input: LoadRoleInput): Promise<LoadRoleOutput>;