agent-trellis 0.1.0

package/dist/commands/secretsAudit.js

@@ -0,0 +1,115 @@
+/**
+ * `trellis secrets audit` — reads every present, MCP-capable agent's real
+ * config file (never the canonical source) and checks it against
+ * `CanonicalSource.secretsPolicy`: a literal-value scan against
+ * `rejectPatterns`, and a declared-env-var-name check against
+ * `allowedVars`. Also checks, agent-agnostically, whether every env var
+ * name declared across canonical `mcp.servers[*].env` actually resolves
+ * to a value via the same `resolveSecretEnv` the pi bridge uses
+ * (trellis-secrets-env-management) — authoritative for pi, a best-effort
+ * proxy for the other three (design.md D3 in that change). Read-only —
+ * never writes anything. Fails non-zero on any finding
+ * (trellis-secrets-audit-p3).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { loadCanonicalSource } from "../core/canonical.js";
+import { ClaudeCodeAdapter } from "../adapters/claude-code.js";
+import { CodexAdapter } from "../adapters/codex.js";
+import { KiroAdapter } from "../adapters/kiro.js";
+import { declaredEnvNames, extractJsonEnvVarNames, extractTomlEnvVarNames } from "../lib/envVarNames.js";
+import { resolveSecretEnv } from "../lib/secretEnv.js";
+function auditedAgents(homeDir) {
+    return [
+        { id: "claude-code", probe: () => new ClaudeCodeAdapter(homeDir).probe(), configPath: (h) => join(h, ".claude.json"), extractNames: extractJsonEnvVarNames },
+        { id: "codex", probe: () => new CodexAdapter(homeDir).probe(), configPath: (h) => join(h, ".codex", "config.toml"), extractNames: extractTomlEnvVarNames },
+        { id: "kiro", probe: () => new KiroAdapter(homeDir).probe(), configPath: (h) => join(h, ".kiro", "settings", "mcp.json"), extractNames: extractJsonEnvVarNames },
+        // pi has no static, generated MCP config file to audit — its bridge
+        // reads mcp/servers.yaml directly at its own runtime (P4). See
+        // design.md Non-Goals in trellis-secrets-audit-p3.
+    ];
+}
+/**
+ * Not scoped to any agent, present or not — a name that can't resolve is
+ * a problem regardless of which agents' `servers.yaml` `agents:` field
+ * would route it to (trellis-secrets-env-management design.md D3).
+ */
+function findMissingEnvValues(servers, policy) {
+    const names = new Set();
+    for (const def of Object.values(servers)) {
+        for (const name of declaredEnvNames(def))
+            names.add(name);
+    }
+    if (names.size === 0)
+        return [];
+    const resolved = resolveSecretEnv([...names], policy);
+    const source = policy.envFile ?? "process environment";
+    return [...names]
+        .filter((name) => !resolved[name])
+        .map((name) => ({
+        agent: "environment",
+        file: source,
+        kind: "missing-env-value",
+        detail: `"${name}" is declared by a canonical MCP server's env but has no resolvable value`,
+    }));
+}
+function auditFile(agent, file, content, policy, extractNames) {
+    const findings = [];
+    for (const pattern of policy.rejectPatterns) {
+        if (pattern.test(content)) {
+            findings.push({ agent, file, kind: "literal-secret", detail: `matches reject pattern ${pattern}` });
+        }
+    }
+    const allowed = new Set(policy.allowedVars);
+    for (const name of new Set(extractNames(content))) {
+        if (!allowed.has(name)) {
+            findings.push({ agent, file, kind: "unexpected-var-name", detail: `"${name}" is not in secrets.policy.yaml's allowed_vars` });
+        }
+    }
+    return findings;
+}
+export async function collectSecretsAuditReport(opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const canonical = loadCanonicalSource(homeDir);
+    const findings = [];
+    for (const agent of auditedAgents(homeDir)) {
+        const probeResult = await agent.probe();
+        if (!probeResult.present)
+            continue;
+        const file = agent.configPath(homeDir);
+        if (!existsSync(file))
+            continue;
+        const content = readFileSync(file, "utf-8");
+        findings.push(...auditFile(agent.id, file, content, canonical.secretsPolicy, agent.extractNames));
+    }
+    findings.push(...findMissingEnvValues(canonical.mcp.servers, canonical.secretsPolicy));
+    return { findings };
+}
+export async function runSecretsAudit(opts = {}) {
+    let report;
+    try {
+        report = await collectSecretsAuditReport(opts);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { exitCode: 1 };
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        printReport(report);
+    }
+    return { exitCode: report.findings.length > 0 ? 1 : 0 };
+}
+function printReport(report) {
+    if (report.findings.length === 0) {
+        console.log("✅ no findings — every present agent's real config and every declared env var passed all checks");
+        return;
+    }
+    console.log(`⚠️  ${report.findings.length} finding(s):`);
+    for (const finding of report.findings) {
+        console.log(`   - [${finding.kind}] ${finding.agent} — ${finding.file}: ${finding.detail}`);
+    }
+}

package/dist/commands/sync.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `trellis sync` / `trellis sync skills` / `trellis sync instructions` —
+ * loads canonical once, runs every present agent's adapter, applies the
+ * plan, and reports what happened. Conflicts are report-only (never
+ * thrown) — see src/core/adapter.ts's `apply()` doc — so one conflicting
+ * item never blocks every other, unrelated item in the same run.
+ */
+import type { AdapterPlanItem } from "../core/adapter.js";
+import type { AgentId } from "../core/types.js";
+export interface RunSyncOptions {
+    /** Omit to sync both. */
+    target?: "skills" | "instructions";
+    json?: boolean;
+    /** Defaults to the real `~`; overridable for tests and
+     * `scripts/sandbox.sh` only — same seam as every probe and
+     * `loadCanonicalSource` uses, and for the same reason: this is the first
+     * command in the repo that writes, and it must never be exercised
+     * against a developer's real dotfiles (docs/architecture.md's testing
+     * philosophy). Not a CLI flag — there is no product reason for an end
+     * user to ever point `trellis sync` at a fake home. */
+    homeDir?: string;
+    /** Compute and report the plan without calling adapter.apply(). */
+    dryRun?: boolean;
+}
+export interface AgentSyncReport {
+    agent: AgentId;
+    present: boolean;
+    items: AdapterPlanItem[];
+}
+export interface SyncReport {
+    reports: AgentSyncReport[];
+}
+export declare function collectSyncReport(opts?: RunSyncOptions): Promise<SyncReport>;
+export declare function runSync(opts?: RunSyncOptions): Promise<{
+    exitCode: number;
+}>;
+/** Exported so `onboard` prints a sync report identically to running
+ * `sync` standalone, instead of a second, easily-drifting copy of this
+ * formatting. */
+export declare function printReport(report: SyncReport, dryRun: boolean): void;

package/dist/commands/sync.js

@@ -0,0 +1,91 @@
+/**
+ * `trellis sync` / `trellis sync skills` / `trellis sync instructions` —
+ * loads canonical once, runs every present agent's adapter, applies the
+ * plan, and reports what happened. Conflicts are report-only (never
+ * thrown) — see src/core/adapter.ts's `apply()` doc — so one conflicting
+ * item never blocks every other, unrelated item in the same run.
+ */
+import { homedir } from "node:os";
+import { loadCanonicalSource } from "../core/canonical.js";
+import { ClaudeCodeAdapter } from "../adapters/claude-code.js";
+import { CodexAdapter } from "../adapters/codex.js";
+import { KiroAdapter } from "../adapters/kiro.js";
+import { PiAdapter } from "../adapters/pi.js";
+function buildAdapters(homeDir) {
+    return [new ClaudeCodeAdapter(homeDir), new CodexAdapter(homeDir), new KiroAdapter(homeDir), new PiAdapter(homeDir)];
+}
+export async function collectSyncReport(opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const canonical = loadCanonicalSource(homeDir);
+    const reports = [];
+    for (const adapter of buildAdapters(homeDir)) {
+        const probeResult = await adapter.probe();
+        if (!probeResult.present) {
+            reports.push({ agent: adapter.id, present: false, items: [] });
+            continue;
+        }
+        // adapter.plan() also returns "mcp" items now (trellis-mcp-sync-p2) —
+        // `trellis sync` never touches MCP, that's `trellis mcp sync`'s own
+        // command, so exclude it unconditionally before any target filter.
+        let items = (await adapter.plan(canonical)).filter((item) => item.kind !== "mcp");
+        if (opts.target) {
+            // CLI/option vocabulary is plural ("skills"/"instructions",
+            // matching `trellis sync skills`); AdapterPlanItem.kind is singular
+            // ("skill"/"instructions") since it describes one item. Map
+            // explicitly rather than assume the strings line up — they don't,
+            // and a caught-nowhere mismatch here silently filters everything
+            // out (found via the sandbox: every agent reported "already in
+            // sync" even with real create items pending).
+            const kind = opts.target === "skills" ? "skill" : "instructions";
+            items = items.filter((item) => item.kind === kind);
+        }
+        if (!opts.dryRun) {
+            await adapter.apply(items);
+        }
+        reports.push({ agent: adapter.id, present: true, items });
+    }
+    return { reports };
+}
+export async function runSync(opts = {}) {
+    let report;
+    try {
+        report = await collectSyncReport(opts);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return { exitCode: 1 };
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        printReport(report, opts.dryRun ?? false);
+    }
+    const hasConflict = report.reports.some((r) => r.items.some((i) => i.action === "conflict"));
+    return { exitCode: hasConflict ? 1 : 0 };
+}
+/** Exported so `onboard` prints a sync report identically to running
+ * `sync` standalone, instead of a second, easily-drifting copy of this
+ * formatting. */
+export function printReport(report, dryRun) {
+    if (dryRun)
+        console.log("[dry run]");
+    for (const { agent, present, items } of report.reports) {
+        if (!present) {
+            console.log(`—  ${agent} (not installed)`);
+            continue;
+        }
+        const created = items.filter((i) => i.action === "create");
+        const removed = items.filter((i) => i.action === "remove");
+        const conflicts = items.filter((i) => i.action === "conflict");
+        if (created.length === 0 && removed.length === 0 && conflicts.length === 0) {
+            console.log(`✅ ${agent} — already in sync`);
+            continue;
+        }
+        const icon = conflicts.length > 0 ? "⚠️ " : "✅";
+        console.log(`${icon} ${agent} — ${created.length} created, ${removed.length} removed, ${conflicts.length} conflict(s)`);
+        for (const item of [...created, ...removed, ...conflicts]) {
+            console.log(`   - [${item.action}] ${item.description}`);
+        }
+    }
+}

package/dist/core/adapter.d.ts

@@ -0,0 +1,133 @@
+/**
+ * The adapter contract every agent integration (Claude Code, Codex, Kiro,
+ * pi) must implement. See docs/architecture.md "Adapter contract" for the
+ * rules each method must follow — in particular: `apply` must never
+ * overwrite fields it doesn't own, and `verify` must re-read the agent's
+ * own state rather than trust that `apply` succeeded.
+ *
+ * No adapter exists yet (see docs/roadmap.md P1/P2/P4). This interface is
+ * the contract they'll be built against.
+ */
+import type { AgentId, CanonicalSource, McpServerDef } from "./types.js";
+import { resolveScope } from "./types.js";
+export interface AdapterProbeResult {
+    present: boolean;
+    version?: string;
+    detail?: string;
+}
+export interface AdapterPlanItem {
+    /**
+     * "create" also covers repair (wrong symlink target, or an MCP server
+     * definition that differs from canonical); "remove" is the delete half
+     * for skills/instructions — a Trellis-managed symlink whose canonical
+     * entry is gone or was just scoped away from this agent. MCP server
+     * items never use "remove" (see `kind: "mcp"` below — no ownership
+     * marker exists yet to make that provably safe, trellis-mcp-sync-p2
+     * design.md D7). "conflict" is either a real, non-symlink path
+     * occupying a spot Trellis would otherwise touch, or an MCP server
+     * refused for a collision/secrets-guard reason — reported, never acted
+     * on. See `plan()`'s doc below.
+     */
+    action: "create" | "remove" | "conflict";
+    /** Lets `trellis sync skills` / `trellis sync instructions` /
+     * `trellis mcp sync` filter a full plan without changing `plan()`'s
+     * signature — every adapter produces every kind it's responsible for in
+     * one pass; the CLI subcommand decides which to apply, not the adapter.
+     * `"extension"` is pi-only: the MCP bridge file itself
+     * (trellis-pi-mcp-bridge-p4) — Trellis's own packaged code, not a
+     * user-authored capability from `~/.trellis/`, delivered via the same
+     * symlink create/repair/remove semantics as skills/instructions.
+     * `"kiro-approved-env-vars"` is Kiro-only (trellis-kiro-approved-env-vars):
+     * a completely different target file and merge mechanism (see
+     * `approvedEnvVars` below) from `"mcp"`, not something the other
+     * three agents have an equivalent of. */
+    kind: "skill" | "instructions" | "mcp" | "extension" | "kiro-approved-env-vars";
+    /** Human-readable description of one change this adapter would make
+     * ("create" / "remove") or why it refused to ("conflict"). */
+    description: string;
+    /** What's being touched, for the collision/audit checks to reason
+     * about. For `kind: "mcp"`, the config file being modified (e.g.
+     * `~/.codex/config.toml`), not a per-server path — there isn't one. */
+    target: string;
+    /** Only set (and only meaningful) when `kind` is `"skill"` or
+     * `"instructions"` and `action === "create"`: the absolute path
+     * `target` should be symlinked to. Kept as a real field rather than
+     * embedded in `description` — `apply()` must never have to parse prose
+     * back into structured data. */
+    linkTarget?: string;
+    /** Only set (and only meaningful) when `kind === "mcp"` and
+     * `action === "create"`: the server name and definition to write into
+     * `target` (the config file) via that agent's own mechanism (JSON
+     * merge or, for Codex, `src/lib/tomlSection.ts`'s splice). */
+    mcpWrite?: {
+        name: string;
+        def: McpServerDef;
+    };
+    /** Only set (and only meaningful) when `kind === "kiro-approved-env-vars"`
+     * and `action === "create"`: the full, already-deduplicated array to
+     * write as `kiroAgent.mcpApprovedEnvVars` — a union of whatever was
+     * already there plus every name Trellis's canonical MCP config needs
+     * for Kiro, never a subtraction (trellis-kiro-approved-env-vars
+     * design.md D3/D4). */
+    approvedEnvVars?: string[];
+}
+export interface AdapterVerifyResult {
+    ok: boolean;
+    /** Present only when ok is false — what didn't match canonical. */
+    mismatches?: string[];
+}
+export interface TrellisAdapter {
+    readonly name: string;
+    readonly id: AgentId;
+    /** Does this agent exist on this machine, and what version. No side effects. */
+    probe(): Promise<AdapterProbeResult>;
+    /**
+     * Diffs canonical state against this agent's current on-disk state to
+     * produce a plan. Read-only against that state — it must never write —
+     * but it does read (e.g. `lstat` each target) because "create" vs.
+     * "remove" vs. no-op vs. conflict can't be decided from canonical alone.
+     *
+     * MUST filter every scopable item (skills, subagent profiles, memory
+     * entries, MCP servers) through its `scope` field before planning any
+     * change for it — an item scoped away from `this.id` must produce no
+     * plan item at all, not a plan item that's later skipped. Use
+     * `resolveScope(item.scope).includes(this.id)`. See docs/architecture.md
+     * "Private / agent-specific capabilities" — the default (`scope`
+     * omitted) is "all agents," so this filter is a no-op for the common
+     * case and only actually excludes anything when a capability was
+     * explicitly restricted.
+     *
+     * MUST also produce "remove" items: an on-disk symlink whose realpath
+     * resolves inside the canonical source, but whose corresponding entry no
+     * longer exists in `canonical` (or was just scoped away from `this.id`)
+     * is stale and belongs in the plan as a removal — not silently left
+     * behind. This is the delete half of "add once, remove once, reaches
+     * every agent"; a plan() that only ever emits "create" items has an
+     * add-only implementation regardless of what the roadmap says.
+     *
+     * MUST NOT plan removal of a path that isn't a symlink Trellis can prove
+     * it created (realpath outside the canonical source) — that's a real
+     * conflict, not a stale entry, and MUST instead produce a "conflict"
+     * plan item so it's visible in the same report as everything else,
+     * rather than only surfacing when `apply()` gets to it.
+     */
+    plan(canonical: CanonicalSource): Promise<AdapterPlanItem[]>;
+    /**
+     * Perform the diff. Must be idempotent and safely re-runnable: applying
+     * a "create" item against an already-correct symlink is a no-op, and
+     * applying a "remove" item against an already-gone path is a no-op.
+     *
+     * MUST treat every "conflict" item as report-only: no filesystem
+     * operation, and MUST NOT throw or abort the rest of the plan because
+     * of it — a conflict on one item must never prevent every other, unrelated
+     * item in the same plan from being applied. The caller (e.g. `trellis
+     * sync`) is responsible for surfacing conflicts and failing the overall
+     * command (non-zero exit), not `apply()` per item.
+     */
+    apply(plan: AdapterPlanItem[]): Promise<void>;
+    /** Re-read the agent's own state and confirm it matches canonical. */
+    verify(canonical: CanonicalSource): Promise<AdapterVerifyResult>;
+}
+/** Convenience used by every adapter's `plan()` — see the scope-filtering
+ * obligation documented above. */
+export declare function isInScope(id: AgentId, scope: Parameters<typeof resolveScope>[0]): boolean;

package/dist/core/adapter.js

@@ -0,0 +1,16 @@
+/**
+ * The adapter contract every agent integration (Claude Code, Codex, Kiro,
+ * pi) must implement. See docs/architecture.md "Adapter contract" for the
+ * rules each method must follow — in particular: `apply` must never
+ * overwrite fields it doesn't own, and `verify` must re-read the agent's
+ * own state rather than trust that `apply` succeeded.
+ *
+ * No adapter exists yet (see docs/roadmap.md P1/P2/P4). This interface is
+ * the contract they'll be built against.
+ */
+import { resolveScope } from "./types.js";
+/** Convenience used by every adapter's `plan()` — see the scope-filtering
+ * obligation documented above. */
+export function isInScope(id, scope) {
+    return resolveScope(scope).includes(id);
+}

package/dist/core/canonical.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Loads `~/.trellis/` into a `CanonicalSource`. Global only — no `root`
+ * parameter, no workspace merge (docs/architecture.md "Global vs.
+ * workspace scope"). See openspec/changes/trellis-sync-p1/specs/
+ * canonical-source-loading/spec.md for the exact contract this implements.
+ */
+import type { CanonicalSource } from "./types.js";
+/**
+ * `homeDir` defaults to the real `~` and is only ever overridden for tests
+ * and `scripts/sandbox.sh` — the same seam P0's probes use
+ * (src/probes/*.ts) and for the same reason: never touch a developer's
+ * real dotfiles from a test. It is not a workspace/project root — see
+ * specs/canonical-source-loading's global-only requirement, which this
+ * parameter does not weaken.
+ */
+export declare function loadCanonicalSource(homeDir?: string): CanonicalSource;

package/dist/core/canonical.js

@@ -0,0 +1,148 @@
+/**
+ * Loads `~/.trellis/` into a `CanonicalSource`. Global only — no `root`
+ * parameter, no workspace merge (docs/architecture.md "Global vs.
+ * workspace scope"). See openspec/changes/trellis-sync-p1/specs/
+ * canonical-source-loading/spec.md for the exact contract this implements.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { ALL_AGENTS } from "./types.js";
+function trellisRoot(homeDir) {
+    return join(homeDir, ".trellis");
+}
+function listMarkdownFiles(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((name) => name.endsWith(".md"))
+        .map((name) => ({ name: basename(name, ".md"), file: join(dir, name) }));
+}
+function listSkillDirs(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const skills = [];
+    for (const name of entries) {
+        const skillDir = join(dir, name);
+        try {
+            if (statSync(skillDir).isDirectory()) {
+                skills.push({ name, dir: skillDir });
+            }
+        }
+        catch {
+            // unreadable/broken entry — skip, not a load failure
+        }
+    }
+    return skills;
+}
+function loadScopeYaml(path) {
+    if (!existsSync(path)) {
+        return {};
+    }
+    const parsed = parseYaml(readFileSync(path, "utf-8"));
+    return (parsed ?? {});
+}
+function loadServersYaml(path) {
+    if (!existsSync(path)) {
+        return { servers: {}, knownHostInjected: [] };
+    }
+    const parsed = (parseYaml(readFileSync(path, "utf-8")) ?? {});
+    return {
+        servers: parsed.servers ?? {},
+        knownHostInjected: parsed.known_host_injected ?? [],
+        hub: parsed.hub,
+    };
+}
+function loadSecretsPolicyYaml(path, homeDir) {
+    if (!existsSync(path)) {
+        return { allowedVars: [], rejectPatterns: [] };
+    }
+    const parsed = (parseYaml(readFileSync(path, "utf-8")) ?? {});
+    return {
+        allowedVars: parsed.allowed_vars ?? [],
+        rejectPatterns: (parsed.reject_patterns ?? []).map((pattern) => new RegExp(pattern)),
+        envFile: parsed.env_file ? parsed.env_file.replace(/^~(?=$|\/)/, homeDir) : undefined,
+    };
+}
+/** `undefined` if the name has no entry in scope.yaml's map — "shared with
+ * all four agents," the default. A recognized but empty list is left as
+ * authored (an explicitly agent-less scope), not coerced to "all". */
+function scopeFor(map, name) {
+    return map?.[name];
+}
+function validAgentIds(scope) {
+    if (!scope)
+        return true;
+    return scope.every((id) => ALL_AGENTS.includes(id));
+}
+/**
+ * `homeDir` defaults to the real `~` and is only ever overridden for tests
+ * and `scripts/sandbox.sh` — the same seam P0's probes use
+ * (src/probes/*.ts) and for the same reason: never touch a developer's
+ * real dotfiles from a test. It is not a workspace/project root — see
+ * specs/canonical-source-loading's global-only requirement, which this
+ * parameter does not weaken.
+ */
+export function loadCanonicalSource(homeDir = homedir()) {
+    const root = trellisRoot(homeDir);
+    if (!existsSync(root)) {
+        throw new Error(`No canonical source at ${root}. Create it before running trellis sync — see docs/architecture.md's canonical schema.`);
+    }
+    const diagnostics = [];
+    const scopeYaml = loadScopeYaml(join(root, "scope.yaml"));
+    const skillDirs = listSkillDirs(join(root, "skills"));
+    const knownSkillNames = new Set(skillDirs.map((s) => s.name));
+    const skills = skillDirs.map(({ name, dir }) => ({ name, dir, scope: scopeFor(scopeYaml.skills, name) }));
+    const agentFiles = listMarkdownFiles(join(root, "agents"));
+    const knownAgentProfileNames = new Set(agentFiles.map((a) => a.name));
+    const agents = agentFiles.map(({ name, file }) => ({
+        name,
+        file,
+        scope: scopeFor(scopeYaml.agents, name),
+    }));
+    const memoryFiles = listMarkdownFiles(join(root, "memories"));
+    const knownMemoryNames = new Set(memoryFiles.map((m) => m.name));
+    const memories = memoryFiles.map(({ name, file }) => ({
+        name,
+        file,
+        scope: scopeFor(scopeYaml.memories, name),
+    }));
+    for (const [section, known] of [
+        ["skills", knownSkillNames],
+        ["agents", knownAgentProfileNames],
+        ["memories", knownMemoryNames],
+    ]) {
+        const map = scopeYaml[section];
+        for (const name of Object.keys(map ?? {})) {
+            if (!known.has(name)) {
+                diagnostics.push(`scope.yaml: "${section}.${name}" does not match any known ${section.slice(0, -1)} — ignored`);
+            }
+            else if (!validAgentIds(map?.[name])) {
+                diagnostics.push(`scope.yaml: "${section}.${name}" lists an unrecognized agent id — ignored`);
+            }
+        }
+    }
+    return {
+        instructionsFile: join(root, "agents.md"),
+        skills,
+        agents,
+        memories,
+        mcp: loadServersYaml(join(root, "mcp", "servers.yaml")),
+        // P2's pre-write guard (src/adapters/mcpPlan.ts) uses its own narrow,
+        // hardcoded floor instead of this field — see design.md D1 in
+        // trellis-secrets-audit-p3.
+        secretsPolicy: loadSecretsPolicyYaml(join(root, "secrets.policy.yaml"), homeDir),
+        diagnostics,
+    };
+}