canary-test-cli 6.2.0 → 6.3.0

package/dist/engine/cli-commands.js

@@ -344,6 +344,7 @@ export function migrateCmd(opts, deps) {
             dryRun,
             framework: opts.framework || null,
             overlayPath,
+            force: opts.force ?? false,
         });
     }
     catch (e) {
@@ -367,6 +368,7 @@ export function migrateCmd(opts, deps) {
                 status: r.status,
                 note: r.note,
             })),
+            installed_workflows: report.installed_workflows.map((r) => r.to_dict()),
         }));
         return;
     }

package/dist/engine/cli.core.js

@@ -107,6 +107,7 @@ export function createCanaryCommand(depsInit = {}) {
         .option('-o, --overlay <path>', '[deprecated: use --from] Path to an overlay repo whose .canary/skills/ are deployed.')
         .option('--apply', 'Write files. Without this flag the command is a dry run.')
         .option('--check', 'Freshness gate: report drift without writing.')
+        .option('--force', 'Overwrite a .github/workflows/ file that differs from the overlay template. Without this flag a difference is only reported -- your CI is never rewritten behind your back.')
         .option('--json', 'Emit the report as JSON.')
         .action((opts) => {
         migrateCmd(opts, deps);

package/dist/engine/core/company-knowledge.js

@@ -13,9 +13,11 @@
  *   2. .canary/company.json            -- project-local config
  *   3. .canary/company.<env>.json      -- environment override (CANARY_ENV or explicit)
  *
- * List fields are unioned across sources; scalar fields (dashboard_url,
- * dashboard_token_env, notes) are replaced by the highest-priority source that
- * sets them.
+ * List fields ({@link _LIST_FIELDS}) are unioned across sources; scalar fields
+ * ({@link _SCALAR_FIELDS}) are replaced by the highest-priority source that
+ * sets a non-empty value. Those two arrays are the single place a new field
+ * opts into a merge rule, and both are checked for exhaustiveness at compile
+ * time.
  *
  * Python->TS nuances:
  *   - Python patches `Path.home()` in its tests to isolate the home tier. There
@@ -118,6 +120,12 @@ const _KNOWN_KEYS = new Set([
     // warning that it is told anyone adopting an overlay that the single field
     // driving their adoption does nothing.
     'canary_shape',
+    // #459: repo-relative pointers a generated workflow interpolates (the
+    // coverage report the guardian reads; the controllers dir it scopes SUT
+    // analysis to). See `validateRepoRelativePath` for why they are validated
+    // rather than stored verbatim.
+    'coverage_report_path',
+    'sut_controllers_path',
 ]);
 const _HEX_COLOR_RE = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
 const _BRAND_TEXT_MAX = 200;
@@ -240,6 +248,50 @@ function validateOtelEndpoint(raw, fieldName, warnings) {
     }
     return raw;
 }
+// A path that is absolute in any flavour git checkouts run under: POSIX
+// (`/x`), UNC / Windows-separator (`\x`), or drive-qualified (`C:x`, `C:/x`).
+// Drive-relative `C:x` is included deliberately -- it is not repo-relative.
+const _ABSOLUTE_PATH_RE = /^(?:[/\\]|[A-Za-z]:)/;
+// Newlines would break out of the scalar these values are interpolated into
+// when a workflow template is generated, so they are refused outright rather
+// than escaped -- no legitimate repo path contains one.
+const _PATH_CONTROL_RE = /[\r\n\t\0]/;
+/**
+ * A repo-relative path pointer (#459: `coverage_report_path`,
+ * `sut_controllers_path`).
+ *
+ * These are interpolated into generated GitHub Actions YAML, so validation is
+ * a safety boundary, not tidiness: an absolute path aims the generated CI at
+ * something outside the checkout, and a `..` segment escapes the repo. Both are
+ * dropped with a warning (the module's degrade-never-throw convention); a
+ * secret-like value raises so the whole layer is refused, exactly as every
+ * other non-notes field does.
+ *
+ * `..` is rejected as a SUBSTRING, not just as a path component. A component
+ * check would have to agree with the separator handling of whatever consumes
+ * the value later (shell, Actions expression, node `path`); refusing the two
+ * characters outright cannot disagree with anything. The cost is rejecting the
+ * vanishingly rare legitimate `report..xml`.
+ */
+function validateRepoRelativePath(raw, fieldName, warnings) {
+    if (typeof raw !== 'string') {
+        warnings.push(`${fieldName}: expected string, got ${pyTypeName(raw)} ${EMDASH} skipped`);
+        return '';
+    }
+    const value = raw.trim();
+    if (!value)
+        return '';
+    if (looksLikeSecret(value))
+        throw new SecretDetected(fieldName, value);
+    if (_ABSOLUTE_PATH_RE.test(value) ||
+        value.includes('..') ||
+        _PATH_CONTROL_RE.test(value)) {
+        warnings.push(`${fieldName}: dropped invalid repo-relative path ${pyRepr(raw)} ` +
+            `${EMDASH} must stay inside the repo (no absolute path, no '..')`);
+        return '';
+    }
+    return value;
+}
 /** Accept #RGB / #RRGGBB (any case); drop anything else with a warning. */
 function validateHexColor(raw, fieldName, warnings) {
     if (typeof raw !== 'string' || !raw)
@@ -432,6 +484,14 @@ function parseLayer(data, source) {
     if (Object.prototype.hasOwnProperty.call(data, 'otel_exporter_endpoint')) {
         otel_exporter_endpoint = validateOtelEndpoint(data['otel_exporter_endpoint'], 'otel_exporter_endpoint', warns);
     }
+    let coverage_report_path = '';
+    if (Object.prototype.hasOwnProperty.call(data, 'coverage_report_path')) {
+        coverage_report_path = validateRepoRelativePath(data['coverage_report_path'], 'coverage_report_path', warns);
+    }
+    let sut_controllers_path = '';
+    if (Object.prototype.hasOwnProperty.call(data, 'sut_controllers_path')) {
+        sut_controllers_path = validateRepoRelativePath(data['sut_controllers_path'], 'sut_controllers_path', warns);
+    }
     let notes = '';
     if (Object.prototype.hasOwnProperty.call(data, 'notes')) {
         const rawNotes = data['notes'];
@@ -455,6 +515,8 @@ function parseLayer(data, source) {
         dashboard_url,
         dashboard_token_env,
         otel_exporter_endpoint,
+        coverage_report_path,
+        sut_controllers_path,
         notes,
         brand,
         warnings: warns,
@@ -509,51 +571,66 @@ function union(a, b) {
     }
     return out;
 }
+const _LIST_FIELDS = [
+    'confluence_spaces',
+    'jira_projects',
+    'internal_doc_urls',
+    'internal_domains',
+    'mcp_servers',
+    'claude_code_skills',
+];
+const _SCALAR_FIELDS = [
+    'dashboard_url',
+    'dashboard_token_env',
+    'otel_exporter_endpoint',
+    'coverage_report_path',
+    'sut_controllers_path',
+    'notes',
+];
+// Compile-time exhaustiveness: adding a field to `Layer`/`MergedFields` without
+// adding it to the matching array above fails the build here (the assertion
+// type collapses to `never`) rather than silently dropping the field at merge.
+const _LIST_FIELDS_EXHAUSTIVE = true;
+const _SCALAR_FIELDS_EXHAUSTIVE = true;
+void _LIST_FIELDS_EXHAUSTIVE;
+void _SCALAR_FIELDS_EXHAUSTIVE;
+function mergeListFields(layers) {
+    const out = {};
+    for (const field of _LIST_FIELDS) {
+        let merged = [];
+        for (const layer of layers)
+            merged = union(merged, layer[field]);
+        out[field] = merged;
+    }
+    return out;
+}
+function mergeScalarFields(layers) {
+    const out = {};
+    for (const field of _SCALAR_FIELDS) {
+        let merged = '';
+        // Highest-priority non-empty wins. A layer whose value was DROPPED as
+        // invalid contributes '' and therefore leaves the lower layer's valid value
+        // standing (degrade, never blank out) -- load-bearing, and pinned by tests.
+        for (const layer of layers)
+            if (layer[field])
+                merged = layer[field];
+        out[field] = merged;
+    }
+    return out;
+}
 function mergeLayers(layers) {
-    let confluence_spaces = [];
-    let jira_projects = [];
-    let internal_doc_urls = [];
-    let internal_domains = [];
-    let mcp_servers = [];
-    let claude_code_skills = [];
-    let dashboard_url = '';
-    let dashboard_token_env = '';
-    let otel_exporter_endpoint = '';
-    let notes = '';
-    const warns = [];
+    const warnings = [];
     const sources = [];
     for (const layer of layers) {
-        confluence_spaces = union(confluence_spaces, layer.confluence_spaces);
-        jira_projects = union(jira_projects, layer.jira_projects);
-        internal_doc_urls = union(internal_doc_urls, layer.internal_doc_urls);
-        internal_domains = union(internal_domains, layer.internal_domains);
-        mcp_servers = union(mcp_servers, layer.mcp_servers);
-        claude_code_skills = union(claude_code_skills, layer.claude_code_skills);
-        if (layer.dashboard_url)
-            dashboard_url = layer.dashboard_url;
-        if (layer.dashboard_token_env)
-            dashboard_token_env = layer.dashboard_token_env;
-        if (layer.otel_exporter_endpoint)
-            otel_exporter_endpoint = layer.otel_exporter_endpoint;
-        if (layer.notes)
-            notes = layer.notes;
-        warns.push(...layer.warnings);
+        warnings.push(...layer.warnings);
         if (layer.source)
             sources.push(layer.source);
     }
     return {
-        confluence_spaces,
-        jira_projects,
-        internal_doc_urls,
-        internal_domains,
-        mcp_servers,
-        claude_code_skills,
-        dashboard_url,
-        dashboard_token_env,
-        otel_exporter_endpoint,
-        notes,
+        ...mergeListFields(layers),
+        ...mergeScalarFields(layers),
         brand: mergeBrand(layers),
-        warnings: warns,
+        warnings,
         sources,
     };
 }
@@ -585,6 +662,10 @@ export class CompanyKnowledge {
     dashboard_url;
     dashboard_token_env;
     otel_exporter_endpoint;
+    /** Repo-relative path to the coverage report a generated workflow reads. */
+    coverage_report_path;
+    /** Repo-relative path to the SUT controllers dir analysis is scoped to. */
+    sut_controllers_path;
     notes;
     brand;
     warnings;
@@ -600,6 +681,8 @@ export class CompanyKnowledge {
         this.dashboard_url = init.dashboard_url ?? '';
         this.dashboard_token_env = init.dashboard_token_env ?? '';
         this.otel_exporter_endpoint = init.otel_exporter_endpoint ?? '';
+        this.coverage_report_path = init.coverage_report_path ?? '';
+        this.sut_controllers_path = init.sut_controllers_path ?? '';
         this.notes = init.notes ?? '';
         this.brand = init.brand ?? new Brand();
         this.warnings = init.warnings ?? [];
@@ -733,6 +816,8 @@ export class CompanyKnowledge {
             dashboard_url: this.dashboard_url,
             dashboard_token_env: this.dashboard_token_env,
             otel_exporter_endpoint: this.otel_exporter_endpoint,
+            coverage_report_path: this.coverage_report_path,
+            sut_controllers_path: this.sut_controllers_path,
             notes: this.notes,
             brand: this.brand.toDict(),
             sources: this.sources,

package/dist/engine/core/migrator.js

@@ -39,7 +39,7 @@
 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';
@@ -147,34 +147,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 +509,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 +563,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');
@@ -475,6 +616,7 @@ export class FreshnessReport {
                 status: r.status,
                 detail: r.detail,
             })),
+            workflows: this.workflows.map((r) => r.to_dict()),
         };
     }
     to_markdown() {
@@ -486,6 +628,7 @@ export class FreshnessReport {
         ];
         if (this.results.length === 0) {
             lines.push("_No overlay skills match this project's shape._", '');
+            lines.push(...workflowMarkdown(this.workflows, false));
             return lines.join('\n');
         }
         if (this.in_sync) {
@@ -514,9 +657,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 +701,7 @@ export class MigrationReport {
     would_create;
     manual_followups;
     deployed_skills;
+    installed_workflows;
     config_warnings;
     constructor(init) {
         this.framework = init.framework;
@@ -544,6 +716,7 @@ 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 ?? [];
     }
     to_markdown() {
@@ -642,6 +815,7 @@ 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)
@@ -719,6 +893,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 +916,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 +929,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 +946,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 +969,7 @@ export class HarnessMigrator {
                 preserved_files: preserved,
                 manual_followups: followups,
                 deployed_skills: deployed,
+                installed_workflows: installedWorkflows,
                 config_warnings: ctx.config_warnings,
             });
         }
@@ -804,6 +986,7 @@ export class HarnessMigrator {
             preserved_files: preserved,
             manual_followups: followups,
             deployed_skills: deployed,
+            installed_workflows: installedWorkflows,
             config_warnings: ctx.config_warnings,
         });
     }
@@ -873,7 +1056,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 +1102,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 +1231,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,7 +1254,10 @@ 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).

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

@@ -181,7 +181,11 @@ export class AuthoringContext {
     effective_tier; // from resolveTier (2 == can author)
     is_fork; // reuse Phase-2 fork/403 detection -- (b)
     repo_root; // collision + sentinel base
-    authored_sentinel_present; // loop-guard -- (a)
+    // loop-guard -- (a). True only when a sentinel stamped at the CURRENT HEAD
+    // exists (#456): the caller resolves the stamp, and every unverifiable state
+    // (missing/unreadable/malformed sentinel, unresolvable HEAD) passes `false`
+    // so authoring fails OPEN.
+    authored_sentinel_present;
     constructor(author_tests_optin, effective_tier, init = {}) {
         this.author_tests_optin = author_tests_optin;
         this.effective_tier = effective_tier;
@@ -256,7 +260,8 @@ function authoringSkipReason(gap, ctx) {
         return `fork: read-only ${EM_DASH} guardian never writes on a fork PR`;
     }
     if (ctx.authored_sentinel_present) {
-        return `loop-guard: guardian tests already authored this run ${EM_DASH} not re-authoring`;
+        return (`loop-guard: guardian tests already authored at this HEAD ${EM_DASH} ` +
+            `review and commit them to re-enable authoring`);
     }
     const target = joinPosix(ctx.repo_root, targetTestPath(gap));
     if (existsSync(target)) {

package/dist/engine/guardian/cli.js

@@ -258,6 +258,61 @@ const AUTHORED_SENTINEL_NAME = 'canary-guardian-authored';
 function authoredSentinelPath(deps, root) {
     return join(gitDir(deps, root), AUTHORED_SENTINEL_NAME);
 }
+// The sentinel's FIRST line stamps the HEAD the guardian authored at:
+// `HEAD <sha>`. Every line after it is one authored path. Anchored at the start
+// of the body and hex-only, with a trailing `[ \t\r]*` so a CRLF-written file
+// still parses -- anything else reads as malformed, which fails OPEN.
+const SENTINEL_HEAD_RE = /^HEAD ([0-9a-fA-F]{7,64})[ \t\r]*(?:\n|$)/;
+/**
+ * Parse the `HEAD <sha>` stamp off a sentinel body; `null` when malformed.
+ *
+ * Malformed covers empty, headerless (the pre-#456 paths-only format), and any
+ * unparseable first line. Callers MUST treat `null` as "cannot verify" and fail
+ * OPEN -- an unreadable sentinel must never wedge authoring off (#456).
+ */
+function sentinelHeadStamp(text) {
+    const match = SENTINEL_HEAD_RE.exec(text);
+    return match === null ? null : match[1].toLowerCase();
+}
+/** Current `HEAD` sha for `root`, or `null` when git/HEAD is unavailable. */
+function headSha(deps, root) {
+    const res = deps.runGit(['rev-parse', 'HEAD'], root);
+    if (res === null || res.code !== 0)
+        return null; // no git / no commits
+    return res.stdout.trim().toLowerCase() || null;
+}
+/**
+ * Is the loop guard live -- i.e. does a sentinel stamped at the CURRENT `HEAD`
+ * exist?
+ *
+ * This is the surviving half of the stage-and-block-once contract (#456). The
+ * component that CLEARED the sentinel on the next commit
+ * (`hooks/guardian_precommit.py`) was deleted as dead code in #449, which left
+ * `author-plan` fail-closed forever: author once in a clone and Tier-2 authoring
+ * never ran again. Stamping HEAD makes the guard self-expiring -- once the human
+ * reviews and commits the staged tests, `HEAD` moves, the stamp stops matching,
+ * and authoring re-enables itself with no manual step and no hook.
+ *
+ * Every unverifiable state FAILS OPEN (returns `false`, authoring allowed):
+ * missing or unreadable sentinel, a malformed/absent `HEAD` header, or a `HEAD`
+ * we cannot resolve. Fail-closed here is exactly the bug being fixed.
+ */
+function authoredSentinelActive(deps, root) {
+    let body;
+    try {
+        body = readFileSync(authoredSentinelPath(deps, root), 'utf-8');
+    }
+    catch {
+        return false; // absent or unreadable -> fail open
+    }
+    const stamp = sentinelHeadStamp(body);
+    if (stamp === null)
+        return false; // malformed -> fail open
+    const head = headSha(deps, root);
+    if (head === null)
+        return false; // unverifiable -> fail open
+    return head === stamp;
+}
 /**
  * Return raw unified-diff text from a source.
  *
@@ -785,7 +840,8 @@ function authorPlanCmd(opts, deps) {
     const ctx = new AuthoringContext(config.precommit_author_tests, effective, {
         is_fork: isForkContext(deps.env),
         repo_root: repoRoot,
-        authored_sentinel_present: existsSync(authoredSentinelPath(deps, repoRoot)),
+        // #456: HEAD-stamped, so the guard expires on the next commit by itself.
+        authored_sentinel_present: authoredSentinelActive(deps, repoRoot),
     });
     const results = deps.makeAgentTier().author_tests(gaps, ctx);
     const decision = decideBlock(results);
@@ -799,11 +855,23 @@ function authorPlanCmd(opts, deps) {
     };
     deps.out(ensureAscii(JSON.stringify(payload, null, 2)));
 }
+/**
+ * Record the authored paths in the loop-guard sentinel, stamped with the HEAD
+ * they were authored at (#456).
+ *
+ * The `HEAD <sha>` header is what makes the guard self-expiring: `author-plan`
+ * honors it only while `HEAD` still matches, so the human's review commit clears
+ * it implicitly. When `HEAD` cannot be resolved (a repo with no commits, or no
+ * git at all) the header is omitted -- an unstamped sentinel reads as malformed
+ * and FAILS OPEN, which is the safe direction.
+ */
 function markAuthoredCmd(opts, deps) {
     const root = gitToplevel(deps);
     const sentinel = authoredSentinelPath(deps, root);
     mkdirSync(dirname(sentinel), { recursive: true });
-    const body = opts.path.map((p) => `${p}\n`).join('');
+    const head = headSha(deps, root);
+    const header = head === null ? '' : `HEAD ${head}\n`;
+    const body = header + opts.path.map((p) => `${p}\n`).join('');
     writeFileSync(sentinel, body, 'utf-8');
     deps.out(`guardian: recorded ${opts.path.length} authored path(s) ${RIGHT_ARROW} ${sentinel}`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canary-test-cli",
-  "version": "6.2.0",
+  "version": "6.3.0",
   "description": "Canary — AI-powered test automation agent",
   "license": "MIT",
   "repository": {