agent-trellis 0.14.0 → 0.15.0

package/dist/commands/migrateWorkspace.js

@@ -0,0 +1,197 @@
+/**
+ * `trellis migrate --workspace` — absorbs a repo's existing project-level
+ * agent config (all six agents' MCP files + root AGENTS.md) into
+ * `.agents/`, then re-renders (trellis-workspace-scope group 4).
+ *
+ * Flow: plan (pure, `src/lib/workspaceMigrate.ts`) → refuse on unresolved
+ * conflicts → one backup session named `workspace-<repo-hash>` covering
+ * every write (task 4.6 — `.agents/` writes, the secret-store extraction,
+ * the marker-headed AGENTS.md rewrite, and the cascade render, so a
+ * single `trellis rollback` restores originals and removes generated
+ * `.agents/` content) → post-migration equivalence report (task 4.7).
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { ALL_AGENTS } from "../core/types.js";
+import { ensureGitignoreEntry, loadCanonicalSource, writeSecretsPolicyExtraction } from "../core/canonical.js";
+import { openBackupSession } from "../lib/backup.js";
+import { writeLocalSecretValue } from "../lib/secretEnv.js";
+import { findWorkspaceRoot } from "../lib/workspace.js";
+import { upsertWorkspaceServer } from "../lib/workspaceConfig.js";
+import { INSTRUCTIONS_MARKER } from "../lib/workspaceFiles.js";
+import { recordWorkspaceRendered, renderWorkspaceManifestEntry } from "../lib/workspaceMcp.js";
+import { collectWorkspaceMigratePlan, readWorkspaceAgentMcpDefsForApply } from "../lib/workspaceMigrate.js";
+import { collectMcpSyncReport } from "./mcp.js";
+import { collectSyncReport } from "./sync.js";
+import { defaultLocalSecretsEnvFilePath, DEFAULT_LOCAL_SECRETS_ENV_FILE_TILDE } from "./migrate.js";
+/** Task 4.6's `<repo-hash>`: stable per checkout path, short enough to
+ * stay readable in a backups listing. */
+function repoHash(workspaceRoot) {
+    return createHash("sha256").update(workspaceRoot).digest("hex").slice(0, 12);
+}
+/**
+ * Applies one plan item. MCP items go through `upsertWorkspaceServer`
+ * (which serializes the snake_case shape and fills `version`); the
+ * extract-secret companion write mirrors the global migrate's
+ * `applyStaticEnvExtraction` — real value re-read from the SOURCE file at
+ * apply time, never carried on the plan (D9). Instructions import writes
+ * `.agents/AGENTS.md` and rewrites the root file marker-headed in place
+ * (a `file-overwrite` op — rollback restores the original unmarked file).
+ */
+function applyWorkspaceMigrateItem(item, plan, homeDir, backup) {
+    if (item.kind === "mcp" && (item.action === "create" || item.action === "extract-secret") && item.mcpDef) {
+        upsertWorkspaceServer(plan.workspaceRoot, item.name, item.mcpDef, backup);
+        // Adopt the source entries: every agent file this name came from gets
+        // a manifest ownership record, so the cascade render owns the entry
+        // (bringing it to Trellis's canonical render) instead of conflict-
+        // guarding on it as user-authored content. Without this the migration
+        // would import into .agents/ and then immediately conflict on the
+        // very files it absorbed.
+        for (const agent of item.sources) {
+            recordWorkspaceRendered(plan.workspaceRoot, agent, item.name, renderWorkspaceManifestEntry(agent, item.name, item.mcpDef), backup);
+        }
+        if (item.action === "extract-secret" && item.extractVarName && item.extractTargetPath && item.extractSourceKey && item.extractSourceAgent) {
+            const realValue = readWorkspaceAgentMcpDefsForApply(plan.workspaceRoot, item.extractSourceAgent)
+                .entries.find((e) => e.name === item.name)?.def.staticEnv?.[item.extractSourceKey];
+            if (realValue !== undefined) {
+                if (item.extractTargetPath === defaultLocalSecretsEnvFilePath(homeDir)) {
+                    ensureGitignoreEntry(join(homeDir, ".trellis", ".gitignore"), "mcp/servers.local.env", backup);
+                }
+                writeLocalSecretValue(item.extractTargetPath, item.extractVarName, realValue, backup);
+                const policyResult = writeSecretsPolicyExtraction(join(homeDir, ".trellis", "secrets.policy.yaml"), { varName: item.extractVarName, envFilePath: DEFAULT_LOCAL_SECRETS_ENV_FILE_TILDE }, backup);
+                // A failed policy write leaves the extracted var unresolvable —
+                // the cascade render then refuses with a confusing conflict. Say
+                // why, plainly, while the run is still honest about it.
+                if (!policyResult.ok) {
+                    console.error(`warning: extracted ${item.extractVarName} but could not record it in secrets.policy.yaml: ${policyResult.error}`);
+                }
+            }
+            // undefined = the source changed between plan and apply; the safe
+            // def (name-only reference) is still imported, matching the global
+            // migrate's "nothing left to extract" behavior.
+        }
+        return;
+    }
+    if (item.kind === "instructions" && item.action === "create" && item.sourceContent !== undefined) {
+        const target = join(plan.workspaceRoot, ".agents", "AGENTS.md");
+        mkdirSync(dirname(target), { recursive: true });
+        backup.writeFile(target, item.sourceContent);
+        // Rewrite the root file marker-headed NOW so the cascade instructions
+        // sync sees current === rendered (no-op) instead of conflicting on an
+        // unmarked file. Byte-identical to planWorkspaceInstructions' render.
+        backup.writeFile(join(plan.workspaceRoot, "AGENTS.md"), `${INSTRUCTIONS_MARKER}\n\n${item.sourceContent}`);
+    }
+}
+export async function runMigrateWorkspace(opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const workspaceRoot = opts.workspaceDir ?? findWorkspaceRoot(process.cwd()) ?? process.cwd();
+    // --- flag validation (raw strings arrive from cli.ts) ---
+    const choose = {};
+    for (const raw of opts.choose ?? []) {
+        const eq = raw.indexOf("=");
+        const agent = eq === -1 ? "" : raw.slice(eq + 1);
+        if (eq === -1 || !ALL_AGENTS.includes(agent)) {
+            console.error(`--choose must be name=agentId with agentId one of: ${ALL_AGENTS.join(", ")} (got "${raw}")`);
+            return { exitCode: 1 };
+        }
+        choose[raw.slice(0, eq)] = agent;
+    }
+    if (opts.dedup !== undefined && opts.dedup !== "drop" && opts.dedup !== "override") {
+        console.error(`--dedup must be drop or override (got ${opts.dedup})`);
+        return { exitCode: 1 };
+    }
+    const secretsPolicy = loadCanonicalSource({ homeDir, workspaceDir: null }).secretsPolicy;
+    const plan = collectWorkspaceMigratePlan({ workspaceRoot, homeDir, secretsPolicy, choose, dedup: opts.dedup });
+    // Task 4.3/4.2: a real run with ANY unresolved conflict writes nothing —
+    // the user resolves (via --choose, or by fixing the source) and re-runs.
+    const conflicts = plan.items.filter((i) => i.action === "conflict");
+    if (conflicts.length > 0 && !opts.dryRun) {
+        printWorkspaceMigratePlan(plan, false);
+        console.error(`\n${conflicts.length} unresolved conflict(s) — nothing was written. Resolve each and re-run.`);
+        return { exitCode: 1 };
+    }
+    // Task 4.7's "before" half: what each agent's project config held.
+    const beforeByAgent = new Map();
+    for (const item of plan.items) {
+        if (item.kind !== "mcp" || item.action === "skip-local")
+            continue;
+        for (const agent of item.sources) {
+            beforeByAgent.set(agent, [...new Set([...(beforeByAgent.get(agent) ?? []), item.name])]);
+        }
+    }
+    let equivalence;
+    if (!opts.dryRun) {
+        const actionable = plan.items.filter((i) => i.action === "create" || i.action === "extract-secret");
+        const backup = openBackupSession(homeDir, `workspace-${repoHash(workspaceRoot)}`);
+        for (const item of actionable) {
+            applyWorkspaceMigrateItem(item, plan, homeDir, backup);
+        }
+        // Cascade render through the SAME session (task 4.6): MCP artifacts
+        // for every managed agent, so one `trellis rollback` undoes the whole
+        // migration. Instructions only cascade when an instructions item was
+        // actually applied — scoping the side effects to what migration
+        // touched, same discipline as `mcp add --workspace`'s MCP-only
+        // cascade.
+        await collectMcpSyncReport({ homeDir, workspaceDir: workspaceRoot, backupSession: backup });
+        if (actionable.some((i) => i.kind === "instructions")) {
+            await collectSyncReport({ target: "instructions", homeDir, workspaceDir: workspaceRoot, backupSession: backup });
+        }
+        backup.finalize();
+        // Task 4.7's "after" half: a fresh dry-run render against the
+        // migrated `.agents/` proves the absorbed config now delivers.
+        const after = await collectMcpSyncReport({ homeDir, workspaceDir: workspaceRoot, dryRun: true });
+        equivalence = {
+            agents: after.reports
+                .filter((r) => r.present)
+                .map((r) => ({
+                agent: r.agent,
+                before: (beforeByAgent.get(r.agent) ?? []).sort(),
+                after: r.items.filter((i) => i.kind === "mcp" && i.layer === "workspace" && i.mcpWrite).map((i) => i.mcpWrite.name).sort(),
+            }))
+                .filter((a) => a.before.length > 0 || a.after.length > 0),
+        };
+    }
+    if (opts.json) {
+        console.log(JSON.stringify({ ...plan, ...(equivalence ? { equivalence } : {}) }, null, 2));
+    }
+    else {
+        printWorkspaceMigratePlan(plan, opts.dryRun ?? false);
+        if (equivalence)
+            printEquivalence(equivalence);
+    }
+    return { exitCode: conflicts.length > 0 ? 1 : 0 };
+}
+export function printWorkspaceMigratePlan(plan, dryRun) {
+    console.log(`${dryRun ? "[dry run] " : ""}migrate --workspace ${plan.workspaceRoot}`);
+    if (plan.items.length === 0) {
+        console.log("  nothing to migrate");
+        return;
+    }
+    for (const item of plan.items) {
+        const label = item.kind === "mcp" ? `mcp server "${item.name}"` : "instructions (AGENTS.md)";
+        console.log(`  [${item.action}] ${label} — ${item.detail}`);
+        if (item.defs) {
+            for (const [agent, def] of Object.entries(item.defs)) {
+                console.log(`      ${agent}: ${JSON.stringify(def)}`);
+            }
+        }
+        if (item.rotationAdvisory) {
+            console.log(`      ⚠ ${item.rotationAdvisory}`);
+        }
+        if (item.remediation) {
+            console.log(`      → ${item.remediation}`);
+        }
+    }
+}
+function printEquivalence(equivalence) {
+    console.log("equivalence (before → rendered after):");
+    if (equivalence.agents.length === 0) {
+        console.log("  no managed agent renders workspace servers on this machine");
+        return;
+    }
+    for (const { agent, before, after } of equivalence.agents) {
+        console.log(`  ${agent}: [${before.join(", ") || "—"}] → [${after.join(", ") || "—"}]`);
+    }
+}

package/dist/commands/rollback.js

@@ -8,7 +8,7 @@
  * already hold themselves to for every other kind of conflict.
  */
 import { createHash } from "node:crypto";
-import { cpSync, existsSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { readlink, rm, symlink } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -63,84 +63,110 @@ async function currentLinkTarget(path) {
         return undefined;
     }
 }
-async function planOperation(homeDir, runId, op) {
+/** Probes the path's real on-disk state once, then caches it in `sim`;
+ * later ops for the same path see the simulated rewinds, not the disk. */
+async function simStateFor(path, sim) {
+    const cached = sim.get(path);
+    if (cached)
+        return cached;
+    let state;
+    // readlink first: it detects symlinks (even dangling ones) that
+    // existsSync would miss or misclassify.
+    const link = await currentLinkTarget(path);
+    if (link !== undefined) {
+        state = { kind: "symlink", target: link };
+    }
+    else if (!existsSync(path)) {
+        state = { kind: "absent" };
+    }
+    else if (statSync(path).isDirectory()) {
+        let digest;
+        try {
+            digest = directoryDigest(path);
+        }
+        catch {
+            digest = undefined;
+        }
+        state = { kind: "dir", digest };
+    }
+    else {
+        state = { kind: "file", hash: sha256(readFileSync(path, "utf-8")) };
+    }
+    sim.set(path, state);
+    return state;
+}
+async function planOperation(homeDir, runId, op, sim) {
     const runDir = join(backupsRoot(homeDir), runId);
+    const state = await simStateFor(op.path, sim);
     switch (op.kind) {
         case "file-create":
         case "file-overwrite": {
-            if (!existsSync(op.path)) {
+            if (state.kind === "absent") {
                 return { action: "already-reverted", path: op.path, description: `${op.path} no longer exists — nothing to undo` };
             }
-            const currentHash = sha256(readFileSync(op.path, "utf-8"));
-            if (currentHash !== op.afterHash) {
+            if (state.kind !== "file" || state.hash !== op.afterHash) {
                 return { action: "conflict", path: op.path, description: `${op.path} has changed since this run — left untouched` };
             }
             if (op.kind === "file-create") {
+                sim.set(op.path, { kind: "absent" });
                 return { action: "restore", path: op.path, description: `delete ${op.path} (created by this run)` };
             }
+            sim.set(op.path, { kind: "file", hash: op.beforeHash });
             return { action: "restore", path: op.path, description: `restore ${op.path} to its content before this run (${join(runDir, op.beforeFile)})` };
         }
         case "symlink-create":
         case "symlink-repair": {
-            const current = await currentLinkTarget(op.path);
-            if (current === undefined) {
+            if (state.kind === "absent") {
                 return { action: "already-reverted", path: op.path, description: `${op.path} no longer exists — nothing to undo` };
             }
-            if (current !== op.afterLinkTarget) {
+            if (state.kind !== "symlink" || state.target !== op.afterLinkTarget) {
                 return { action: "conflict", path: op.path, description: `${op.path} points somewhere else now — left untouched` };
             }
             if (op.kind === "symlink-create") {
+                sim.set(op.path, { kind: "absent" });
                 return { action: "restore", path: op.path, description: `remove ${op.path} (created by this run)` };
             }
+            sim.set(op.path, { kind: "symlink", target: op.beforeLinkTarget });
             return { action: "restore", path: op.path, description: `repoint ${op.path} back to ${op.beforeLinkTarget}` };
         }
         case "symlink-remove": {
-            if (existsSync(op.path)) {
+            if (state.kind !== "absent") {
                 return { action: "conflict", path: op.path, description: `${op.path} exists again since this run — left untouched` };
             }
+            sim.set(op.path, { kind: "symlink", target: op.beforeLinkTarget });
             return { action: "restore", path: op.path, description: `recreate ${op.path} -> ${op.beforeLinkTarget}` };
         }
         // Historical `dir-remove` operations remain existence-only because they
         // predate directory manifests. New directory creates/replacements carry a
         // deterministic digest, so remote Skill rollback refuses an edited tree.
         case "dir-create": {
-            if (!existsSync(op.path)) {
+            if (state.kind === "absent") {
                 return { action: "already-reverted", path: op.path, description: `${op.path} no longer exists — nothing to undo` };
             }
-            if (op.afterDigest !== undefined) {
-                let digest;
-                try {
-                    digest = directoryDigest(op.path);
-                }
-                catch {
-                    return { action: "conflict", path: op.path, description: `${op.path} can no longer be read safely — left untouched` };
-                }
-                if (digest !== op.afterDigest) {
-                    return { action: "conflict", path: op.path, description: `${op.path} has changed since this run — left untouched` };
-                }
+            if (op.afterDigest !== undefined && (state.kind !== "dir" || state.digest !== op.afterDigest)) {
+                return { action: "conflict", path: op.path, description: `${op.path} has changed since this run — left untouched` };
             }
+            sim.set(op.path, { kind: "absent" });
             return { action: "restore", path: op.path, description: `delete ${op.path} (created by this run)` };
         }
         case "dir-remove": {
-            if (existsSync(op.path)) {
+            if (state.kind !== "absent") {
                 return { action: "conflict", path: op.path, description: `${op.path} exists again since this run — left untouched` };
             }
+            // The rewind's content comes from the beforeDir snapshot at apply
+            // time; its digest isn't recorded, so mark it unknown for any
+            // (in practice nonexistent) earlier op on the same path.
+            sim.set(op.path, { kind: "dir", digest: undefined });
             return { action: "restore", path: op.path, description: `recreate ${op.path} from its content before this run (${join(runDir, op.beforeDir)})` };
         }
         case "dir-replace": {
-            if (!existsSync(op.path)) {
+            if (state.kind === "absent") {
                 return { action: "already-reverted", path: op.path, description: `${op.path} no longer exists — nothing to undo` };
             }
-            let digest;
-            try {
-                digest = directoryDigest(op.path);
-            }
-            catch {
-                return { action: "conflict", path: op.path, description: `${op.path} can no longer be read safely — left untouched` };
-            }
-            if (digest !== op.afterDigest) {
+            if (state.kind !== "dir" || state.digest !== op.afterDigest) {
                 return { action: "conflict", path: op.path, description: `${op.path} has changed since this run — left untouched` };
             }
+            sim.set(op.path, { kind: "dir", digest: undefined });
             return { action: "restore", path: op.path, description: `restore ${op.path} to its content before this run (${join(runDir, op.beforeDir)})` };
         }
     }
@@ -149,11 +175,15 @@ export async function collectRollbackPlan(homeDirInput, runIdInput) {
     const homeDir = homeDirInput ?? homedir();
     const runId = resolveRunId(homeDir, runIdInput);
     const manifest = loadManifest(homeDir, runId);
-    const items = [];
-    for (const op of manifest.operations) {
-        items.push(await planOperation(homeDir, runId, op));
+    // Plan newest-first against the simulated undo, then report in the
+    // manifest's original chronological order.
+    const sim = new Map();
+    const planned = [];
+    for (const op of [...manifest.operations].reverse()) {
+        planned.push(await planOperation(homeDir, runId, op, sim));
     }
-    return { runId, items };
+    planned.reverse();
+    return { runId, items: planned };
 }
 async function restoreOperation(homeDir, runId, op) {
     const runDir = join(backupsRoot(homeDir), runId);

package/dist/commands/skill.d.ts

@@ -49,6 +49,18 @@ export interface SkillAddPlan {
 }
 export declare function collectSkillAddPlan(name: string, fromPath: string, homeDir?: string): SkillAddPlan;
 export declare function applySkillAddPlan(plan: SkillAddPlan, homeDir?: string, backup?: BackupSession): void;
+/** The workspace twin of `collectSkillAddPlan` (trellis-workspace-scope
+ * task 3.4): same source validation, destination is `.agents/skills/`
+ * instead of the global canonical skills dir. */
+export declare function collectSkillAddWorkspacePlan(name: string, fromPath: string, workspaceRoot: string): SkillAddPlan;
+export declare function applySkillAddWorkspacePlan(plan: SkillAddPlan, workspaceRoot: string, backup?: BackupSession): void;
+/** Same own-backup-session + cascade-sync posture as
+ * `applySkillAddWithSync`, scoped to the workspace layer. */
+export declare function applySkillAddWorkspaceWithSync(plan: SkillAddPlan, workspaceRoot: string, opts?: {
+    homeDir?: string;
+    dryRun?: boolean;
+    backupSession?: BackupSession;
+}): Promise<SkillAddOutcome>;
 export interface SkillAddOutcome {
     plan: SkillAddPlan;
     sync?: SyncReport;
@@ -70,6 +82,8 @@ export declare function runSkillAdd(name: string, fromPath: string, opts?: {
     homeDir?: string;
     json?: boolean;
     dryRun?: boolean;
+    workspace?: boolean;
+    workspaceDir?: string;
 }): Promise<{
     exitCode: number;
 }>;

package/dist/commands/skill.js

@@ -21,6 +21,7 @@ import { openBackupSession } from "../lib/backup.js";
 import { collectSyncReport, printReport as printSyncReport } from "./sync.js";
 import { remoteSkillProvenance } from "./remoteSkill.js";
 import { describeScope, resolveScopeSelection, sameScope } from "../lib/scopeSelection.js";
+import { findWorkspaceRoot } from "../lib/workspace.js";
 function builtinSkillTemplate() {
     const here = dirname(fileURLToPath(import.meta.url));
     return readFileSync(join(here, "..", "..", "schema", "builtin-skills", "trellis-runtime", "SKILL.md"), "utf8");
@@ -114,6 +115,55 @@ export function applySkillAddPlan(plan, homeDir = homedir(), backup) {
     mkdirSync(dest, { recursive: true });
     cpSync(plan.sourceDir, dest, { recursive: true });
 }
+/** The workspace twin of `collectSkillAddPlan` (trellis-workspace-scope
+ * task 3.4): same source validation, destination is `.agents/skills/`
+ * instead of the global canonical skills dir. */
+export function collectSkillAddWorkspacePlan(name, fromPath, workspaceRoot) {
+    const skillFile = findSkillFile(fromPath);
+    if (!skillFile) {
+        return { name, action: "invalid-source", detail: `${fromPath} has no SKILL.md` };
+    }
+    if (!skillFile.caseCorrect) {
+        return { name, action: "invalid-source", detail: `${fromPath} has skill.md, not case-correct SKILL.md — fix the case first` };
+    }
+    const dest = join(workspaceRoot, ".agents", "skills", name);
+    switch (decideDirImport(fromPath, dest)) {
+        case "create":
+            return { name, action: "create", detail: `will copy from ${fromPath} into .agents/skills/`, sourceDir: fromPath };
+        case "already-present":
+            return { name, action: "already-present", detail: ".agents/skills/ content is already byte-identical" };
+        case "conflict":
+            return { name, action: "conflict", detail: `.agents/skills/${name}/ already exists with different content — resolve by hand` };
+    }
+}
+export function applySkillAddWorkspacePlan(plan, workspaceRoot, backup) {
+    if (plan.action !== "create" || !plan.sourceDir)
+        return;
+    const dest = join(workspaceRoot, ".agents", "skills", plan.name);
+    if (backup) {
+        backup.createDirFromSource(dest, plan.sourceDir);
+        return;
+    }
+    mkdirSync(dest, { recursive: true });
+    cpSync(plan.sourceDir, dest, { recursive: true });
+}
+/** Same own-backup-session + cascade-sync posture as
+ * `applySkillAddWithSync`, scoped to the workspace layer. */
+export async function applySkillAddWorkspaceWithSync(plan, workspaceRoot, opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const ownSession = !opts.dryRun && !opts.backupSession && plan.action === "create" ? openBackupSession(homeDir, "skill-add") : undefined;
+    const session = opts.backupSession ?? ownSession;
+    if (!opts.dryRun && plan.action === "create") {
+        applySkillAddWorkspacePlan(plan, workspaceRoot, session);
+    }
+    ownSession?.finalize();
+    const failed = plan.action === "conflict" || plan.action === "invalid-source";
+    let syncReport;
+    if (!failed && plan.action === "create" && existsSync(join(homeDir, ".trellis"))) {
+        syncReport = await collectSyncReport({ target: "skills", homeDir, workspaceDir: workspaceRoot, dryRun: opts.dryRun });
+    }
+    return { plan, ...(syncReport ? { sync: syncReport } : {}) };
+}
 /**
  * See `applyMcpAddWithSync`'s doc comment (mcp.ts) — same split, same
  * reason: a non-CLI caller needs the structured result a JSON-mode CLI
@@ -139,6 +189,27 @@ export async function applySkillAddWithSync(plan, opts = {}) {
 }
 export async function runSkillAdd(name, fromPath, opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
+    if (opts.workspace) {
+        const workspaceRoot = opts.workspaceDir ?? findWorkspaceRoot(process.cwd());
+        if (!workspaceRoot) {
+            console.error("no .agents/ found here or above — run `trellis init --workspace` first (or pass --workspace from inside the repo)");
+            return { exitCode: 1 };
+        }
+        const plan = collectSkillAddWorkspacePlan(name, fromPath, workspaceRoot);
+        const { sync: syncReport } = await applySkillAddWorkspaceWithSync(plan, workspaceRoot, { homeDir, dryRun: opts.dryRun });
+        const failed = plan.action === "conflict" || plan.action === "invalid-source";
+        if (opts.json) {
+            console.log(JSON.stringify(syncReport ? { ...plan, workspace: workspaceRoot, sync: syncReport } : { ...plan, workspace: workspaceRoot }, null, 2));
+        }
+        else {
+            console.log(`${opts.dryRun ? "[dry run] " : ""}skill add ${name} --workspace`);
+            console.log(`  [${plan.action}] ${plan.detail}`);
+            if (syncReport)
+                printSyncReport(syncReport, opts.dryRun ?? false);
+        }
+        const syncConflict = syncReport?.reports.some((r) => r.items.some((i) => i.action === "conflict")) ?? false;
+        return { exitCode: failed || syncConflict ? 1 : 0 };
+    }
     const plan = collectSkillAddPlan(name, fromPath, homeDir);
     const { sync: syncReport } = await applySkillAddWithSync(plan, { homeDir, dryRun: opts.dryRun });
     const failed = plan.action === "conflict" || plan.action === "invalid-source";

package/dist/commands/sync.d.ts

@@ -34,14 +34,29 @@ export interface RunSyncOptions {
      * does NOT finalize it — only whoever opened it does. Never a CLI
      * flag — standalone `trellis sync` always opens and finalizes its own. */
     backupSession?: BackupSession;
+    /** Force global-only behavior even inside a workspace (`--global-only`). */
+    globalOnly?: boolean;
+    /** Explicit workspace root — the test/sandbox seam. CLI discovery walks
+     * up from cwd via `findWorkspaceRoot`; this overrides it (null = none). */
+    workspaceDir?: string | null;
+    /** `--check`: compute the plan, write nothing, exit non-zero when any
+     * rendered artifact is stale or missing (CI/pre-commit freshness gate,
+     * trellis-workspace-scope design D7). Implies dry-run. */
+    check?: boolean;
 }
 export interface AgentSyncReport {
     agent: AgentId;
     present: boolean;
     items: AdapterPlanItem[];
+    /** zcode's reverse-precedence notices (workspace shadowing that zcode
+     * resolves user-level-first) — warnings, not conflicts: the write still
+     * happens. */
+    warnings?: string[];
 }
 export interface SyncReport {
     reports: AgentSyncReport[];
+    /** Workspace root when a `.agents/` layer participated in this run. */
+    workspaceRoot?: string;
 }
 export declare function collectSyncReport(opts?: RunSyncOptions): Promise<SyncReport>;
 export declare function runSync(opts?: RunSyncOptions): Promise<{
@@ -50,4 +65,4 @@ export declare function runSync(opts?: RunSyncOptions): Promise<{
 /** 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;
+export declare function printReport(report: SyncReport, dryRun: boolean, check?: boolean): void;

package/dist/commands/sync.js

@@ -14,6 +14,9 @@ import { PiAdapter } from "../adapters/pi.js";
 import { KimiCodeAdapter } from "../adapters/kimi-code.js";
 import { ZcodeAdapter } from "../adapters/zcode.js";
 import { openBackupSession } from "../lib/backup.js";
+import { findWorkspaceRoot } from "../lib/workspace.js";
+import { applyWorkspaceFiles, planWorkspaceFiles } from "../lib/workspaceFiles.js";
+import { workspacePrecedenceWarnings } from "../lib/workspaceMcp.js";
 const ADAPTER_FACTORY = {
     "claude-code": (homeDir) => new ClaudeCodeAdapter(homeDir),
     codex: (homeDir) => new CodexAdapter(homeDir),
@@ -30,7 +33,11 @@ function buildAdapters(homeDir, managedAgents) {
 }
 export async function collectSyncReport(opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
-    const loaded = loadCanonicalSource(homeDir);
+    // Workspace participation is automatic inside a repo carrying `.agents/`
+    // and revocable via --global-only; outside any workspace (or when it
+    // resolves null) the load is byte-identical to before.
+    const workspaceDir = opts.globalOnly ? null : (opts.workspaceDir !== undefined ? opts.workspaceDir : findWorkspaceRoot(process.cwd()));
+    const loaded = loadCanonicalSource({ homeDir, workspaceDir });
     // A single override point, not two: every downstream read of "who's
     // managed" — the adapter list built here AND each adapter's own
     // in-scope filtering via `canonical.managedAgents` — must agree, or a
@@ -39,9 +46,10 @@ export async function collectSyncReport(opts = {}) {
     const canonical = opts.managedAgents ? { ...loaded, managedAgents: opts.managedAgents } : loaded;
     const reports = [];
     // Own session only when the caller didn't share one (trellis-backup-
-    // rollback D2) — dry-run never opens or writes one, there's nothing to
-    // record.
-    const ownSession = !opts.dryRun && !opts.backupSession ? openBackupSession(homeDir, "sync") : undefined;
+    // rollback D2) — dry-run/check never opens or writes one, there's
+    // nothing to record.
+    const writeMode = !opts.dryRun && !opts.check;
+    const ownSession = writeMode && !opts.backupSession ? openBackupSession(homeDir, "sync") : undefined;
     const backup = opts.backupSession ?? ownSession;
     for (const adapter of buildAdapters(homeDir, canonical.managedAgents)) {
         const probeResult = await adapter.probe();
@@ -53,6 +61,7 @@ export async function collectSyncReport(opts = {}) {
         // `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");
+        let wsItems = planWorkspaceFiles(adapter.id, canonical);
         if (opts.target) {
             // CLI/option vocabulary is plural ("skills"/"instructions",
             // matching `trellis sync skills`); AdapterPlanItem.kind is singular
@@ -63,14 +72,18 @@ export async function collectSyncReport(opts = {}) {
             // sync" even with real create items pending).
             const kind = opts.target === "skills" ? "skill" : "instructions";
             items = items.filter((item) => item.kind === kind || (kind === "skill" && item.kind === "zcode-skill-control"));
+            wsItems = wsItems.filter((item) => item.kind === kind);
         }
-        if (!opts.dryRun) {
+        const allItems = [...items, ...wsItems];
+        if (writeMode) {
             await adapter.apply(items, backup);
+            applyWorkspaceFiles(adapter.id, canonical, wsItems, backup);
         }
-        reports.push({ agent: adapter.id, present: true, items });
+        const warnings = workspacePrecedenceWarnings(adapter.id, canonical);
+        reports.push({ agent: adapter.id, present: true, items: allItems, ...(warnings.length > 0 ? { warnings } : {}) });
     }
     ownSession?.finalize();
-    return { reports };
+    return { reports, ...(canonical.workspace ? { workspaceRoot: canonical.workspace.root } : {}) };
 }
 export async function runSync(opts = {}) {
     let report;
@@ -85,22 +98,34 @@ export async function runSync(opts = {}) {
         console.log(JSON.stringify(report, null, 2));
     }
     else {
-        printReport(report, opts.dryRun ?? false);
+        printReport(report, opts.dryRun ?? false, opts.check ?? false);
     }
     const hasConflict = report.reports.some((r) => r.items.some((i) => i.action === "conflict"));
+    if (opts.check) {
+        // Freshness gate: any pending write (create/remove) or conflict means
+        // the rendered artifacts are stale — exit non-zero, having written
+        // nothing.
+        const hasPending = report.reports.some((r) => r.items.some((i) => i.action !== "conflict"));
+        return { exitCode: hasPending || hasConflict ? 1 : 0 };
+    }
     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) {
+export function printReport(report, dryRun, check = false) {
     if (dryRun)
         console.log("[dry run]");
+    if (check)
+        console.log("[check]");
+    if (report.workspaceRoot) {
+        console.log(`Workspace layer: ${report.workspaceRoot} (.agents/)`);
+    }
     if (report.reports.length === 0) {
         console.log("No managed agents yet — run `trellis onboard` or list agent ids in ~/.trellis/managed.yaml.");
         return;
     }
-    for (const { agent, present, items } of report.reports) {
+    for (const { agent, present, items, warnings } of report.reports) {
         if (!present) {
             console.log(`—  ${agent} (not installed)`);
             continue;
@@ -110,12 +135,20 @@ export function printReport(report, dryRun) {
         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}`);
+        else {
+            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.layer === "workspace" ? " (workspace)" : ""} ${item.description}`);
+                // Same as mcp.ts's printer: a conflict's remediation IS the fix —
+                // never leave the user at "left untouched" with no next step.
+                if (item.remediation)
+                    console.log(`     → ${item.remediation}`);
+            }
+        }
+        for (const warning of warnings ?? []) {
+            console.log(`   ⚠ ${warning}`);
         }
     }
 }