canary-test-cli 6.8.0 → 7.0.0

package/dist/engine/core/migrator.js

@@ -248,6 +248,23 @@ function resolveTemplatePath(skillDir, rel) {
         return null;
     return full;
 }
+/**
+ * Is the deployed copy of a skill the consumer's rather than the overlay's?
+ *
+ * True when it differs from the overlay AND from the hash recorded at deploy
+ * time -- or carries no recorded provenance at all, since unknown provenance is
+ * not permission to overwrite.
+ *
+ * This is the single definition of `local_edit`. The skill-deploy phase refuses
+ * to overwrite on it (#334) and the workflow-install phase withholds on it
+ * (#667); sharing one predicate is what keeps the two phases from reporting
+ * contradictory things about the same skill in the same run.
+ */
+function isLocallyEdited(overlayHash, targetHash, recordedHash) {
+    if (targetHash === overlayHash)
+        return false;
+    return recordedHash === undefined || targetHash !== recordedHash;
+}
 // ---------------------------------------------------------------------------
 // Constants / probes
 // ---------------------------------------------------------------------------
@@ -455,8 +472,10 @@ export class SkillDeployResult {
  *   - `dry_run`   -- what an `--apply` run would have done
  *   - `missing`   -- the overlay declares a template it does not ship
  *   - `invalid`   -- the declared path escapes the skill directory (refused)
+ *   - `withheld`  -- the declaring skill was skipped as locally edited, so its
+ *                    templates were not installed either (#667)
  *
- * `outdated` and `conflict` are REPORTS. Neither ever writes.
+ * `outdated`, `conflict`, and `withheld` are REPORTS. None ever writes.
  */
 export class WorkflowInstallResult {
     /** File name under `.github/workflows/`. */
@@ -506,11 +525,21 @@ export class FreshnessReport {
      * nagging about something canary has no claim over.
      */
     workflows;
-    constructor(shape, overlay_path = null, results = [], workflows = []) {
+    /**
+     * Every shape the gate actually resolved -- the set `migrate` deploys for
+     * (#504 part 1). The scalar `shape` above stays, because the `--check --json`
+     * payload is documented and consumers read it; `shapes` is additive.
+     *
+     * A mixed monorepo collapses `shape` to `unknown` while `shapes` still names
+     * both, so the two disagree by design rather than by accident.
+     */
+    shapes;
+    constructor(shape, overlay_path = null, results = [], workflows = [], shapes = []) {
         this.shape = shape;
         this.overlay_path = overlay_path;
         this.results = results;
         this.workflows = workflows;
+        this.shapes = shapes;
     }
     get stale() {
         return this.results.filter((r) => r.status === 'stale' || r.status === 'missing');
@@ -564,6 +593,7 @@ export class FreshnessReport {
     to_dict() {
         return {
             shape: this.shape,
+            shapes: this.shapes,
             overlay_path: this.overlay_path,
             in_sync: this.in_sync,
             has_drift: this.has_drift,
@@ -587,14 +617,20 @@ export class FreshnessReport {
             `**Shape:** ${this.shape}`,
             '',
         ];
+        // A workspace repo resolves several shapes at once; naming only the scalar
+        // would tell a reader `unknown` while the gate checked two shapes (#504).
+        if (this.shapes.length > 1) {
+            lines.push(`**Shapes checked:** ${this.shapes.map((s) => `\`${s}\``).join(', ')}`, '');
+        }
         if (this.results.length === 0) {
             lines.push("_No overlay skills match this project's shape._", '');
             lines.push(`${WARN} **Abstained** ${EMDASH} the gate verified zero skills, so this is not a pass.`, '');
-            if (this.shape === 'unknown') {
+            if (this.shapes.length === 0) {
                 lines.push('The shape could not be detected. Set `canary_shape` in', '`.canary/company.json` or pass `--framework <name>`.', '');
             }
             else {
-                lines.push(`The overlay ships no skills with \`deploy_to\` covering \`${this.shape}\`.`, "Check the overlay's `deploy_to` lists or the resolved `canary_shape`.", '');
+                const covered = this.shapes.map((s) => `\`${s}\``).join(', ');
+                lines.push(`The overlay ships no skills with \`deploy_to\` covering ${covered}.`, "Check the overlay's `deploy_to` lists or the resolved `canary_shape`.", '');
             }
             lines.push(...workflowMarkdown(this.workflows, false));
             return lines.join('\n');
@@ -654,6 +690,14 @@ function workflowMarkdown(results, dryRun) {
             'differs from the template. Re-run with `--force` to take the ' +
             "overlay's version.", '');
     }
+    // #667: a withheld install is the one line that says why a template the
+    // overlay declares is absent from the target -- without it, the section
+    // simply omits the file and reads as though it were never declared.
+    if (results.some((r) => r.status === 'withheld')) {
+        lines.push(`${WARN} Templates declared by a skill with local edits were withheld: ` +
+            'the skill itself was skipped, so its workflows were not installed ' +
+            'either. Revert the local edits, or re-run with `--force`.', '');
+    }
     return lines;
 }
 export class MigrationReport {
@@ -994,6 +1038,10 @@ export class HarnessMigrator {
             ? shapeForFrameworkOverride(framework, projectRoot)
             : null;
         const shape = overrideShape ?? ctx.detected_shape;
+        // The set that actually drives deployment. Re-derived from the *effective*
+        // scalar rather than reusing `ctx.shapes`, so a `--framework` override
+        // contributes its resolved shape to the union too (#504 parts 1-2).
+        const deployShapes = unionShapes(shape, ctx.workspace);
         const followups = [];
         if (effectiveFramework === null) {
             followups.push(uncertainDetectionMessage('test framework', {
@@ -1004,7 +1052,7 @@ export class HarnessMigrator {
             // Issue #295 point 3: a detection miss must not block skill deployment --
             // nor, for the same reason, the workflow install (#459). The guardian
             // workflow is exactly what an unrecognised repo most needs.
-            const deployed = this.deploySkills(shape, overlayPath, projectRoot, dryRun);
+            const deployed = this.deploySkills(deployShapes, overlayPath, projectRoot, dryRun);
             return new MigrationReport({
                 framework: 'unknown',
                 shape,
@@ -1014,9 +1062,9 @@ export class HarnessMigrator {
                 manual_followups: followups,
                 config_warnings: ctx.config_warnings,
                 workspace: ctx.workspace,
-                shapes: ctx.shapes,
+                shapes: deployShapes,
                 deployed_skills: deployed,
-                installed_workflows: this.installWorkflows(shape, overlayPath, projectRoot, dryRun, force),
+                installed_workflows: this.installWorkflows(deployShapes, overlayPath, projectRoot, dryRun, force),
             });
         }
         // A framework canary knows but cannot scaffold gets no config boilerplate.
@@ -1035,10 +1083,10 @@ export class HarnessMigrator {
         // must not be offered a second one at the root.
         const existingSuites = findWorkspaceSuites(projectRoot, effectiveFramework);
         const scaffolder = new Scaffolder();
-        const deployed = this.deploySkills(shape, overlayPath, projectRoot, dryRun);
+        const deployed = this.deploySkills(deployShapes, overlayPath, projectRoot, dryRun);
         // Post-copy install phase: the template bytes already landed under
         // .canary/skills/ with the skill; this puts them where Actions looks.
-        const installedWorkflows = this.installWorkflows(shape, overlayPath, projectRoot, dryRun, force);
+        const installedWorkflows = this.installWorkflows(deployShapes, overlayPath, projectRoot, dryRun, force);
         if (dryRun) {
             const tmpl = TEMPLATES[effectiveFramework];
             const files = tmpl?.files ?? {};
@@ -1067,7 +1115,7 @@ export class HarnessMigrator {
                 installed_workflows: installedWorkflows,
                 config_warnings: ctx.config_warnings,
                 workspace: ctx.workspace,
-                shapes: ctx.shapes,
+                shapes: deployShapes,
             });
         }
         // Same guard on the apply path: what the dry run refuses to propose, an
@@ -1092,16 +1140,25 @@ export class HarnessMigrator {
             installed_workflows: installedWorkflows,
             config_warnings: ctx.config_warnings,
             workspace: ctx.workspace,
-            shapes: ctx.shapes,
+            shapes: deployShapes,
         });
     }
     // -- private helpers --------------------------------------------------------
     /**
      * Return `[[SkillInfo, skillDir], ...]` for overlay skills whose `deploy_to`
-     * matches *shape* (or the `all` sentinel). Sources: *overlayPath* first, then
-     * `~/.canary/skills/`. The first definition of a name wins.
+     * matches **any** shape in *shapes* (or the `all` sentinel). Sources:
+     * *overlayPath* first, then `~/.canary/skills/`. The first definition of a
+     * name wins.
+     *
+     * *shapes* is a set, not a scalar, because a monorepo genuinely has several
+     * shapes at once (#504 part 1). One pass over the overlay collects the union
+     * deduplicated by name, so a skill matching two shapes is collected once and
+     * the deploy manifest is read and written exactly once -- which a per-shape
+     * loop would not give.
+     *
+     * An empty *shapes* is the old `unknown`: only `deploy_to: [all]` matches.
      */
-    collectOverlaySkills(shape, overlayPath) {
+    collectOverlaySkills(shapes, overlayPath) {
         const candidateRoots = [];
         if (overlayPath !== null)
             candidateRoots.push(overlayPath);
@@ -1143,7 +1200,7 @@ export class HarnessMigrator {
                     continue;
                 if (!pyTruthy(info.deploy_to))
                     continue;
-                if (!info.deploy_to.includes(shape) &&
+                if (!shapes.some((s) => info.deploy_to.includes(s)) &&
                     !info.deploy_to.includes('all')) {
                     continue;
                 }
@@ -1154,12 +1211,12 @@ export class HarnessMigrator {
         return collected;
     }
     /**
-     * Copy skills from the overlay's `.canary/skills/` that match *shape*.
+     * Copy skills from the overlay's `.canary/skills/` matching any of *shapes*.
      * Deployment is strictly one-way -- the overlay owns deployed files (#334).
      */
-    deploySkills(shape, overlayPath, targetRoot, dryRun) {
+    deploySkills(shapes, overlayPath, targetRoot, dryRun) {
         const results = [];
-        const skillsToDeploy = this.collectOverlaySkills(shape, overlayPath);
+        const skillsToDeploy = this.collectOverlaySkills(shapes, overlayPath);
         const targetSkillsDir = join(targetRoot, '.canary', 'skills');
         const doc = readManifestDoc(targetSkillsDir);
         const manifest = doc.skills;
@@ -1178,8 +1235,7 @@ export class HarnessMigrator {
                     }
                     continue;
                 }
-                const recorded = manifest[dirName]?.hash;
-                if (recorded === undefined || targetHash !== recorded) {
+                if (isLocallyEdited(overlayHash, targetHash, manifest[dirName]?.hash)) {
                     // Hand-edited (or unprovenanced) -- one-way ownership refuses to clobber.
                     results.push(new SkillDeployResult(info.name, 'skipped', `local edits ${EMDASH} not overwritten`));
                     continue;
@@ -1210,6 +1266,21 @@ export class HarnessMigrator {
             writeManifestDoc(targetSkillsDir, doc);
         return results;
     }
+    /**
+     * Would the deploy phase skip this skill as `local_edit` (#667)?
+     *
+     * Answers for the CURRENT on-disk state, so it holds whether the deploy phase
+     * has already run this invocation (apply) or never will (dry run / `--check`)
+     * -- the workflow report then says the same thing about a skill as the skill
+     * report does.
+     */
+    skillWasSkipped(skillDir, targetSkillsDir, manifest) {
+        const dirName = basename(skillDir);
+        const dest = join(targetSkillsDir, dirName);
+        if (!existsSync(dest))
+            return false;
+        return isLocallyEdited(hashSkillDir(skillDir), hashSkillDir(dest), manifest[dirName]?.hash);
+    }
     /**
      * Install the workflow templates the shape-matching overlay skills declare
      * into the target's `.github/workflows/` (#459).
@@ -1225,22 +1296,43 @@ export class HarnessMigrator {
      * a hand-tuned workflow -- or nagging that it is "stale" via an exit code --
      * would be a worse failure than the partial adoption this fixes.
      *
-     * Shape selection reuses the same resolved `canary_shape` that drives
-     * `deploy_to` matching: skills are gated by {@link collectOverlaySkills}, and
-     * an entry may additionally carry a `<shape>:` prefix to pick a variant.
+     * **The skill's own protection extends here (#667).** A skill the deploy
+     * phase skips as `local_edit` installs nothing: it is reported `withheld`
+     * with the reason and no bytes are written. Otherwise a run could announce
+     * "skipped -- local edits, not overwritten" while writing that same skill's
+     * files to `.github/workflows/` anyway, which is how a consumer who
+     * deliberately de-listed a template got it reinstated on every sync. The
+     * de-listing lives in the consumer's SKILL.md, and the install list is read
+     * from the OVERLAY copy -- so withholding is also the only way that edit can
+     * mean anything.
+     *
+     * Shape selection reuses the same resolved shape set that drives `deploy_to`
+     * matching: skills are gated by {@link collectOverlaySkills}, and an entry may
+     * additionally carry a `<shape>:` prefix to pick a variant. A prefixed entry
+     * installs when its shape is anywhere in *shapes* (#504 part 1) -- a monorepo
+     * carrying both an e2e and a unit package wants both variants, and matching
+     * only the scalar would silently install neither once the scalar collapses to
+     * `unknown`.
      */
-    installWorkflows(shape, overlayPath, targetRoot, dryRun, force = false) {
+    installWorkflows(shapes, overlayPath, targetRoot, dryRun, force = false) {
         const results = [];
-        const skills = this.collectOverlaySkills(shape, overlayPath);
+        const skills = this.collectOverlaySkills(shapes, overlayPath);
         const targetSkillsDir = join(targetRoot, '.canary', 'skills');
         const doc = readManifestDoc(targetSkillsDir);
         const workflowsDir = join(targetRoot, '.github', 'workflows');
         let manifestDirty = false;
         for (const [info, skillDir] of skills) {
             const { entries, version } = readWorkflowDeclaration(info.path);
+            // Hashing a skill directory is not free, so only skills that actually
+            // declare templates pay for the local-edit lookup.
+            const skillWithheld = !force &&
+                entries.length > 0 &&
+                this.skillWasSkipped(skillDir, targetSkillsDir, doc.skills);
             for (const entry of entries) {
                 const [wantShape, rel] = parseWorkflowEntry(entry);
-                if (wantShape !== null && wantShape !== shape && wantShape !== 'all') {
+                if (wantShape !== null &&
+                    !shapes.includes(wantShape) &&
+                    wantShape !== 'all') {
                     continue;
                 }
                 const src = resolveTemplatePath(skillDir, rel);
@@ -1274,6 +1366,21 @@ export class HarnessMigrator {
                 const push = (status, detail) => {
                     results.push(new WorkflowInstallResult(name, info.name, status, detail));
                 };
+                const installedBytes = existsSync(dest) ? readBytesOrNull(dest) : null;
+                const alreadyCurrent = installedBytes !== null && installedBytes.equals(templateBytes);
+                // #667: the declaring skill was skipped as locally edited, so this
+                // template is not ours to place. An already-identical file is exempt:
+                // it is a no-op, and calling that "withheld" would raise a finding on
+                // every scheduled freshness check. Everything else is gated here,
+                // ahead of `outdated`, whose remedy ("re-run with --force") would
+                // otherwise talk a consumer into the very overwrite the skip refused.
+                if (skillWithheld && !alreadyCurrent) {
+                    push('withheld', `.github/workflows/${name} was NOT installed ${EMDASH} its skill ` +
+                        `'${info.name}' has local edits and was skipped, so its ` +
+                        'templates were withheld too; re-run with --force to install it ' +
+                        'anyway');
+                    continue;
+                }
                 if (!existsSync(dest)) {
                     if (dryRun) {
                         push('dry_run', `would install .github/workflows/${name} (v${version})`);
@@ -1283,8 +1390,7 @@ export class HarnessMigrator {
                     push('installed', `installed .github/workflows/${name} (v${version})`);
                     continue;
                 }
-                const installedBytes = readBytesOrNull(dest);
-                if (installedBytes !== null && installedBytes.equals(templateBytes)) {
+                if (alreadyCurrent) {
                     // Back-fill provenance for a hand-placed but identical file so a later
                     // template fix can be reported as `outdated` rather than `conflict`.
                     if (doc.workflows[name]?.hash !== templateHash)
@@ -1334,7 +1440,12 @@ export class HarnessMigrator {
                 'Expected harness.config.json and .harness/ directory.');
         }
         const shape = ctx.detected_shape;
-        const skills = this.collectOverlaySkills(shape, overlayPath);
+        // The gate must examine exactly what `migrate` deploys. Resolving only the
+        // scalar here would let `--check` report "in sync" about skills it never
+        // looked at in a monorepo -- a deliberate false green in a drift gate
+        // (#504 part 1).
+        const shapes = ctx.shapes;
+        const skills = this.collectOverlaySkills(shapes, overlayPath);
         const targetSkillsDir = join(projectRoot, '.canary', 'skills');
         const manifest = readManifestDoc(targetSkillsDir).skills;
         const results = [];
@@ -1362,7 +1473,7 @@ export class HarnessMigrator {
         return new FreshnessReport(shape, overlayPath !== null ? String(overlayPath) : null, results, 
         // dryRun = true: `--check` reports what an install WOULD do and never
         // writes. Informational only -- see FreshnessReport.workflows.
-        this.installWorkflows(shape, overlayPath, projectRoot, true, false));
+        this.installWorkflows(shapes, overlayPath, projectRoot, true, false), shapes);
     }
     detectFramework(root, config, ws = null) {
         // Explicit override in .canary/company.json ("canary_shape" field) is
@@ -1400,7 +1511,7 @@ export class HarnessMigrator {
         const findings = ws.findings;
         if (findings.length === 0)
             return null;
-        const pairs = new Set(findings.map((f) => `${f.framework}${f.shape}`));
+        const pairs = new Set(findings.map((f) => `${f.framework}\0${f.shape}`));
         if (pairs.size > 1) {
             return [null, 'unknown', 'workspace (mixed)', 'none'];
         }

package/dist/engine/core/static-linter.js

@@ -347,7 +347,7 @@ const JS_EXT_SET = new Set(JS_TEST_EXTENSIONS);
  * guess that cannot be distinguished from a clean result is a false green;
  * `null` forces the caller to abstain instead.
  */
-export function lintableFramework(path) {
+export function frameworkForPath(path) {
     const suffix = extname(path).toLowerCase();
     const name = basename(path).toLowerCase();
     if (suffix === '.py')
@@ -368,7 +368,7 @@ export class UnsupportedTestFileError extends Error {
     }
 }
 function requireFramework(path, framework) {
-    const fw = framework || lintableFramework(path);
+    const fw = framework || frameworkForPath(path);
     if (fw === null)
         throw new UnsupportedTestFileError(path);
     return fw;

package/dist/engine/guardian/adjudication.js

@@ -1,5 +1,5 @@
 /**
- * Finding adjudication collection — the precision the hard gate depends on
+ * Guardian finding adjudication collection — the precision the hard gate depends on
  * (#490).
  *
  * `pr-check.ts` documents the soft→hard promotion contract as

package/dist/engine/guardian/agent-tier.js

@@ -8,7 +8,7 @@
  * `tier.ts`), which imports it never (SC-11). Under the chosen **Option A**
  * invocation mechanism it **never calls an LLM directly**: it (i) turns
  * deterministic Tier-0 gaps into structured authoring intents, (ii) parses and
- * validates agent results into `Finding`/`GeneratedTest` records, and (iii)
+ * validates agent results into `GuardianFinding`/`GeneratedTest` records, and (iii)
  * enforces the write-safety model (opt-in, fork, collision, loop-guard) and the
  * block-once decision. It reaches an agent runtime only through an injected
  * `AgentInvoker` **port**; the production default (`RecordingInvoker`) records
@@ -26,7 +26,7 @@
  */
 import { existsSync } from 'node:fs';
 import { Severity } from './impact-mapper.js';
-import { Finding } from './pr-check.js';
+import { GuardianFinding } from './pr-check.js';
 /** Construct a {@link ReviewRequest} (a frozen dataclass in Python). */
 function reviewRequest(test_paths) {
     return { test_paths };
@@ -98,7 +98,7 @@ function parseReviewFindings(transcript) {
         if (severity === undefined)
             continue;
         const path = match.groups['path'];
-        findings.push(new Finding({
+        findings.push(new GuardianFinding({
             path,
             unit: path,
             kind: 'weak-test',