@zq-silk/yui 0.6.0 → 0.6.2

package/dist/verification/verificationPlan.js

@@ -0,0 +1,308 @@
+import { createHash } from "node:crypto";
+import { requireIdentity, requirePositiveInteger, requireText } from "../domain/validation.js";
+/**
+ * Issue 08: the per-Project VerificationPlan contract.
+ *
+ * A Project's verification knowledge lives in its Yui-maintained Project
+ * record (a `verification-plan` knowledge entry, see
+ * {@link resolveProjectVerificationPlan}). The plan is Project Policy: it is
+ * never a hardcoded Yui default. A Project without a plan keeps the existing
+ * explicit `--check <shell>` path, which is marked unstructured and is not
+ * reusable across stages.
+ */
+export const VERIFICATION_PLAN_SCHEMA_VERSION = 1;
+export const VERIFICATION_PLAN_KIND = "verification-plan";
+/** The reserved knowledge marker that carries a Project's VerificationPlan. */
+export const VERIFICATION_PLAN_KNOWLEDGE_KIND = VERIFICATION_PLAN_KIND;
+export function normalizeVerificationPlan(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        throw new Error("VerificationPlan must be an object.");
+    }
+    const record = raw;
+    if (record.kind !== VERIFICATION_PLAN_KIND) {
+        throw new Error(`VerificationPlan kind must be "${VERIFICATION_PLAN_KIND}".`);
+    }
+    const schemaVersion = record.schemaVersion ?? VERIFICATION_PLAN_SCHEMA_VERSION;
+    if (schemaVersion !== VERIFICATION_PLAN_SCHEMA_VERSION) {
+        throw new Error(`VerificationPlan schemaVersion must be ${VERIFICATION_PLAN_SCHEMA_VERSION}.`);
+    }
+    const mode = record.mode ?? "record";
+    if (mode !== "record" && mode !== "reuse" && mode !== "enforce") {
+        throw new Error(`VerificationPlan mode is invalid: ${String(mode)}.`);
+    }
+    const plan = {
+        schemaVersion: VERIFICATION_PLAN_SCHEMA_VERSION,
+        kind: VERIFICATION_PLAN_KIND,
+        id: requireIdentity(record.id, "VerificationPlan id"),
+        version: requireText(record.version, "VerificationPlan version"),
+        mode,
+        toolchain: normalizeToolchain(record.toolchain),
+        bootstrap: normalizeSteps(record.bootstrap, "bootstrap"),
+        l1: {
+            categories: normalizeL1Categories(record.l1)
+        },
+        l2: {
+            steps: normalizeSteps(record.l2?.steps, "l2")
+        },
+        ...(record.l3 === undefined
+            ? {}
+            : {
+                l3: {
+                    steps: normalizeSteps(record.l3?.steps, "l3")
+                }
+            }),
+        ...(record.excludedRealResourceChecks === undefined
+            ? {}
+            : {
+                excludedRealResourceChecks: normalizedTextList(record.excludedRealResourceChecks, "VerificationPlan excludedRealResourceChecks")
+            }),
+        ...(record.artifactTtlDays === undefined
+            ? {}
+            : {
+                artifactTtlDays: requirePositiveInteger(Number(record.artifactTtlDays), "VerificationPlan artifactTtlDays")
+            })
+    };
+    if (plan.l2.steps.length === 0) {
+        throw new Error("VerificationPlan l2 requires at least one step.");
+    }
+    return plan;
+}
+function normalizeToolchain(raw) {
+    if (raw === undefined)
+        return Object.freeze({});
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        throw new Error("VerificationPlan toolchain must be an object.");
+    }
+    const record = raw;
+    const toolchain = {
+        ...(record.node === undefined ? {} : { node: requireText(record.node, "VerificationPlan toolchain node") }),
+        ...(record.npm === undefined ? {} : { npm: requireText(record.npm, "VerificationPlan toolchain npm") }),
+        ...(record.platform === undefined ? {} : { platform: requireText(record.platform, "VerificationPlan toolchain platform") })
+    };
+    return toolchain;
+}
+function normalizeSteps(raw, label) {
+    if (!Array.isArray(raw)) {
+        throw new Error(`VerificationPlan ${label} steps must be an array.`);
+    }
+    const names = new Set();
+    return Object.freeze(raw.map((entry) => {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+            throw new Error(`VerificationPlan ${label} step must be an object.`);
+        }
+        const record = entry;
+        const name = requireIdentity(record.name, `VerificationPlan ${label} step name`);
+        if (names.has(name)) {
+            throw new Error(`VerificationPlan ${label} step names must be unique: ${name}.`);
+        }
+        names.add(name);
+        if (!Array.isArray(record.argv) || record.argv.length === 0) {
+            throw new Error(`VerificationPlan ${label} step ${name} requires a non-empty argv.`);
+        }
+        const argv = Object.freeze(record.argv.map((value) => requireText(value, `VerificationPlan ${label} step ${name} argv`)));
+        const step = {
+            name,
+            argv,
+            ...(record.cwd === undefined ? {} : { cwd: requireText(record.cwd, `VerificationPlan ${label} step ${name} cwd`) }),
+            ...(record.env === undefined ? {} : { env: normalizeStepEnv(record.env, `${label} step ${name}`) }),
+            ...(record.shell === undefined ? {} : { shell: record.shell === true })
+        };
+        if (step.cwd !== undefined && step.cwd.startsWith("/")) {
+            throw new Error(`VerificationPlan ${label} step ${name} cwd must be workspace-relative.`);
+        }
+        return step;
+    }));
+}
+function normalizeStepEnv(raw, label) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        throw new Error(`VerificationPlan ${label} env must be a map.`);
+    }
+    const env = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (typeof value !== "string") {
+            throw new Error(`VerificationPlan ${label} env values must be strings: ${key}.`);
+        }
+        env[requireIdentity(key, `VerificationPlan ${label} env key`)] = value;
+    }
+    return Object.freeze(env);
+}
+function normalizeL1Categories(raw) {
+    if (raw === undefined)
+        return Object.freeze([]);
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        throw new Error("VerificationPlan l1 must be an object.");
+    }
+    const categoriesRaw = raw.categories;
+    if (!Array.isArray(categoriesRaw)) {
+        throw new Error("VerificationPlan l1 categories must be an array.");
+    }
+    const ids = new Set();
+    return Object.freeze(categoriesRaw.map((entry) => {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+            throw new Error("VerificationPlan l1 category must be an object.");
+        }
+        const record = entry;
+        const id = requireIdentity(record.id, "VerificationPlan l1 category id");
+        if (ids.has(id)) {
+            throw new Error(`VerificationPlan l1 category ids must be unique: ${id}.`);
+        }
+        ids.add(id);
+        return Object.freeze({
+            id,
+            paths: normalizedTextList(record.paths, `VerificationPlan l1 category ${id} paths`),
+            checks: normalizeSteps(record.checks, `l1 ${id}`)
+        });
+    }));
+}
+function normalizedTextList(raw, label) {
+    if (!Array.isArray(raw)) {
+        throw new Error(`${label} must be an array.`);
+    }
+    const seen = new Set();
+    return Object.freeze(raw.map((value) => {
+        const text = requireText(value, label);
+        if (seen.has(text))
+            throw new Error(`${label} must be unique: ${text}.`);
+        seen.add(text);
+        return text;
+    }));
+}
+/**
+ * The stable digest of the gate contract. It deliberately excludes the
+ * rollout `mode`, retention window, and documentation fields: changing the
+ * rollout switch must not invalidate proven gate evidence.
+ */
+export function verificationPlanDigest(plan) {
+    const canonical = canonicalJson({
+        id: plan.id,
+        version: plan.version,
+        toolchain: plan.toolchain,
+        bootstrap: plan.bootstrap,
+        l1: plan.l1,
+        l2: plan.l2,
+        ...(plan.l3 === undefined ? {} : { l3: plan.l3 })
+    });
+    return createHash("sha256").update(canonical).digest("hex");
+}
+/** Resolve the runtime toolchain identity from the current process. */
+export function resolveToolchain() {
+    return Object.freeze({
+        node: process.version,
+        ...(process.env.npm_version === undefined ? {} : { npm: process.env.npm_version }),
+        platform: process.platform,
+        arch: process.arch
+    });
+}
+/**
+ * Digest of the toolchain a gate actually ran under, bound to the plan's
+ * declared requirements. A Node upgrade, platform change, or plan toolchain
+ * edit changes the digest and invalidates reuse.
+ */
+export function toolchainDigest(plan, toolchain) {
+    const canonical = canonicalJson({
+        constraints: plan.toolchain,
+        node: toolchain.node,
+        ...(toolchain.npm === undefined ? {} : { npm: toolchain.npm }),
+        platform: toolchain.platform,
+        arch: toolchain.arch
+    });
+    return createHash("sha256").update(canonical).digest("hex");
+}
+/**
+ * Select the L1 checks for a change: every category whose path prefixes match
+ * a changed path. A category with no path prefixes matches nothing (it must
+ * be selected explicitly by the caller).
+ */
+export function selectL1Checks(plan, changedPaths) {
+    const selected = new Map();
+    for (const category of plan.l1.categories) {
+        if (category.paths.length === 0)
+            continue;
+        const matches = changedPaths.some((path) => category.paths.some((prefix) => path === prefix || path.startsWith(`${prefix}/`)));
+        if (!matches)
+            continue;
+        for (const check of category.checks) {
+            if (!selected.has(check.name))
+                selected.set(check.name, check);
+        }
+    }
+    return Object.freeze([...selected.values()]);
+}
+/** Bootstrap steps as DurableJob steps, named `bootstrap-N`. */
+export function planBootstrapJobSteps(plan) {
+    return plan.bootstrap.map((step, index) => toDurableJobStep(step, `bootstrap-${index + 1}`));
+}
+/** L2 gate steps as DurableJob steps, named `gate-N`. */
+export function planL2JobSteps(plan) {
+    return plan.l2.steps.map((step, index) => toDurableJobStep(step, `gate-${index + 1}`));
+}
+/** L1 steps as DurableJob steps, named `l1-N`. */
+export function planL1JobSteps(steps) {
+    return steps.map((step, index) => toDurableJobStep(step, `l1-${index + 1}`));
+}
+function toDurableJobStep(step, name) {
+    return {
+        name,
+        // The shell-equivalent command stays as the human-readable fallback and
+        // the coverage-matching string; argv is the executable form.
+        command: step.shell === true ? step.argv.join(" ") : shellQuote(step.argv),
+        argv: step.argv,
+        ...(step.cwd === undefined ? {} : { cwd: step.cwd }),
+        ...(step.env === undefined ? {} : { env: step.env })
+    };
+}
+/** The shell-equivalent of a structured step, for display and coverage. */
+export function verificationStepCommand(step) {
+    return step.shell === true ? step.argv.join(" ") : shellQuote(step.argv);
+}
+function shellQuote(argv) {
+    return argv.map((value) => (/^[A-Za-z0-9_./:=@+-]+$/u.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`)).join(" ");
+}
+/**
+ * Resolve a Project's VerificationPlan from its Yui-maintained knowledge.
+ * A knowledge entry whose JSON body declares `kind: verification-plan` is
+ * the plan; malformed plan bodies fail closed. Free-text knowledge entries
+ * are ignored. A Project without a plan returns `undefined` (unstructured
+ * explicit-check mode).
+ */
+export function resolveProjectVerificationPlan(project) {
+    let found;
+    for (const entry of project.knowledge) {
+        if (entry.status !== "active")
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(entry.body);
+        }
+        catch {
+            continue;
+        }
+        if (typeof parsed !== "object" || parsed === null
+            || parsed.kind !== VERIFICATION_PLAN_KIND) {
+            continue;
+        }
+        const plan = normalizeVerificationPlan(parsed);
+        if (found !== undefined) {
+            throw new Error(`Project ${project.id} declares multiple VerificationPlans; only one is allowed.`);
+        }
+        found = plan;
+    }
+    return found;
+}
+/** Serialize a plan for storage in a Project knowledge entry body. */
+export function verificationPlanKnowledgeBody(plan) {
+    return `${JSON.stringify(plan, null, 2)}\n`;
+}
+function canonicalJson(value) {
+    return JSON.stringify(canonicalize(value));
+}
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (typeof value === "object" && value !== null) {
+        const entries = Object.entries(value)
+            .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+        return Object.fromEntries(entries.map(([key, entry]) => [key, canonicalize(entry)]));
+    }
+    return value;
+}

package/dist/workspace/gitChangeSetCapture.js

@@ -21,13 +21,23 @@ export async function captureManagedGitChanges(input) {
     const headCommit = await assertManagedHead(input);
     if (headCommit === input.baseCommit)
         return null;
+    // Rename folding is disabled on purpose: a rename must record its source
+    // path as touched and deleted.  With rename detection a pure rename would
+    // surface only the destination, letting a target that added the same file
+    // in parallel (but kept the source) converge on a partial-tree proof.
     const changedPaths = (await git([
         "-C", input.path,
-        "diff", "--name-only", "-z",
+        "diff", "--no-renames", "--name-only", "-z",
         input.baseCommit,
         headCommit
     ])).split("\0").filter(Boolean);
-    return { headCommit, changedPaths };
+    const deletedPaths = (await git([
+        "-C", input.path,
+        "diff", "--no-renames", "--name-only", "-z", "--diff-filter=D",
+        input.baseCommit,
+        headCommit
+    ])).split("\0").filter(Boolean);
+    return { headCommit, changedPaths, deletedPaths };
 }
 async function assertManagedHead(input) {
     const currentBranch = (await git([

package/dist/workspace/workItemChangeSetManager.js

@@ -1,5 +1,7 @@
 import { isDeepStrictEqual } from "node:util";
 import { createWorkItemChangeSet } from "../integration/changeSet.js";
+import { createChangeSetManifest } from "../integration/changeSetManifest.js";
+import { deriveManifestTags } from "../integration/manifestTags.js";
 import { NodeGitWorkspace } from "../repository/gitWorkspace.js";
 import { sameTaskFinalReviewContract } from "../review/taskFinalReviewContract.js";
 import { managedWorkspaceKey } from "../worktree/managedWorkspace.js";
@@ -216,6 +218,16 @@ export class WorkItemChangeSetManager {
         const existing = findWorkItemChangeSet(this.store, context.taskId, context.workItemId, entry.projectId, entry.baseCommit, result.headCommit);
         if (existing !== undefined)
             return existing;
+        const targetRef = captureTargetRef(this.store, context.taskId, entry.projectId);
+        const manifest = createChangeSetManifest({
+            tags: deriveManifestTags({
+                changedPaths: result.changedPaths,
+                deletedPaths: result.deletedPaths
+            }),
+            deletedPaths: result.deletedPaths,
+            ...(targetRef === undefined ? {} : { targetRef }),
+            evidenceRefs: this.#captureEvidenceRefs(context.taskId, context.workItemId, result.headCommit)
+        });
         return this.store.transaction((tx) => {
             assertCaptureStillCurrent(tx, context);
             const concurrent = findWorkItemChangeSet(tx, context.taskId, context.workItemId, entry.projectId, entry.baseCommit, result.headCommit);
@@ -238,12 +250,46 @@ export class WorkItemChangeSetManager {
                 baseCommit: entry.baseCommit,
                 headCommit: result.headCommit,
                 branch: entry.branch,
-                changedPaths: result.changedPaths
+                changedPaths: result.changedPaths,
+                manifest
             }, nextCaptureTime(tx, context.taskId, context.workItemId, entry.projectId, this.now()));
             tx.saveChangeSet(context.taskId, changeSet);
             return changeSet;
         });
     }
+    /**
+     * Verified evidence for the exact reviewed candidate.  A completed
+     * ReviewRound freezes the candidate it reviewed at `reviewBaseCommit`; when
+     * the captured ChangeSet head is that commit, the round's checks are
+     * durable evidence for it.  "completed" alone is not a verdict: the
+     * reviewer may have yielded with failed checks (requires-repair), so only a
+     * round with an explicit positive verdict — at least one passed check and
+     * no failed one — may feed `evidenceRefs`.  The link is by
+     * `reviewBaseCommit`, not by `evidenceCommit`: the latter records the exact
+     * tree the checks ran on (the frozen base for a clean review, a diagnostic
+     * commit for a committed-diagnostic review, absent for a dirty review), and
+     * the queue separately re-checks that tree binding before waiving a gate.
+     */
+    #captureEvidenceRefs(taskId, workItemId, headCommit) {
+        return this.store.listReviewRounds(taskId)
+            .filter((round) => round.status === "completed"
+            && round.workItemId === workItemId
+            && round.reviewBaseCommit === headCommit
+            && hasPositiveReviewVerdict(round.checks))
+            .map(({ id }) => `review-round:${id}`);
+    }
+}
+/**
+ * A ReviewRound carries reusable verification evidence only when its checks
+ * state an explicit positive verdict: at least one check passed and none
+ * failed.  A round without checks, or with only skipped checks, has no
+ * positive conclusion; a round with a failed check rejects the candidate.
+ * Neither may skip a later gate.
+ */
+function hasPositiveReviewVerdict(checks) {
+    return checks !== undefined
+        && checks.some((check) => check.outcome === "passed")
+        && checks.every((check) => check.outcome !== "failed");
 }
 function requireCapturableContext(store, taskId, workItemId, taskFinalReviewContract) {
     const item = store.getWorkItem(taskId, workItemId);
@@ -410,8 +456,7 @@ function writableEntries(workspace) {
     return workspace.entries.filter(({ access }) => access === "write");
 }
 function latestWorkItemChangeSet(store, taskId, workItemId, projectId, commits) {
-    return store.listChangeSets(taskId).filter((changeSet) => (changeSet.schemaVersion === 2
-        && changeSet.workItemId === workItemId
+    return store.listChangeSets(taskId).filter((changeSet) => (changeSet.workItemId === workItemId
         && changeSet.projectId === projectId
         && (commits === undefined
             || (changeSet.baseCommit === commits.baseCommit
@@ -423,6 +468,18 @@ function findWorkItemChangeSet(store, taskId, workItemId, projectId, baseCommit,
         headCommit
     });
 }
+/**
+ * The intended integration target for a captured Project change: the Task
+ * main worktree branch for that Project, matching the Integration default.
+ * Returns undefined when the Task main worktree is not ready yet.
+ */
+function captureTargetRef(store, taskId, projectId) {
+    const mainWorkspace = store.getTaskWorkspace(taskId);
+    if (mainWorkspace === null)
+        return undefined;
+    const entry = mainWorkspace.entries.find((candidate) => candidate.projectId === projectId);
+    return entry?.branch;
+}
 function compareNewestFirst(left, right) {
     return right.createdAt.localeCompare(left.createdAt) || right.id.localeCompare(left.id);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zq-silk/yui",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Local control plane for long-running native agent CLI sessions backed by tmux.",
   "license": "MIT",
   "private": false,

package/skills/yui-leader/SKILL.md

@@ -100,6 +100,14 @@ unavailable external fact that blocks progress.
 
 ## Lead with judgment
 
+- `yui task next-action <task-id>` is decision support, not an autopilot. It
+  reads durable Task records and returns one recommended command, exact refs,
+  legitimate alternatives, and any `judgmentRequired` explanation. The Leader
+  still owns product priority, acceptance, risk, and the choice among legal
+  alternatives. Treat protocol inconsistencies, active Run ownership, open
+  InputRequests, Draft activation, exact duplicates, and durable final-review
+  contracts as hard boundaries; treat semantic-budget and suspected-duplicate
+  warnings as evidence rather than commands.
 - Keep the context layers distinct in every handoff: Yui Core supplies durable
   identity, lifecycle, access, workspace, and exact-yield safety; this generic
   role Skill supplies portable collaboration behavior; the bound Project's