speccle 0.12.0 → 0.16.0

package/dist/claims.js

@@ -1,6 +1,6 @@
 import { readFile, stat } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
-import { readConfig } from "./config.js";
+import { readConfig, resolveFacts } from "./config.js";
 import { DEFAULT_DIALECT, resolveDialect } from "./dialects.js";
 import { discoverSpecs, discoverTests } from "./discover.js";
 import { compareCriterionIds, parseSpec, readClaimedIds } from "./spec.js";
@@ -8,10 +8,13 @@ export async function claims(target, options = {}) {
     const root = resolve(target);
     if (!(await isDirectory(root)))
         throw new Error(`path not found: ${target}`);
-    // An explicit --dialect wins outright; otherwise `.speccle/config.json` is the source
-    // of truth, falling back to the default only when the repo has recorded nothing.
-    const declared = options.dialect ?? (await readConfig(root))?.dialect;
-    const dialect = resolveDialect(declared ?? DEFAULT_DIALECT);
+    // An explicit --dialect wins outright, everywhere; otherwise `.speccle/config.json` is the
+    // source of truth, and its per-path overrides let one pass join a mixed-language tree under
+    // each folder's own dialect (ADR-0040). The default applies only to a repo with no config.
+    const forced = options.dialect === undefined ? undefined : resolveDialect(options.dialect);
+    const config = forced === undefined ? await readConfig(root) : undefined;
+    const dialectAt = (folder) => forced ??
+        resolveDialect(config === undefined ? DEFAULT_DIALECT : resolveFacts(config, folder).dialect);
     const specFiles = await discoverSpecs(root);
     const specs = await Promise.all(specFiles.map(async (file) => parseSpec(await readFile(join(root, file), "utf8"), file)));
     const criteria = new Map();
@@ -25,18 +28,23 @@ export async function claims(target, options = {}) {
     // A slice's tests live in its own folder: only test files under a spec's folder
     // count, so unrelated tooling tests can never claim (or phantom-claim) a criterion.
     const folders = [...new Set(specFiles.map((file) => dirname(file)))];
-    const found = new Set();
-    for (const folder of folders) {
+    const folderDialects = new Map(folders.map((folder) => [folder, dialectAt(folder)]));
+    // Nested spec folders can each discover the same test file, under different dialects. The
+    // deepest folder's dialect reads it — the same most-specific-path rule the config resolves
+    // an override under, so walking the folders shortest-first lets the deepest one win.
+    const fileDialects = new Map();
+    for (const folder of [...folders].sort((a, b) => a.length - b.length)) {
+        const folderDialect = folderDialects.get(folder);
         const abs = folder === "." ? root : join(root, folder);
-        for (const file of await discoverTests(abs, dialect)) {
-            found.add(folder === "." ? file : `${folder}/${file}`);
+        for (const file of await discoverTests(abs, folderDialect)) {
+            fileDialects.set(folder === "." ? file : `${folder}/${file}`, folderDialect);
         }
     }
-    const testFiles = [...found].sort();
+    const testFiles = [...fileDialects.keys()].sort();
     const claimsById = new Map();
     for (const file of testFiles) {
         const source = await readFile(join(root, file), "utf8");
-        for (const { name, spelling } of dialect.readTestNames(source)) {
+        for (const { name, spelling } of fileDialects.get(file).readTestNames(source)) {
             for (const id of readClaimedIds(name, spelling)) {
                 const entry = claimsById.get(id) ?? [];
                 entry.push({ file, name });
@@ -47,6 +55,7 @@ export async function claims(target, options = {}) {
     const features = specs.map((spec) => ({
         key: spec.key?.raw,
         spec: spec.file,
+        dialect: folderDialects.get(dirname(spec.file)).name,
         criteria: [...criteria.entries()]
             .filter(([, value]) => value.spec === spec.file)
             .map(([id, value]) => ({
@@ -64,9 +73,12 @@ export async function claims(target, options = {}) {
         .filter(([id]) => !criteria.has(id))
         .map(([id, tests]) => ({ id, tests }))
         .sort((a, b) => compareCriterionIds(a.id, b.id));
+    // With no spec at all no folder resolved a dialect, so name the one a pass at the root
+    // would have run under rather than reporting none in play.
+    const inPlay = folders.length === 0 ? [dialectAt(".")] : [...folderDialects.values()];
     return {
         root,
-        dialect: dialect.name,
+        dialects: [...new Set(inPlay.map((entry) => entry.name))].sort(),
         testFiles,
         features,
         unclaimed,

package/dist/cli.js

@@ -1,31 +1,84 @@
 #!/usr/bin/env node
+import { calibrationReport, recordCalibration } from "./calibration.js";
 import { check } from "./check.js";
 import { claims } from "./claims.js";
 import { initConfig } from "./config.js";
 import { DEFAULT_DIALECT, DIALECT_NAMES } from "./dialects.js";
 import { doctor } from "./doctor.js";
-import { init, ownVersion } from "./init.js";
+import { detectDoubleLoad, init, ownVersion } from "./init.js";
+import { materializeLenses } from "./lenses.js";
 import { lint } from "./lint.js";
-import { renderCheck, renderClaims, renderConfigInit, renderDoctor, renderHuman, renderInit, renderSkillsInit, renderStrength, renderUpdate, } from "./render.js";
+import { recallRemedy, recordRemedy, REMEDY_ROUTES } from "./remedy.js";
+import { renderCalibrateRecord, renderCalibrateReport, renderCheck, renderClaims, renderConfigInit, renderDoctor, renderDoubleLoad, renderHuman, renderInit, renderLensesInit, renderRemedyRecall, renderRemedyRecord, renderReviewInit, renderReviewRun, renderRisk, renderSkillsInit, renderStrength, renderUpdate, renderVerify, } from "./render.js";
+import { scaffoldReviewWorkflow } from "./reviewinit.js";
+import { reviewRun } from "./reviewrun.js";
+import { risk } from "./risk.js";
 import { materializeSkills } from "./skills.js";
 import { DEFAULT_COVERAGE_SUMMARY, DEFAULT_MUTATION_REPORT, strength } from "./strength.js";
 import { update } from "./update.js";
+import { verify } from "./verify.js";
 const USAGE = `Usage: speccle <command> [options]
 
 Commands:
-  init [path] [--json]           Record repo facts in .speccle/config.json and materialize
-                                 the skills into .claude/skills/
-  doctor [path] [--json]         Report staleness across the CLI, skills, and strength stack
-  update [path] [--json]         Refresh the skills as a diff; report the stack and binary fixes
+  init [path] [--json]           Record repo facts in .speccle/config.json, materialize the
+                                 skills into .claude/skills/ and the lenses into .speccle/lenses/
+  doctor [path] [--json]         Report staleness across the CLI, skills, lenses, the CI driver's
+                                 pin, and the strength stack
+  update [path] [--json]         Refresh the skills and lenses as a diff, and an already-installed
+                                 CI driver's pin; report stack and binary fixes
   lint [path] [--json]           Lint every SPEC.md under path (default: current directory)
   claims [path] [--json]         Join criteria to the test names that claim them — no reports needed
+  verify [path] [--json]         Run .speccle/checks/ against the change set: cross-file invariants
+  risk [path] [--json]           Score the change set from spec-aware signals; gate on the review threshold
+  calibrate record [path]        Append a calibration entry: the risk floor + your honest verdict
+  calibrate report [path]        Read the calibration record: signal reliability + the supported threshold
+  remedy record [path]           Record a remedy: the finding, the fix, and the prevention artefact
+  remedy recall [path]           Recall the known remedy for a finding's class — fix consistently
+  review init [path] [--json]    Scaffold the opt-in CI driver: a GitHub Actions workflow, pinned
+  review run [path]              Review a pull request with the lens panel and post one review.
+                                 The one command here that calls a model — needs a metered key
   strength [path] [--json]       Oracle-strength heatmap: per-criterion killed ÷ covered
   strength init [path] [--json]  Provision the strength stack: devDependencies + configs
   --version, -v                  Print the installed CLI version
 
-claims options:
+claims / risk options:
   --dialect <name>    Test dialect: ${DIALECT_NAMES.join(", ")} (default: ${DEFAULT_DIALECT})
 
+verify / risk options:
+  --base <ref>        Read the change set from the commits between <ref> and HEAD, instead of the
+                      working tree's pending change — what a CI driver needs, where the tree is
+                      clean. Measured from the merge base, so it needs their shared history
+
+risk exit codes: 0 below the review threshold (review may fix), 1 at or above it (human required)
+
+calibrate record options:
+  --needed-human <true|false>  Did this change actually need a human? (required — the honest verdict)
+  --found-real <true|false>    Did the review find something real? (required)
+  --escalated                  A risk lens escalated beyond the deterministic floor
+  --note <text>                Free-text context for the entry
+  --dialect <name>             Test dialect: ${DIALECT_NAMES.join(", ")} (default: ${DEFAULT_DIALECT})
+
+remedy record options:
+  --class <handle>             Short, stable handle for the finding's class (required — the recall key)
+  --finding <text>             What the finding is (required)
+  --fix <text>                 The fix applied to the code (required)
+  --route <route>              Prevention route: ${REMEDY_ROUTES.join(", ")} (required)
+  --artefact <ref>             The prevention artefact: a .speccle/checks|lenses path or a SPEC
+                               criterion id (required for every route but none)
+  --note <text>                Free-text context for the entry
+
+remedy recall options:
+  --class <handle>             The finding's class to look up (required)
+
+review run options:
+  --pr <number>                The pull request to review (required)
+  --repo <owner/name>          Defaults to GITHUB_REPOSITORY
+  --base <ref>                 Base ref for the risk verdict (default: origin/<the PR's base>)
+  --force                      Review again even if this driver already reviewed the PR
+  --model <id>                 Overrides SPECCLE_REVIEW_MODEL
+  --dry-run                    Report what would be posted, and post nothing
+  Reads ANTHROPIC_API_KEY and GITHUB_TOKEN from the environment
+
 strength options:
   --check             Report whether the reports are fresh, stale, or missing — never runs them
   --mutation <file>   Stryker JSON report   (default: ${DEFAULT_MUTATION_REPORT})
@@ -53,6 +106,34 @@ async function main(argv) {
         return runLint(rest);
     if (command === "claims")
         return runClaims(rest);
+    if (command === "verify")
+        return runVerify(rest);
+    if (command === "risk")
+        return runRisk(rest);
+    if (command === "calibrate" && rest[0] === "record")
+        return runCalibrateRecord(rest.slice(1));
+    if (command === "calibrate" && rest[0] === "report")
+        return runCalibrateReport(rest.slice(1));
+    if (command === "calibrate") {
+        console.error(`calibrate needs a subcommand: record or report\n\n${USAGE}`);
+        return 2;
+    }
+    if (command === "remedy" && rest[0] === "record")
+        return runRemedyRecord(rest.slice(1));
+    if (command === "remedy" && rest[0] === "recall")
+        return runRemedyRecall(rest.slice(1));
+    if (command === "remedy") {
+        console.error(`remedy needs a subcommand: record or recall\n\n${USAGE}`);
+        return 2;
+    }
+    if (command === "review" && rest[0] === "init")
+        return runReviewInit(rest.slice(1));
+    if (command === "review" && rest[0] === "run")
+        return runReviewRun(rest.slice(1));
+    if (command === "review") {
+        console.error(`review needs a subcommand: init or run\n\n${USAGE}`);
+        return 2;
+    }
     if (command === "strength" && rest[0] === "init")
         return runStrengthInit(rest.slice(1));
     if (command === "strength")
@@ -98,6 +179,300 @@ async function runClaims(args) {
     console.log(json ? JSON.stringify(report, null, 2) : renderClaims(report));
     return report.clean ? 0 : 1;
 }
+async function runVerify(args) {
+    let json = false;
+    let base;
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--base") {
+            const value = args[++i];
+            if (value === undefined) {
+                console.error(`--base needs a git ref\n\n${USAGE}`);
+                return 2;
+            }
+            base = value;
+        }
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`verify takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await verify(positional[0] ?? ".", { ...(base !== undefined && { base }) });
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderVerify(report));
+    return report.clean ? 0 : 1;
+}
+async function runRisk(args) {
+    let json = false;
+    let dialect;
+    let base;
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--dialect" || arg === "--base") {
+            const value = args[++i];
+            if (value === undefined) {
+                console.error(`${arg} needs ${arg === "--base" ? "a git ref" : "a dialect name"}\n\n${USAGE}`);
+                return 2;
+            }
+            if (arg === "--dialect")
+                dialect = value;
+            else
+                base = value;
+        }
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`risk takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await risk(positional[0] ?? ".", {
+            ...(dialect !== undefined && { dialect }),
+            ...(base !== undefined && { base }),
+        });
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderRisk(report));
+    return report.humanRequired ? 1 : 0;
+}
+async function runCalibrateRecord(args) {
+    let json = false;
+    let dialect;
+    let neededHuman;
+    let foundReal;
+    let escalated = false;
+    let note;
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--escalated")
+            escalated = true;
+        else if (arg === "--needed-human" || arg === "--found-real") {
+            const value = args[++i];
+            if (value !== "true" && value !== "false") {
+                console.error(`${arg} needs true or false\n\n${USAGE}`);
+                return 2;
+            }
+            if (arg === "--needed-human")
+                neededHuman = value === "true";
+            else
+                foundReal = value === "true";
+        }
+        else if (arg === "--note" || arg === "--dialect") {
+            const value = args[++i];
+            if (value === undefined) {
+                console.error(`${arg} needs a value\n\n${USAGE}`);
+                return 2;
+            }
+            if (arg === "--note")
+                note = value;
+            else
+                dialect = value;
+        }
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`calibrate record takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    // The honest verdict is required, never defaulted — a fabricated verdict is the dishonest
+    // calibration data ADR-0042 exists to keep out of the record.
+    if (neededHuman === undefined || foundReal === undefined) {
+        console.error(`calibrate record needs --needed-human and --found-real\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await recordCalibration(positional[0] ?? ".", { neededHuman, foundReal, escalated, ...(note !== undefined && { note }) }, { ...(dialect !== undefined && { dialect }) });
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderCalibrateRecord(report));
+    return 0;
+}
+async function runCalibrateReport(args) {
+    let json = false;
+    const positional = [];
+    for (const arg of args) {
+        if (arg === "--json")
+            json = true;
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`calibrate report takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await calibrationReport(positional[0] ?? ".");
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderCalibrateReport(report));
+    return 0;
+}
+async function runRemedyRecord(args) {
+    let json = false;
+    let classHandle;
+    let finding;
+    let fix;
+    let route;
+    let artefact;
+    let note;
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--class" ||
+            arg === "--finding" ||
+            arg === "--fix" ||
+            arg === "--route" ||
+            arg === "--artefact" ||
+            arg === "--note") {
+            const value = args[++i];
+            if (value === undefined) {
+                console.error(`${arg} needs a value\n\n${USAGE}`);
+                return 2;
+            }
+            if (arg === "--class")
+                classHandle = value;
+            else if (arg === "--finding")
+                finding = value;
+            else if (arg === "--fix")
+                fix = value;
+            else if (arg === "--route")
+                route = value;
+            else if (arg === "--artefact")
+                artefact = value;
+            else
+                note = value;
+        }
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`remedy record takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    if (classHandle === undefined ||
+        finding === undefined ||
+        fix === undefined ||
+        route === undefined) {
+        console.error(`remedy record needs --class, --finding, --fix, and --route\n\n${USAGE}`);
+        return 2;
+    }
+    if (!REMEDY_ROUTES.includes(route)) {
+        console.error(`--route must be one of ${REMEDY_ROUTES.join(", ")}\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await recordRemedy(positional[0] ?? ".", {
+            class: classHandle,
+            finding,
+            fix,
+            route: route,
+            ...(artefact !== undefined && { artefact }),
+            ...(note !== undefined && { note }),
+        });
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderRemedyRecord(report));
+    return 0;
+}
+async function runRemedyRecall(args) {
+    let json = false;
+    let classHandle;
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--class") {
+            const value = args[++i];
+            if (value === undefined) {
+                console.error(`--class needs a value\n\n${USAGE}`);
+                return 2;
+            }
+            classHandle = value;
+        }
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`remedy recall takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    if (classHandle === undefined) {
+        console.error(`remedy recall needs --class\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await recallRemedy(positional[0] ?? ".", classHandle);
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderRemedyRecall(report));
+    return 0;
+}
 async function runDoctor(args) {
     let json = false;
     const positional = [];
@@ -266,24 +641,136 @@ async function runInit(args) {
     const root = positional[0] ?? ".";
     let config;
     let skills;
+    let lenses;
+    let doubleLoad;
     try {
-        // Materialize first, then stamp the version onto the config — so the recorded anchor
-        // only ever names skills that actually landed on disk.
+        // Materialize first, then stamp the version onto the config — so the recorded anchors
+        // only ever name the skills and lenses that actually landed on disk.
         skills = await materializeSkills(root);
+        lenses = await materializeLenses(root);
         config = await initConfig(root, await ownVersion());
+        // Asked after materializing: this run is what makes the repo a project-level vendor, so
+        // the double-load it may have just created is exactly what the human needs told (#183).
+        doubleLoad = await detectDoubleLoad(root);
     }
     catch (err) {
         console.error(message(err));
         return 2;
     }
     if (json) {
-        console.log(JSON.stringify({ config, skills }, null, 2));
+        console.log(JSON.stringify({ config, skills, lenses, doubleLoad }, null, 2));
     }
     else {
         console.log(renderConfigInit(config));
         console.log("");
         console.log(renderSkillsInit(skills));
+        console.log("");
+        console.log(renderLensesInit(lenses));
+        if (doubleLoad) {
+            console.log("");
+            console.log(renderDoubleLoad());
+        }
+    }
+    return 0;
+}
+async function runReviewInit(args) {
+    let json = false;
+    const positional = [];
+    for (const arg of args) {
+        if (arg === "--json")
+            json = true;
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`review init takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await scaffoldReviewWorkflow(positional[0] ?? ".");
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderReviewInit(report));
+    return 0;
+}
+async function runReviewRun(args) {
+    let json = false;
+    let force = false;
+    let dryRun = false;
+    let pr;
+    let repo;
+    let base;
+    let model;
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--force")
+            force = true;
+        else if (arg === "--dry-run")
+            dryRun = true;
+        else if (arg === "--pr" || arg === "--repo" || arg === "--base" || arg === "--model") {
+            const value = args[++i];
+            if (value === undefined) {
+                console.error(`${arg} needs a value\n\n${USAGE}`);
+                return 2;
+            }
+            if (arg === "--pr") {
+                const number = Number(value);
+                if (!Number.isInteger(number) || number <= 0) {
+                    console.error(`--pr needs a pull request number\n\n${USAGE}`);
+                    return 2;
+                }
+                pr = number;
+            }
+            else if (arg === "--repo")
+                repo = value;
+            else if (arg === "--base")
+                base = value;
+            else
+                model = value;
+        }
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`review run takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    if (pr === undefined) {
+        console.error(`review run needs --pr\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await reviewRun(positional[0] ?? ".", {
+            pr,
+            force,
+            dryRun,
+            ...(repo !== undefined && { repo }),
+            ...(base !== undefined && { base }),
+            ...(model !== undefined && { model }),
+        });
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
     }
+    console.log(json ? JSON.stringify(report, null, 2) : renderReviewRun(report));
+    // Posting findings is not a failure: the risk gate is the check, and it runs as its own step.
     return 0;
 }
 async function runStrengthInit(args) {

package/dist/config.js

@@ -58,22 +58,25 @@ export async function detectConfig(root) {
  * written record is the source of truth, never the detection (ADR-0040), the same posture
  * `strength init` takes with the stack it provisions.
  *
- * When `skillsVersion` is given, it is (re)stamped even on the kept path: materialization
- * always refreshes the skills to the current version, so the anchor must move with them or
- * a re-run would leave the recorded version behind the files it just wrote. The facts
- * themselves stay kept — only the stamp follows the skills.
+ * When `payloadVersion` is given, it is (re)stamped onto both the skills and the lenses
+ * anchors even on the kept path: `init`/`update` materialize both from the same tarball, so
+ * the two anchors must move with them or a re-run would leave a recorded version behind the
+ * files it just wrote. The facts themselves stay kept — only the stamps follow the payload.
  */
-export async function initConfig(root, skillsVersion) {
+export async function initConfig(root, payloadVersion) {
+    const stamped = (config) => payloadVersion === undefined
+        ? config
+        : { ...config, skillsVersion: payloadVersion, lensesVersion: payloadVersion };
     const existing = await readConfig(root);
     if (existing !== undefined) {
-        const config = skillsVersion !== undefined ? { ...existing, skillsVersion } : existing;
-        if (skillsVersion !== undefined && existing.skillsVersion !== skillsVersion) {
+        const config = stamped(existing);
+        const moved = payloadVersion !== undefined &&
+            (existing.skillsVersion !== payloadVersion || existing.lensesVersion !== payloadVersion);
+        if (moved)
             await writeConfig(root, config);
-        }
         return { root, file: CONFIG_FILE, action: "kept", config };
     }
-    const detected = await detectConfig(root);
-    const config = skillsVersion !== undefined ? { ...detected, skillsVersion } : detected;
+    const config = stamped(await detectConfig(root));
     await writeConfig(root, config);
     return { root, file: CONFIG_FILE, action: "written", config };
 }