@aefree/pi-plastic 0.4.0

package/tests/plastic-extension-registration.test.ts

@@ -0,0 +1,34 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+
+function main(): void {
+  const indexText = readFileSync(new URL("../index.ts", import.meta.url), "utf8");
+  const packageManifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+  const branchStatusText = readFileSync(new URL("../extensions/plastic-branch-status.ts", import.meta.url), "utf8");
+
+  assert.match(indexText, /parameters:\s*buildParameters\(coreTool\.args\)/, "plastic tools should derive schemas from core args without approval-only parameters");
+  assert.match(indexText, /prepareArguments:\s*config\.prepareArguments/, "plastic tools should wire prepareArguments");
+  assert.match(indexText, /core\.runWithAbortSignal\(signal, async \(\) => coreTool\.execute\(normalizedParams\)\)/, "plastic tools should propagate abort signals into core execution");
+  assert.doesNotMatch(indexText, /authorizationToken|authorizationProvenance|ctx\.ui\.confirm/, "Plastic tool registration must not implement token or UI-confirmation approvals");
+
+  assert.match(indexText, /assignAlias\(input, "message", \["comment", "comments"\]\);/, "plastic_checkin should normalize comment aliases");
+  assert.match(indexText, /assignAlias\(input, "pendingChanges", \["pending_changes"\]\);/, "plastic_switchBranch should normalize pending_changes");
+  assert.match(indexText, /"patch",/, "plastic_patch should be included in registered exports");
+  assert.match(indexText, /"mergeToBranch",/, "plastic_mergeToBranch should be included in registered exports");
+  assert.doesNotMatch(indexText, /"workspaceCreate",/, "plastic_workspaceCreate should remain unregistered until paired cleanup is available");
+  assert.match(indexText, /assignAlias\(input, "toolPath", \["tool_path", "tool"\]\);/, "plastic_patch should normalize toolPath aliases");
+  assert.match(indexText, /assignAlias\(input, "output", \["output_file", "outputFile"\]\);/, "plastic_patch should normalize output aliases");
+  assert.match(indexText, /assignAlias\(input, "titleLike", \["title_like"\]\);/, "plastic_codeReviewFind should normalize title_like");
+  assert.match(indexText, /assignAlias\(input, "keepOnDisk", \["keep_on_disk", "keepOnDisk", "nodisk"\]\);/, "plastic_resolveDeleteChangeConflict should normalize keepOnDisk aliases");
+  assert.match(indexText, /assignAlias\(input, "source", \["sourceBranch", "source_branch", "branch"\]\);/, "plastic_mergeToBranch should normalize source branch aliases");
+  assert.match(indexText, /assignAlias\(input, "cardRef", \["card", "cardCode", "card_code", "codecksCard", "codecks_card"\]\);/, "plastic_mergeToBranch should normalize card aliases");
+  assert.match(indexText, /assignAlias\(input, "source", \["mergeSource", "merge_source"\]\);/, "plastic_finalizeMerge should normalize merge source aliases");
+  assert.match(indexText, /assignAlias\(input, "workdir", \["cwd", "workingDirectory", "working_directory"\]\);/, "plastic tools should normalize workdir aliases");
+  assert.match(indexText, /const enumSchema =/, "plastic tools should expose explicit enum schemas");
+  assert.ok(packageManifest.pi.extensions.includes("./extensions/plastic-branch-status.ts"), "package should register the Plastic branch status extension");
+  assert.doesNotMatch(branchStatusText, /\.setFooter\s*\(/, "Plastic branch status must compose through setStatus rather than replace the footer");
+
+  console.log("PASS: plastic extension registration test succeeded");
+}
+
+main();

package/tests/plastic-live-smoke.test.ts

@@ -0,0 +1,37 @@
+import assert from "node:assert/strict";
+import { resolve } from "node:path";
+import { invokeRegisteredTool } from "./pi-tool-harness.ts";
+
+type ToolEnvelope = {
+  ok?: boolean;
+  data?: Record<string, unknown>;
+};
+
+const parseToolEnvelope = (text: string): ToolEnvelope => {
+  const fencedJson = text.match(/```json\s*([\s\S]*?)\s*```/);
+  assert(fencedJson, "Expected a structured JSON tool result.");
+  return JSON.parse(fencedJson[1]) as ToolEnvelope;
+};
+
+const configuredWorkspace = process.env.PI_PLASTIC_TEST_WORKSPACE?.trim();
+
+if (!configuredWorkspace) {
+  console.log("SKIP: set PI_PLASTIC_TEST_WORKSPACE to run opt-in Plastic live smoke tests");
+  process.exit(0);
+}
+
+const workspace = resolve(configuredWorkspace);
+const status = parseToolEnvelope(await invokeRegisteredTool("plastic_status", { short: true, format: "json" }, workspace));
+assert.equal(status.ok, true, "Expected Plastic status to succeed.");
+const summary = status.data?.summary as Record<string, unknown> | undefined;
+const mergeState = status.data?.mergeState as Record<string, unknown> | undefined;
+assert.equal(summary?.totalPending, 0, "Live smoke tests require a clean workspace.");
+assert.equal(mergeState?.hasMergeInProgress, false, "Live smoke tests require no merge in progress.");
+
+const currentBranch = parseToolEnvelope(await invokeRegisteredTool("plastic_currentBranch", { format: "json" }, workspace));
+assert.equal(currentBranch.data?.branch, "/main", "Live sandbox must be on /main.");
+
+const mainExists = await invokeRegisteredTool("plastic_branchExists", { branch: "/main" }, workspace);
+assert.equal(mainExists.trim(), "true", "Expected plastic_branchExists to find the full /main path.");
+
+console.log("PASS: read-only Plastic live smoke tests passed for the configured sandbox");

package/tests/plastic-mutation-execution.test.ts

@@ -0,0 +1,61 @@
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import { Readable } from "node:stream";
+import { runWithAbortSignal, update } from "../src/plastic-core.ts";
+import { loadRegisteredTools } from "./pi-tool-harness.ts";
+
+const registeredTools = await loadRegisteredTools();
+for (const [name, registeredTool] of registeredTools) {
+  if (!name.startsWith("plastic_") || name === "plastic_tool_search") continue;
+  assert.equal(
+    (registeredTool.parameters as any)?.properties?.authorizationToken,
+    undefined,
+    `${name} must not expose mutation authorization tokens`,
+  );
+}
+
+type SpawnCall = {
+  command: string;
+  args: string[];
+  cwd: string;
+};
+
+function makeSpawn(calls: SpawnCall[], exitCode: number, stderr = "") {
+  return ((command: string, args: readonly string[], options: { cwd: string }) => {
+    calls.push({ command, args: [...args], cwd: options.cwd });
+    const child = new EventEmitter() as any;
+    child.stdout = Readable.from(exitCode === 0 ? ["Updated successfully"] : []);
+    child.stderr = Readable.from(stderr ? [stderr] : []);
+    child.stdin = undefined;
+    child.kill = () => true;
+    process.nextTick(() => child.emit("close", exitCode));
+    return child;
+  }) as any;
+}
+
+const workdir = process.cwd();
+const successfulCalls: SpawnCall[] = [];
+const output = await runWithAbortSignal(
+  undefined,
+  () => update.execute({ workdir }),
+  { spawn: makeSpawn(successfulCalls, 0) },
+);
+assert.equal(output, "Updated successfully");
+assert.deepEqual(successfulCalls, [{
+  command: process.env.PI_PLASTIC_CM_EXECUTABLE?.trim() || "cm",
+  args: ["update", "--dontmerge", "--noinput"],
+  cwd: workdir,
+}], "a directly invoked mutation tool must make one exact cm spawn without approval context");
+
+const failedCalls: SpawnCall[] = [];
+await assert.rejects(
+  runWithAbortSignal(
+    undefined,
+    () => update.execute({ workdir }),
+    { spawn: makeSpawn(failedCalls, 1, "fixture mutation failure") },
+  ),
+  /fixture mutation failure/,
+);
+assert.equal(failedCalls.length, 1, "a failed mutation process must not be retried implicitly");
+
+console.log("PASS: Plastic direct mutation execution tests passed");

package/tests/plastic-patch-command.test.ts

@@ -0,0 +1,118 @@
+import { __plasticPatchInternals } from "../src/plastic-core.ts";
+
+const assert = (condition: boolean, message: string): void =>
+{
+    if (!condition)
+    {
+        throw new Error(message);
+    }
+};
+
+const assertArgs = (actual: string[], expected: string[], message: string): void =>
+{
+    assert(JSON.stringify(actual) === JSON.stringify(expected), `${message}. Expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}.`);
+};
+
+const assertThrows = (fn: () => void, expectedMessage: string, message: string): void =>
+{
+    try
+    {
+        fn();
+    }
+    catch (error)
+    {
+        assert(error instanceof Error, `${message}: expected an Error instance.`);
+        assert(error.message.includes(expectedMessage), `${message}: expected message to include '${expectedMessage}', got '${error.message}'.`);
+        return;
+    }
+
+    throw new Error(`${message}: expected function to throw.`);
+};
+
+const main = (): void =>
+{
+    const { buildPatchCommandArgs, resolvePatchToolPath } = __plasticPatchInternals;
+
+    assert(resolvePatchToolPath() === "diff", "Expected patch backend to share the portable diff PATH default.");
+    assert(resolvePatchToolPath(" C:\\gnu\\diff.exe ") === "C:\\gnu\\diff.exe", "Expected an explicit patch backend to override the default.");
+
+    assertArgs(
+        buildPatchCommandArgs({ source: "br:/main/task001" }),
+        ["patch", "br:/main/task001"],
+        "Expected one-spec patch command",
+    );
+
+    assertArgs(
+        buildPatchCommandArgs({ source: "br:/main/task001", clean: true }),
+        ["patch", "br:/main/task001", "--clean"],
+        "Expected clean flag to be included",
+    );
+
+    assertArgs(
+        buildPatchCommandArgs({ source: "br:/main/task001", integration: true }),
+        ["patch", "br:/main/task001", "--integration"],
+        "Expected integration flag to be included",
+    );
+
+    assertArgs(
+        buildPatchCommandArgs({ source: "br:/main/task001", clean: true, integration: true }),
+        ["patch", "br:/main/task001", "--clean", "--integration"],
+        "Expected clean and integration flags in stable order",
+    );
+
+    assertArgs(
+        buildPatchCommandArgs({ source: "cs:2", destination: "cs:4", output: "review.patch" }),
+        ["patch", "cs:2", "cs:4", "--output=review.patch"],
+        "Expected destination before output flag",
+    );
+
+    assertArgs(
+        buildPatchCommandArgs({ source: "br:/main/task001", toolPath: "C:\\gnu\\diff.exe" }),
+        ["patch", "br:/main/task001", "--tool=C:\\gnu\\diff.exe"],
+        "Expected custom diff tool path flag",
+    );
+
+    assertArgs(
+        buildPatchCommandArgs({ source: "br:/main/task001", clean: false, integration: false }),
+        ["patch", "br:/main/task001"],
+        "Expected false booleans to be omitted",
+    );
+
+    assertThrows(
+        () => buildPatchCommandArgs({ source: "" }),
+        "source must be non-empty",
+        "Expected blank source to be rejected",
+    );
+
+    assertThrows(
+        () => buildPatchCommandArgs({ source: "br:/main/task001", destination: "   " }),
+        "destination must be non-empty",
+        "Expected blank destination to be rejected",
+    );
+
+    assertThrows(
+        () => buildPatchCommandArgs({ source: "br:/main/task001", output: "   " }),
+        "output must be non-empty",
+        "Expected blank output to be rejected",
+    );
+
+    assertThrows(
+        () => buildPatchCommandArgs({ source: "br:/main/task001", toolPath: "   " }),
+        "toolPath must be non-empty",
+        "Expected blank toolPath to be rejected",
+    );
+
+    const allArgs = buildPatchCommandArgs({
+        source: "br:/main/task001",
+        destination: "br:/main",
+        output: "review.patch",
+        toolPath: "C:\\gnu\\diff.exe",
+        clean: true,
+        integration: true,
+    });
+    assert(!allArgs.some((arg) => arg === "--apply" || arg.startsWith("--apply=")), "Patch generation helper must not emit --apply.");
+
+    console.log("PASS: plastic patch command tests succeeded");
+};
+
+main();

package/tests/plastic-process-lifecycle.test.ts

@@ -0,0 +1,148 @@
+import { EventEmitter } from "node:events";
+import { PassThrough } from "node:stream";
+import { __plasticProcessInternals } from "../src/plastic-core.ts";
+
+const assert = (condition: boolean, message: string): void =>
+{
+    if (!condition)
+    {
+        throw new Error(message);
+    }
+};
+
+class FakeChildProcess extends EventEmitter
+{
+    readonly stdout = new PassThrough();
+    readonly stderr = new PassThrough();
+    readonly stdin = new PassThrough();
+    readonly signals: string[] = [];
+    killed = false;
+
+    kill(signal?: NodeJS.Signals): boolean
+    {
+        this.killed = true;
+        this.signals.push(signal ?? "SIGTERM");
+        return true;
+    }
+
+    close(code = 0): void
+    {
+        this.stdout.end();
+        this.stderr.end();
+        this.emit("close", code, null);
+    }
+}
+
+const fakeSpawn = (proc: FakeChildProcess): typeof import("node:child_process").spawn =>
+    (() => proc as unknown as ReturnType<typeof import("node:child_process").spawn>) as typeof import("node:child_process").spawn;
+
+const testExecutableResolutionAndDiagnostics = async (): Promise<void> =>
+{
+    assert(__plasticProcessInternals.resolveCmExecutable({}) === "cm", "Expected cm to be the default Plastic executable.");
+    assert(__plasticProcessInternals.resolveCmExecutable({ PI_PLASTIC_CM_EXECUTABLE: " /tools/cm " }) === "/tools/cm", "Expected PI_PLASTIC_CM_EXECUTABLE to override cm.");
+    assert(__plasticProcessInternals.resolveGitExecutable({ PI_PLASTIC_GIT_EXECUTABLE: "C:/Tools/git.exe" }) === "C:/Tools/git.exe", "Expected PI_PLASTIC_GIT_EXECUTABLE to override git.");
+
+    const proc = new FakeChildProcess();
+    const missingCm = __plasticProcessInternals.spawnAndCollect("cm", ["status"], process.cwd(), undefined, undefined, {
+        spawn: fakeSpawn(proc),
+    });
+    const error = Object.assign(new Error("spawn cm ENOENT"), { code: "ENOENT" });
+    proc.emit("error", error);
+
+    await missingCm.then(
+        () => { throw new Error("Expected a missing executable to reject."); },
+        (reason: unknown) =>
+        {
+            assert(reason instanceof Error && reason.message.includes("PI_PLASTIC_CM_EXECUTABLE"), "Expected missing cm guidance to name PI_PLASTIC_CM_EXECUTABLE.");
+        },
+    );
+
+    const gitProc = new FakeChildProcess();
+    const missingGit = __plasticProcessInternals.spawnAndCollect("git", ["--version"], process.cwd(), undefined, undefined, {
+        spawn: fakeSpawn(gitProc),
+    });
+    gitProc.emit("error", Object.assign(new Error("spawn git ENOENT"), { code: "ENOENT" }));
+    await missingGit.then(
+        () => { throw new Error("Expected a missing Git executable to reject."); },
+        (reason: unknown) =>
+        {
+            assert(reason instanceof Error && reason.message.includes("PI_PLASTIC_GIT_EXECUTABLE"), "Expected missing git guidance to name PI_PLASTIC_GIT_EXECUTABLE.");
+        },
+    );
+};
+
+const testAbortEscalatesUntilTerminalSettlement = async (): Promise<void> =>
+{
+    const proc = new FakeChildProcess();
+    const controller = new AbortController();
+    let scheduledKill: (() => void) | undefined;
+    let clearedTimerCount = 0;
+
+    const resultPromise = __plasticProcessInternals.spawnAndCollect("fake", [], process.cwd(), undefined, controller.signal, {
+        spawn: fakeSpawn(proc),
+        setTimeout: (callback) =>
+        {
+            scheduledKill = callback;
+            return {} as NodeJS.Timeout;
+        },
+        clearTimeout: () =>
+        {
+            clearedTimerCount += 1;
+        },
+    });
+
+    controller.abort();
+    assert(proc.killed, "Expected SIGTERM to mark the fake child as killed.");
+    assert(proc.signals.join(",") === "SIGTERM", "Expected abort to send SIGTERM first.");
+    assert(scheduledKill !== undefined, "Expected abort to schedule escalation.");
+
+    // ChildProcess.killed means only that SIGTERM was sent; a still-running child needs SIGKILL.
+    scheduledKill?.();
+    assert(proc.signals.join(",") === "SIGTERM,SIGKILL", "Expected a non-settled child to receive SIGKILL even after SIGTERM was sent.");
+
+    proc.close();
+    const result = await resultPromise;
+    assert(result.aborted, "Expected abort state to be reported after terminal close.");
+    assert(clearedTimerCount === 1, "Expected the escalation timer to be cleared during cleanup.");
+
+    controller.abort();
+    assert(proc.signals.join(",") === "SIGTERM,SIGKILL", "Expected abort listener cleanup after terminal settlement.");
+};
+
+const testTerminalListenersExistBeforeStdinWrite = async (): Promise<void> =>
+{
+    const proc = new FakeChildProcess();
+    proc.stdin.write = ((_chunk: unknown, _callback?: (error?: Error | null) => void): boolean =>
+    {
+        proc.stdout.end();
+        proc.stderr.end();
+        // Deliberately do not invoke the write callback: terminal error must still settle.
+        proc.emit("error", new Error("stdin-triggered process failure"));
+        return true;
+    }) as typeof proc.stdin.write;
+
+    let thrown: unknown;
+    try
+    {
+        await __plasticProcessInternals.spawnAndCollect("fake", [], process.cwd(), "input", undefined, {
+            spawn: fakeSpawn(proc),
+        });
+    }
+    catch (error)
+    {
+        thrown = error;
+    }
+
+    assert(thrown instanceof Error && thrown.message === "stdin-triggered process failure", "Expected process error raised during stdin write to reject cleanly.");
+    assert(proc.listenerCount("error") === 0 && proc.listenerCount("close") === 0, "Expected terminal listeners to be removed after rejection.");
+};
+
+const main = async (): Promise<void> =>
+{
+    await testExecutableResolutionAndDiagnostics();
+    await testAbortEscalatesUntilTerminalSettlement();
+    await testTerminalListenersExistBeforeStdinWrite();
+    console.log("PASS: plastic process lifecycle tests passed");
+};
+
+void main();

package/tests/plastic-tool-rendering.test.ts

@@ -0,0 +1,16 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+
+const indexText = readFileSync(new URL("../index.ts", import.meta.url), "utf8");
+
+assert.match(indexText, /const COLLAPSED_RESULT_LINES = 12;/, "plastic tool results should have a compact collapsed preview limit");
+assert.match(indexText, /function renderPlasticCall\(/, "plastic tools should provide custom call rendering");
+assert.match(indexText, /function renderPlasticResult\(/, "plastic tools should provide custom result rendering");
+assert.match(indexText, /renderCall\(args, theme\) \{/, "registered plastic tools should wire renderCall");
+assert.match(indexText, /renderResult\(result, options, theme\) \{/, "registered plastic tools should wire renderResult");
+assert.match(indexText, /options\?\.expanded \? lines\.length : COLLAPSED_RESULT_LINES/, "collapsed result rendering should limit visible output until expansion");
+assert.match(indexText, /ctrl\+o to expand/, "collapsed result rendering should advertise the Ctrl+O expansion shortcut");
+assert.match(indexText, /truncateAnsiLine/, "custom rendering should remain width-safe for long output lines");
+assert.match(indexText, /themed\(theme, "toolOutput", line\)/, "tool output lines should use the toolOutput theme color");
+
+console.log("PASS: plastic tool rendering test succeeded");

package/tests/plastic-tool-validation.ts

@@ -0,0 +1,153 @@
+import { readFileSync } from "fs";
+
+const pass = (msg: string): void => console.log(`PASS: ${msg}`);
+const fail = (msg: string): void => console.log(`FAIL: ${msg}`);
+
+const readText = (fileURL: URL): string => readFileSync(fileURL, "utf8");
+
+const checkRequired = (contents: string, target: string, snippets: string[]): number => {
+  let failures = 0;
+  for (const snippet of snippets) {
+    if (contents.includes(snippet)) {
+      pass(`${target} contains: ${snippet}`);
+    } else {
+      fail(`${target} missing required snippet: ${snippet}`);
+      failures += 1;
+    }
+  }
+  return failures;
+};
+
+const checkForbidden = (contents: string, target: string, patterns: RegExp[]): number => {
+  let failures = 0;
+  for (const pattern of patterns) {
+    if (pattern.test(contents)) {
+      fail(`${target} matched forbidden pattern: ${pattern}`);
+      failures += 1;
+    } else {
+      pass(`${target} does not match: ${pattern}`);
+    }
+  }
+  return failures;
+};
+
+const main = (): void => {
+  let failures = 0;
+
+  const plasticPath = new URL("../src/plastic-core.ts", import.meta.url);
+  const skillPath = new URL("../skills/using-plastic/SKILL.md", import.meta.url);
+  const reviewingPath = new URL("../skills/using-plastic/references/reviewing-changes.md", import.meta.url);
+  const changesetPath = new URL("../skills/using-plastic/references/changeset-operations.md", import.meta.url);
+  const troubleshootingPath = new URL("../skills/using-plastic/references/troubleshooting.md", import.meta.url);
+  const integrationPath = new URL("../skills/using-plastic/references/integration.md", import.meta.url);
+  const bashGuardPath = new URL("../extensions/bash-cm-diff-guard.ts", import.meta.url);
+  const bashMergeGuardPath = new URL("../extensions/bash-cm-merge-guard.ts", import.meta.url);
+
+  const plasticText = readText(plasticPath);
+  failures += checkRequired(plasticText, "pi-plastic/src/plastic-core.ts", [
+    "const BLOCKED_CM_DIFF_MESSAGE",
+    "ensureCmCommandAllowed(args);",
+    'command === "diff"',
+    "export const merge = tool({",
+    "export const mergeToBranch = tool({",
+  "resolveBranchParentName",
+    "export const finalizeMerge = tool({",
+    "export const resolveDeleteChangeConflict = tool({",
+    "export const patch = tool({",
+    "__plasticPatchInternals",
+    "buildPatchCommandArgs",
+    "export const diffRevisions = tool({",
+    "plastic_diff is disabled",
+    "parseMachineReadablePendingItems",
+    "summarizePendingItems",
+    "selectPrivatePathsForAutoAdd",
+    "filterPendingItemsByScope",
+    "isNoChangesWorkspaceCheckinError",
+    "SENSITIVE_PRIVATE_PATH_PATTERNS",
+    "auto-add-private-retry-success",
+    "__plasticSwitchInternals",
+    "normalizeBranchSpecForComparison",
+    "isSwitchBringBlockedForUnattended",
+    "canSwitchDirectWithPrivateOnlyPending",
+    "direct-switch-private-only",
+    "resolveCheckinPaths",
+    "buildFallbackScopePaths",
+    "--nointeractiveresolution",
+    "--mergetype=try",
+    "--automaticresolution=all-",
+    "FILE_CONFLICT",
+    "isMergeInProgressCheckinError",
+    "buildMergeInProgressCheckinMessage",
+    "updateAfter is disabled for unattended safety",
+    '["update", "--dontmerge", "--noinput"]',
+  ]);
+  failures += checkForbidden(plasticText, "pi-plastic/src/plastic-core.ts", [
+    /runCm\(\["diff"/,
+    /runCmRaw\(\["diff"/,
+    /runCm\(\["update"\]/,
+  ]);
+
+  const skillText = readText(skillPath);
+  failures += checkRequired(skillText, "pi-plastic/skills/using-plastic/SKILL.md", [
+    "Never run `cm diff` in Pi.",
+    "plastic_diffRevisions",
+    "plastic_patch",
+    "plastic_merge",
+    "plastic_mergeToBranch",
+  "source branch's Plastic parent branch",
+  ]);
+  failures += checkForbidden(skillText, "pi-plastic/skills/using-plastic/SKILL.md", [
+    /^\s*-\s+plastic_diff\s*$/m,
+  ]);
+
+  const refs = [
+    ["reviewing-changes.md", readText(reviewingPath)],
+    ["changeset-operations.md", readText(changesetPath)],
+    ["troubleshooting.md", readText(troubleshootingPath)],
+    ["integration.md", readText(integrationPath)],
+  ] as const;
+
+  for (const [name, text] of refs) {
+    failures += checkForbidden(text, `pi-plastic/skills/using-plastic/references/${name}`, [
+      /cm diff\s+br:/,
+      /cm diff\s+cs:/,
+      /cm diff\s+lb:/,
+      /cm diff\s+sh:/,
+      /cm diff\s+rev:/,
+      /plastic_diff\(source=/,
+      /list changed files/i,
+    ]);
+  }
+
+  const bashGuardText = readText(bashGuardPath);
+  failures += checkRequired(bashGuardText, "pi-plastic/extensions/bash-cm-diff-guard.ts", [
+    'pi.on("tool_call"',
+    "isBashToolCall",
+    "commandRunsCmDiff",
+    "__bashCmDiffGuardInternals",
+    "block: true",
+    "reason: BLOCK_MESSAGE",
+  ]);
+
+  const bashMergeGuardText = readText(bashMergeGuardPath);
+  failures += checkRequired(bashMergeGuardText, "pi-plastic/extensions/bash-cm-merge-guard.ts", [
+    'pi.on("tool_call"',
+    "isBashToolCall",
+    "commandRunsUnsafeCmMerge",
+    "__bashCmMergeGuardInternals",
+    "plastic_resolveDeleteChangeConflict",
+    "--nointeractiveresolution",
+    "--mergetype=try",
+    "block: true",
+    "reason: BLOCK_MESSAGE",
+  ]);
+
+  if (failures > 0) {
+    console.log(`FAIL: plastic validation failed with ${failures} issue(s)`);
+    process.exit(1);
+  }
+
+  console.log("PASS: plastic validation succeeded");
+};
+
+main();

package/tests/plastic-workspace.test.ts

@@ -0,0 +1,62 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, readFile, realpath, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  discoverPlasticWorkspace,
+  parsePlasticSelector,
+  parsePlasticStatusBranch,
+  sanitizePlasticBranch,
+} from "../src/plastic-workspace.ts";
+
+const fixture = async (name: string): Promise<string> => readFile(new URL(`./fixtures/${name}`, import.meta.url), "utf8");
+
+const root = await mkdtemp(join(tmpdir(), "pi-plastic-workspace-"));
+try {
+  const outer = join(root, "outer");
+  const inner = join(outer, "nested", "inner");
+  const cwd = join(inner, "src", "feature");
+  await mkdir(join(outer, ".plastic"), { recursive: true });
+  await writeFile(join(outer, ".plastic", "plastic.workspace"), "sanitized workspace marker\n");
+  await mkdir(join(inner, ".plastic"), { recursive: true });
+  await writeFile(join(inner, ".plastic", "plastic.workspace"), "nested sanitized marker\n");
+  await mkdir(cwd, { recursive: true });
+
+  const nested = await discoverPlasticWorkspace(cwd);
+  assert.equal(nested.kind, "found");
+  if (nested.kind === "found") assert.equal(nested.value.root, await realpath(inner));
+
+  await rm(join(inner, ".plastic", "plastic.workspace"));
+  const outerResult = await discoverPlasticWorkspace(cwd);
+  assert.equal(outerResult.kind, "found");
+  if (outerResult.kind === "found") assert.equal(outerResult.value.root, await realpath(outer));
+
+  const gitOnly = join(root, "git-only", ".git");
+  await mkdir(gitOnly, { recursive: true });
+  assert.equal((await discoverPlasticWorkspace(join(root, "git-only"))).kind, "not_found");
+
+  const selector = parsePlasticSelector(await fixture("plastic.selector"));
+  assert.deepEqual(selector, {
+    kind: "found",
+    value: { repository: "sanitized-repository@sanitized-server", branch: "/main/feature/footer" },
+  });
+  assert.equal(parsePlasticSelector("repository sample@server\n  path /\n").kind, "not_found");
+  assert.equal(parsePlasticSelector("smartbranch \n").kind, "malformed");
+  assert.equal(parsePlasticSelector("smartbranch /main/bad\u0007branch\n").kind, "malformed");
+
+  const normal = parsePlasticStatusBranch(await fixture("status-normal.txt"));
+  const compact = parsePlasticStatusBranch(await fixture("status-compact.txt"));
+  assert.deepEqual(normal, { kind: "found", value: { branch: "/main/feature/footer" } });
+  assert.deepEqual(compact, normal, "normal and compact status forms should yield the same branch path");
+  assert.deepEqual(parsePlasticStatusBranch("status cs:731\n"), { kind: "found", value: { changesetId: "731" } });
+  assert.equal(parsePlasticStatusBranch("unexpected output\n").kind, "malformed");
+  assert.equal(parsePlasticStatusBranch("\n").kind, "not_found");
+
+  assert.equal(sanitizePlasticBranch(" /main/feature\u0007  footer "), "/main/feature footer");
+  assert.equal(sanitizePlasticBranch("x".repeat(81)), `${"x".repeat(79)}…`);
+  assert.equal(sanitizePlasticBranch("界".repeat(41)), `${"界".repeat(39)}…`);
+} finally {
+  await rm(root, { recursive: true, force: true });
+}
+
+console.log("PASS: Plastic workspace discovery and parser tests passed");