canary-test-cli 6.2.0 → 6.4.0

package/dist/engine/core/migrator.js

@@ -39,10 +39,11 @@
 import { createHash } from 'node:crypto';
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
-import { basename, join, relative, resolve, sep } from 'node:path';
+import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { readJsonWithWarning } from './config-validation.js';
 import { uncertainDetectionMessage } from './detection.js';
 import { FrameworkRegistry } from './framework-registry.js';
+import { EXIT_ABSTAINED, gateOutcome } from './gate-result.js';
 import { Scaffolder, scaffoldableFrameworks, TEMPLATES } from './scaffolder.js';
 import { SkillRegistry } from './skill-registry.js';
 // ---------------------------------------------------------------------------
@@ -147,34 +148,127 @@ function collectRelFiles(dir) {
     walk(dir, '');
     return out;
 }
+/** An object-valued manifest section, or `{}` when absent/malformed. */
+function manifestSection(data, key) {
+    if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+        return {};
+    }
+    const section = data[key];
+    if (section === null ||
+        typeof section !== 'object' ||
+        Array.isArray(section)) {
+        return {};
+    }
+    return section;
+}
 /**
- * Return `{dirName: {name, hash}}` from the manifest, or `{}` when absent or
- * unreadable (provenance is best-effort).
+ * Read the whole manifest document (skills + workflows). Both sections default
+ * to `{}` when the file is absent, unreadable, or malformed -- provenance is
+ * best-effort and never blocks a deploy.
  */
-function readDeployManifest(targetSkillsDir) {
+function readManifestDoc(targetSkillsDir) {
     const manifestPath = join(targetSkillsDir, DEPLOY_MANIFEST_NAME);
     let data;
     try {
         data = JSON.parse(readFileSync(manifestPath, 'utf-8'));
     }
     catch {
-        return {};
+        return { skills: {}, workflows: {} };
     }
-    if (data === null || typeof data !== 'object' || Array.isArray(data))
-        return {};
-    const skills = data['skills'];
-    if (skills === null || typeof skills !== 'object' || Array.isArray(skills)) {
-        return {};
-    }
-    return skills;
+    return {
+        skills: manifestSection(data, 'skills'),
+        workflows: manifestSection(data, 'workflows'),
+    };
 }
-function writeDeployManifest(targetSkillsDir, skills) {
+/**
+ * Write the manifest. Read-modify-write of the whole document, because the
+ * skill-deploy phase and the workflow-install phase each own one section and
+ * both write this one file. `workflows` is omitted entirely when empty so a
+ * skills-only manifest keeps its historical bytes.
+ */
+function writeManifestDoc(targetSkillsDir, doc) {
     const manifestPath = join(targetSkillsDir, DEPLOY_MANIFEST_NAME);
     mkdirSync(targetSkillsDir, { recursive: true });
-    const body = ensureAscii(JSON.stringify({ schemaVersion: 1, skills }, null, 2)) + '\n';
+    const payload = {
+        schemaVersion: 1,
+        skills: doc.skills,
+    };
+    if (Object.keys(doc.workflows).length > 0)
+        payload['workflows'] = doc.workflows;
+    const body = ensureAscii(JSON.stringify(payload, null, 2)) + '\n';
     writeFileSync(manifestPath, body, 'utf-8');
 }
 // ---------------------------------------------------------------------------
+// Workflow templates (#459)
+// ---------------------------------------------------------------------------
+/** Frontmatter key: templates this skill installs into `.github/workflows/`. */
+const WORKFLOW_DECL_KEY = 'install_workflows';
+/** Frontmatter key: the version stamped into the deploy manifest. */
+const WORKFLOW_VERSION_KEY = 'workflow_template_version';
+/** Default when a skill declares templates but no explicit version. */
+const WORKFLOW_DEFAULT_VERSION = '1';
+/**
+ * An optional `<shape>:` prefix on a declared entry, e.g.
+ * `api:templates/guardian-api.yml`. Two or more leading characters are required
+ * so a Windows drive letter (`C:\...`) can never be mistaken for a shape -- such
+ * a path is refused by {@link resolveTemplatePath} instead.
+ */
+const _WORKFLOW_ENTRY_RE = /^([A-Za-z][A-Za-z0-9_-]+):(.+)$/;
+function sha256(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+/** File bytes, or null when unreadable (e.g. the path is a directory). */
+function readBytesOrNull(path) {
+    try {
+        return readFileSync(path);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The workflow declaration in a skill's SKILL.md frontmatter.
+ *
+ * Parsed here rather than on {@link SkillInfo} because these fields are
+ * migrator-specific: the registry's job is discovery, and every other consumer
+ * of `SkillInfo` would carry two fields it never reads.
+ */
+function readWorkflowDeclaration(skillMd) {
+    const text = readTextOrNull(skillMd);
+    if (text === null)
+        return { entries: [], version: WORKFLOW_DEFAULT_VERSION };
+    const fm = SkillRegistry.parseFrontmatter(text);
+    const entries = SkillRegistry.parseStrList(fm, WORKFLOW_DECL_KEY);
+    const rawVersion = fm[WORKFLOW_VERSION_KEY];
+    const version = typeof rawVersion === 'string' && rawVersion.trim()
+        ? rawVersion.trim()
+        : WORKFLOW_DEFAULT_VERSION;
+    return { entries, version };
+}
+/** Split `[<shape>:]<relative-path>` into its shape filter and path. */
+function parseWorkflowEntry(entry) {
+    const m = _WORKFLOW_ENTRY_RE.exec(entry.trim());
+    if (m === null)
+        return [null, entry.trim()];
+    return [m[1].toLowerCase(), m[2].trim()];
+}
+/**
+ * Resolve a declared template path inside *skillDir*, or null when it escapes.
+ *
+ * An overlay is third-party content, so a declared path is untrusted input: an
+ * absolute path or a `..` climb would let an overlay copy an arbitrary file
+ * from the machine running `migrate` into the consumer's CI directory.
+ */
+function resolveTemplatePath(skillDir, rel) {
+    if (!rel || isAbsolute(rel) || /^[A-Za-z]:/.test(rel))
+        return null;
+    const base = resolve(skillDir);
+    const full = resolve(base, rel);
+    if (full !== base && !full.startsWith(base + sep))
+        return null;
+    return full;
+}
+// ---------------------------------------------------------------------------
 // Constants / probes
 // ---------------------------------------------------------------------------
 /**
@@ -416,6 +510,43 @@ export class SkillDeployResult {
         this.note = note;
     }
 }
+/**
+ * The outcome of installing one declared workflow template (#459).
+ *
+ * `status` is one of:
+ *   - `installed` -- the target had no such workflow; it was written
+ *   - `skipped`   -- byte-identical to the template; nothing to do
+ *   - `outdated`  -- differs, but is unmodified since canary installed it, so
+ *                    the overlay simply moved on (a template fix is waiting)
+ *   - `conflict`  -- differs and was edited locally / has unknown provenance
+ *   - `updated`   -- differed and `--force` replaced it
+ *   - `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)
+ *
+ * `outdated` and `conflict` are REPORTS. Neither ever writes.
+ */
+export class WorkflowInstallResult {
+    /** File name under `.github/workflows/`. */
+    workflow;
+    skill_name;
+    status;
+    detail;
+    constructor(workflow, skill_name, status, detail = '') {
+        this.workflow = workflow;
+        this.skill_name = skill_name;
+        this.status = status;
+        this.detail = detail;
+    }
+    to_dict() {
+        return {
+            workflow: this.workflow,
+            skill_name: this.skill_name,
+            status: this.status,
+            detail: this.detail,
+        };
+    }
+}
 export class SkillFreshnessResult {
     skill_name;
     dir_name;
@@ -433,10 +564,21 @@ export class FreshnessReport {
     shape;
     overlay_path;
     results;
-    constructor(shape, overlay_path = null, results = []) {
+    /**
+     * What a workflow install WOULD do (#459) -- informational only.
+     *
+     * Deliberately excluded from `has_drift` / `has_local_edits` / `exit_code`:
+     * the freshness gate speaks for overlay-owned skills, and a consumer's
+     * `.github/workflows/` is not overlay-owned. Failing CI because someone
+     * hand-tuned their own workflow, or has not adopted one at all, would be
+     * nagging about something canary has no claim over.
+     */
+    workflows;
+    constructor(shape, overlay_path = null, results = [], workflows = []) {
         this.shape = shape;
         this.overlay_path = overlay_path;
         this.results = results;
+        this.workflows = workflows;
     }
     get stale() {
         return this.results.filter((r) => r.status === 'stale' || r.status === 'missing');
@@ -453,8 +595,34 @@ export class FreshnessReport {
     get in_sync() {
         return !this.has_drift && !this.has_local_edits;
     }
-    /** 0 in sync, 1 drift, 2 local edits (safety refusal wins). */
+    /**
+     * The freshness gate as a {@link GateResult}: denominator = skills
+     * verified, findings = drift + local edits. Feeds the shared abstention
+     * helper (#508) so "verified zero skills" can never render as a pass.
+     */
+    gateResult() {
+        return {
+            checked: this.results.length,
+            findings: [...this.stale, ...this.local_edits],
+        };
+    }
+    /**
+     * A gate that verified zero skills has abstained, not passed (#503): the
+     * shape matched nothing, so nothing was checked and "in sync" would be a
+     * silent false pass -- the #456 class. Reported as its own exit code and
+     * flagged in every output surface. Delegates to the shared helper (#508).
+     */
+    get abstained() {
+        return gateOutcome(this.gateResult(), 'gate').abstained;
+    }
+    /**
+     * 0 in sync, 1 drift, 2 local edits (safety refusal wins), 3 abstained.
+     * The abstention path comes from the shared helper; the 1/2 mapping is
+     * this surface's own contract (local edits outrank drift).
+     */
     exit_code() {
+        if (this.abstained)
+            return EXIT_ABSTAINED;
         if (this.has_local_edits)
             return 2;
         if (this.has_drift)
@@ -468,6 +636,8 @@ export class FreshnessReport {
             in_sync: this.in_sync,
             has_drift: this.has_drift,
             has_local_edits: this.has_local_edits,
+            checked: this.results.length,
+            abstained: this.abstained,
             exit_code: this.exit_code(),
             skills: this.results.map((r) => ({
                 skill_name: r.skill_name,
@@ -475,6 +645,7 @@ export class FreshnessReport {
                 status: r.status,
                 detail: r.detail,
             })),
+            workflows: this.workflows.map((r) => r.to_dict()),
         };
     }
     to_markdown() {
@@ -486,6 +657,14 @@ export class FreshnessReport {
         ];
         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') {
+                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`.", '');
+            }
+            lines.push(...workflowMarkdown(this.workflows, false));
             return lines.join('\n');
         }
         if (this.in_sync) {
@@ -514,9 +693,37 @@ export class FreshnessReport {
                 'edits above (revert them, or upstream them into the overlay) ' +
                 'before the freshness gate can pass.', '');
         }
+        lines.push(...workflowMarkdown(this.workflows, false));
         return lines.join('\n');
     }
 }
+/**
+ * Render the workflow-install section shared by both reports.
+ *
+ * The closing note is not decoration: it is the only place a consumer is told
+ * that a reported difference will never be applied behind their back, and how
+ * to opt in when they do want the overlay's version.
+ */
+function workflowMarkdown(results, dryRun) {
+    if (results.length === 0)
+        return [];
+    const heading = dryRun
+        ? '## Workflows (would install into `.github/workflows/`)'
+        : '## Workflows (`.github/workflows/`)';
+    const lines = [heading, ''];
+    // Every result carries a detail; the status alone would not tell a consumer
+    // which file was touched or what to do next.
+    for (const r of results) {
+        lines.push(`- \`${r.workflow}\` ${EMDASH} ${r.detail}`);
+    }
+    lines.push('');
+    if (results.some((r) => r.status === 'conflict' || r.status === 'outdated')) {
+        lines.push(`${WARN} Your CI is yours: canary never overwrites a workflow that ` +
+            'differs from the template. Re-run with `--force` to take the ' +
+            "overlay's version.", '');
+    }
+    return lines;
+}
 export class MigrationReport {
     framework;
     shape;
@@ -530,6 +737,7 @@ export class MigrationReport {
     would_create;
     manual_followups;
     deployed_skills;
+    installed_workflows;
     config_warnings;
     constructor(init) {
         this.framework = init.framework;
@@ -544,8 +752,20 @@ export class MigrationReport {
         this.would_create = init.would_create ?? [];
         this.manual_followups = init.manual_followups ?? [];
         this.deployed_skills = init.deployed_skills ?? [];
+        this.installed_workflows = init.installed_workflows ?? [];
         this.config_warnings = init.config_warnings ?? [];
     }
+    /**
+     * The dry run's denominator (#504): config files that would be created,
+     * skills that would deploy, workflows that would install. Zero means the
+     * dry run has nothing to apply -- an advisory abstention, not a
+     * completed migration.
+     */
+    get would_migrate_count() {
+        return (this.would_create.length +
+            this.deployed_skills.filter((r) => r.status === 'dry_run').length +
+            this.installed_workflows.filter((r) => r.status === 'dry_run').length);
+    }
     to_markdown() {
         const lines = ['# Canary Migration Report', ''];
         if (this.dry_run) {
@@ -642,12 +862,35 @@ export class MigrationReport {
             }
             lines.push('');
         }
+        lines.push(...workflowMarkdown(this.installed_workflows, this.dry_run));
         if (this.manual_followups.length > 0) {
             lines.push('## Manual Follow-ups Required', '');
             for (const item of this.manual_followups)
                 lines.push(`- ${item}`);
             lines.push('');
         }
+        else if (this.dry_run) {
+            // #504 abstention half: a dry run never completed anything. Zero
+            // pending work is an advisory abstention (D3) -- gateOutcome is the
+            // only summary-line path AND the only decision point (no local
+            // n === 0 arithmetic), so the refusal is structural.
+            const n = this.would_migrate_count;
+            const outcome = gateOutcome({ checked: n, findings: [] }, 'advisory', {
+                noun: 'item(s)',
+            });
+            lines.push('## Status', '');
+            if (outcome.abstained) {
+                lines.push(outcome.summaryLine, '', 'This dry run would migrate zero item(s) ' +
+                    EMDASH +
+                    ' the project already carries everything this migration would ' +
+                    'produce. If you expected changes, check `--from <overlay>` and ' +
+                    'the detected framework/shape above.', '');
+            }
+            else {
+                lines.push(`Dry run ${EMDASH} would migrate ${n} item(s). ` +
+                    'Re-run with `--apply` to write them.', '');
+            }
+        }
         else {
             lines.push('## Status', '', 'Migration complete. Run `canary recommend "<test description>"` to verify framework detection.', '');
         }
@@ -719,6 +962,7 @@ export class HarnessMigrator {
         const dryRun = options.dryRun ?? true;
         const framework = options.framework ?? null;
         const overlayPath = options.overlayPath ?? null;
+        const force = options.force ?? false;
         const ctx = this.detect(projectRoot);
         if (!ctx.is_harness_project) {
             if (ctx.not_test_project_reason)
@@ -741,7 +985,9 @@ export class HarnessMigrator {
                 candidates: KNOWN_FRAMEWORKS,
                 overrideHint: '`canary migrate --framework <name>`',
             }));
-            // Issue #295 point 3: a detection miss must not block skill deployment.
+            // 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);
             return new MigrationReport({
                 framework: 'unknown',
@@ -752,6 +998,7 @@ export class HarnessMigrator {
                 manual_followups: followups,
                 config_warnings: ctx.config_warnings,
                 deployed_skills: deployed,
+                installed_workflows: this.installWorkflows(shape, overlayPath, projectRoot, dryRun, force),
             });
         }
         // A framework canary knows but cannot scaffold gets no config boilerplate.
@@ -768,6 +1015,9 @@ export class HarnessMigrator {
         const preserved = this.findExistingTests(projectRoot);
         const scaffolder = new Scaffolder();
         const deployed = this.deploySkills(shape, 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);
         if (dryRun) {
             const tmpl = TEMPLATES[effectiveFramework];
             const files = tmpl?.files ?? {};
@@ -788,6 +1038,7 @@ export class HarnessMigrator {
                 preserved_files: preserved,
                 manual_followups: followups,
                 deployed_skills: deployed,
+                installed_workflows: installedWorkflows,
                 config_warnings: ctx.config_warnings,
             });
         }
@@ -804,6 +1055,7 @@ export class HarnessMigrator {
             preserved_files: preserved,
             manual_followups: followups,
             deployed_skills: deployed,
+            installed_workflows: installedWorkflows,
             config_warnings: ctx.config_warnings,
         });
     }
@@ -873,7 +1125,8 @@ export class HarnessMigrator {
         const results = [];
         const skillsToDeploy = this.collectOverlaySkills(shape, overlayPath);
         const targetSkillsDir = join(targetRoot, '.canary', 'skills');
-        const manifest = readDeployManifest(targetSkillsDir);
+        const doc = readManifestDoc(targetSkillsDir);
+        const manifest = doc.skills;
         let manifestDirty = false;
         for (const [info, skillDir] of skillsToDeploy) {
             const dirName = basename(skillDir);
@@ -918,7 +1171,117 @@ export class HarnessMigrator {
             results.push(new SkillDeployResult(info.name, 'copied'));
         }
         if (manifestDirty && !dryRun)
-            writeDeployManifest(targetSkillsDir, manifest);
+            writeManifestDoc(targetSkillsDir, doc);
+        return results;
+    }
+    /**
+     * Install the workflow templates the shape-matching overlay skills declare
+     * into the target's `.github/workflows/` (#459).
+     *
+     * This runs AFTER the skill copy and is a distinct phase, not an extension of
+     * it: the bytes already arrive (whole skill dirs are copied, templates
+     * included) -- what was missing is putting them where GitHub Actions looks.
+     *
+     * **Ownership deliberately differs from `deploySkills`.** Deployed skills are
+     * owned one-way by the overlay (#334); a consumer's CI is NOT. Absent ->
+     * write. Byte-identical -> no-op. Different -> report and leave alone, always,
+     * whatever the provenance. `force` is the deliberate escape hatch. Clobbering
+     * 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.
+     */
+    installWorkflows(shape, overlayPath, targetRoot, dryRun, force = false) {
+        const results = [];
+        const skills = this.collectOverlaySkills(shape, 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);
+            for (const entry of entries) {
+                const [wantShape, rel] = parseWorkflowEntry(entry);
+                if (wantShape !== null && wantShape !== shape && wantShape !== 'all') {
+                    continue;
+                }
+                const src = resolveTemplatePath(skillDir, rel);
+                if (src === null) {
+                    results.push(new WorkflowInstallResult(basename(rel), info.name, 'invalid', `declared template '${rel}' resolves outside the skill directory ` +
+                        `${EMDASH} refused`));
+                    continue;
+                }
+                if (!isFile(src)) {
+                    results.push(new WorkflowInstallResult(basename(rel), info.name, 'missing', `the overlay declares '${rel}' but does not ship it`));
+                    continue;
+                }
+                const name = basename(src);
+                const dest = join(workflowsDir, name);
+                const templateBytes = readFileSync(src);
+                const templateHash = sha256(templateBytes);
+                const record = () => {
+                    doc.workflows[name] = {
+                        skill: info.name,
+                        template: rel,
+                        version,
+                        hash: templateHash,
+                    };
+                    manifestDirty = true;
+                };
+                const install = () => {
+                    mkdirSync(workflowsDir, { recursive: true });
+                    writeFileSync(dest, templateBytes);
+                    record();
+                };
+                const push = (status, detail) => {
+                    results.push(new WorkflowInstallResult(name, info.name, status, detail));
+                };
+                if (!existsSync(dest)) {
+                    if (dryRun) {
+                        push('dry_run', `would install .github/workflows/${name} (v${version})`);
+                        continue;
+                    }
+                    install();
+                    push('installed', `installed .github/workflows/${name} (v${version})`);
+                    continue;
+                }
+                const installedBytes = readBytesOrNull(dest);
+                if (installedBytes !== null && installedBytes.equals(templateBytes)) {
+                    // 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)
+                        record();
+                    push('skipped', `.github/workflows/${name} already current`);
+                    continue;
+                }
+                if (force) {
+                    if (dryRun) {
+                        push('dry_run', `would overwrite .github/workflows/${name} with v${version} (--force)`);
+                        continue;
+                    }
+                    install();
+                    push('updated', `overwrote .github/workflows/${name} with v${version} (--force)`);
+                    continue;
+                }
+                const recorded = doc.workflows[name];
+                const untouched = installedBytes !== null &&
+                    recorded !== undefined &&
+                    recorded.hash === sha256(installedBytes);
+                if (untouched) {
+                    push('outdated', `.github/workflows/${name} is at v${recorded.version}, the overlay ` +
+                        `ships v${version} ${EMDASH} unmodified since install, so re-run ` +
+                        'with --force to take the update');
+                    continue;
+                }
+                push('conflict', `.github/workflows/${name} differs from the overlay template and was ` +
+                    `left untouched ${EMDASH} your CI is yours; re-run with --force to ` +
+                    'replace it');
+            }
+        }
+        if (manifestDirty && !dryRun)
+            writeManifestDoc(targetSkillsDir, doc);
         return results;
     }
     /**
@@ -937,7 +1300,7 @@ export class HarnessMigrator {
         const shape = ctx.detected_shape;
         const skills = this.collectOverlaySkills(shape, overlayPath);
         const targetSkillsDir = join(projectRoot, '.canary', 'skills');
-        const manifest = readDeployManifest(targetSkillsDir);
+        const manifest = readManifestDoc(targetSkillsDir).skills;
         const results = [];
         for (const [info, skillDir] of skills) {
             const dirName = basename(skillDir);
@@ -960,22 +1323,29 @@ export class HarnessMigrator {
                 results.push(new SkillFreshnessResult(info.name, dirName, 'local_edit', 'deployed skill has local edits; refusing to overwrite'));
             }
         }
-        return new FreshnessReport(shape, overlayPath !== null ? String(overlayPath) : null, results);
+        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));
     }
     detectFramework(root, config) {
-        // 0. Explicit override in .canary/company.json ("canary_shape" field).
+        // Explicit override in .canary/company.json ("canary_shape" field) is
+        // user intent: it wins over every probe tier's shape, including a total
+        // probe miss (#502 — monorepos often have no root framework config).
+        // Framework detection still runs so framework-dependent behavior keeps
+        // working when a probe does match.
         const rawShape = config['canary_shape'];
         const explicitShape = (rawShape == null ? '' : String(rawShape))
             .trim()
             .toLowerCase();
-        if (explicitShape) {
-            for (const [filename, framework, , confidence] of _CONFIG_PROBES) {
-                if (existsSync(join(root, filename))) {
-                    return [framework, explicitShape, filename, confidence];
-                }
-            }
-            // Fall through to content probes.
-        }
+        const [framework, shape, source, confidence] = this.probeFramework(root, config);
+        if (!explicitShape)
+            return [framework, shape, source, confidence];
+        return framework === null
+            ? [null, explicitShape, 'canary_shape (.canary/company.json)', 'explicit']
+            : [framework, explicitShape, source, confidence];
+    }
+    probeFramework(root, config) {
         // 1. Dedicated config file (highest confidence).
         for (const [filename, framework, shape, confidence] of _CONFIG_PROBES) {
             if (existsSync(join(root, filename))) {