@davidorex/pi-context 0.32.0 → 0.33.0

package/dist/context-sdk.js

@@ -7,13 +7,13 @@ import { execSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { readBlock, readBlockForDir, updateItemInBlock } from "./block-api.js";
+import { readBlock, readBlockForDir, resolveGitRefOrNull, updateItemInBlock } from "./block-api.js";
+import { computeFileBytesHash } from "./content-hash.js";
 import { appendRelation, appendRelations, counterEndpoint, endpointIdentity, endpointKey, findUnmaterializedAssets, isSkeletonConfig, loadConfig, loadConfigForDir, loadRelations, primaryEndpoint, removeRelation, validateRelations, writeRelations, } from "./context.js";
 import { resolveContextDir, SCHEMAS_DIR, schemaPath, schemasDir, tryResolveContextDir } from "./context-dir.js";
 import { loadRegistry, resolveAlias, resolveSubstrateDir } from "./context-registry.js";
 import { cleanGitEnv } from "./git-env.js";
 import { getLensValidators } from "./lens-validator.js";
-import { findReferencesInRepo } from "./lens-view.js";
 import { getProjectMigrationRegistryForDir } from "./migration-registry-loader.js";
 import { addressInto, discoverArrayKey, pageArray } from "./read-element.js";
 import { ValidationError, validateBlockWithMigrationForDir, validateFromFile } from "./schema-validator.js";
@@ -573,6 +573,35 @@ function renderReasonTemplate(template, tokens) {
         return v !== undefined ? v : match;
     });
 }
+/**
+ * Rollup-aware completeness — the ONE truth model for "is this item complete"
+ * (FEAT-011 — FGAP-116). A kind declared in `state_derivation.rollups` is
+ * DERIVED-status: complete iff it has ≥1 member (via the rollup's membership
+ * relation, oriented by `role_direction`) and every member is complete under
+ * this same function (recursively rollup-aware; a `visiting` guard makes a
+ * membership cycle derive not-complete instead of recursing forever). Every
+ * other kind is complete iff its status buckets to "complete". SHARED by
+ * `currentState` (gate satisfaction + the milestones facet) and the
+ * `derived-status` invariant class in `validateContext`, so the derivation and
+ * the divergence detector cannot disagree.
+ */
+export function derivedRollupComplete(index, edges, roleDirection, rollupByKind, bucketOf, itemId, visiting = new Set()) {
+    const loc = index.byRefname.get(itemId);
+    if (loc === undefined)
+        return false;
+    const entry = rollupByKind.get(loc.block);
+    if (entry === undefined)
+        return bucketOf(loc.item) === "complete";
+    if (visiting.has(itemId))
+        return false;
+    visiting.add(itemId);
+    const dir = roleDirection.get(entry.membership_relation) ?? "as_child";
+    const memberIds = edges
+        .filter((e) => e.relation_type === entry.membership_relation && endpointKey(primaryEndpoint(e, dir)) === itemId)
+        .map((e) => endpointKey(counterEndpoint(e, dir)));
+    return (memberIds.length >= 1 &&
+        memberIds.every((memberId) => derivedRollupComplete(index, edges, roleDirection, rollupByKind, bucketOf, memberId, visiting)));
+}
 export function currentState(cwd) {
     // Tolerate any substrate-read failure (no .project, malformed config, etc.)
     // by collapsing to the empty state — this is a pure read surface.
@@ -620,14 +649,33 @@ export function currentState(cwd) {
             description: typeof loc.item.description === "string" ? loc.item.description : "",
         });
     }
-    // A target is complete when it resolves to a known item whose status buckets to
-    // "complete" — the SHARED status-vocab completeness notion (as TASK-065 left it,
-    // the same check the status-consistency invariant engine uses), kind-general and
-    // not a per-derivation literal.
-    const isCompleted = (itemId) => {
-        const loc = index.byRefname.get(itemId);
-        return loc !== undefined && bucket(loc.item) === "complete";
-    };
+    // Per-relation role_direction declarations (FGAP-113) — consulted by the
+    // rollup-aware completeness check below, the blocking partition, and the
+    // milestones rollup. Hoisted above isCompleted so all three read ONE map.
+    const roleDirection = new Map();
+    for (const rt of loadConfig(cwd)?.relation_types ?? []) {
+        if (rt.role_direction !== undefined)
+            roleDirection.set(rt.canonical_id, rt.role_direction);
+    }
+    // A target is complete when it resolves to a known item that IS complete under
+    // its kind's truth model (FEAT-011 criterion 1 — FGAP-116):
+    //   • a kind declared in `sd.rollups` is DERIVED-status — its stored status
+    //     field is canon-forbidden to author and may lag, so completeness is the
+    //     membership rollup itself (≥1 member, every member complete), recursively
+    //     rollup-aware for nested rollup kinds, with a visiting-set guard so a
+    //     membership cycle derives not-complete instead of recursing forever;
+    //   • every other kind keeps the SHARED status-vocab bucketing (as TASK-065
+    //     left it, the same check the status-consistency invariant engine uses),
+    //     byte-identical to the prior behavior.
+    // The milestones[] rollup below consumes THIS function for its reached
+    // verdict, so gate satisfaction and the reported milestone status agree by
+    // construction within a single read — the two can no longer split-brain. The
+    // derived-status invariant class evaluates the SAME shared helper, so
+    // validate-side divergence verdicts match the derivation too.
+    // Kind set + membership relation come from config (`sd.rollups` +
+    // role_direction); no kind / relation literal here (DEC-0025).
+    const rollupEntryByKind = new Map(sd.rollups.map((entry) => [entry.kind, entry]));
+    const isCompleted = (itemId) => derivedRollupComplete(index, edges, roleDirection, rollupEntryByKind, bucket, itemId);
     // Blocking-relation adjacency, driven by `sd.blocked_by.relation_types`. The
     // two stock relations use OPPOSITE endpoint directions, preserved exactly:
     //   • task_depends_on_task — DEPENDENCY direction: parents of edges whose CHILD
@@ -653,11 +701,6 @@ export function currentState(cwd) {
     // construction (no literal to extend). A blocked_by relation the config does
     // NOT register with a role_direction reads as the DEPENDENCY default.
     const blockedByRels = new Set(sd.blocked_by.relation_types);
-    const roleDirection = new Map();
-    for (const rt of loadConfig(cwd)?.relation_types ?? []) {
-        if (rt.role_direction !== undefined)
-            roleDirection.set(rt.canonical_id, rt.role_direction);
-    }
     const gateDirRels = new Set([...blockedByRels].filter((rt) => roleDirection.get(rt) === "as_child"));
     const depDirRels = new Set([...blockedByRels].filter((rt) => roleDirection.get(rt) !== "as_child"));
     const dependencyPredsOf = (itemId) => edges
@@ -785,8 +828,10 @@ export function currentState(cwd) {
                 .filter((e) => e.relation_type === entry.membership_relation && endpointKey(primaryEndpoint(e, dir)) === loc.id)
                 .map((e) => endpointKey(counterEndpoint(e, dir)));
             const phaseCount = memberIds.length;
-            const allComplete = memberIds.every((memberId) => isCompleted(memberId));
-            const reached = phaseCount >= 1 && allComplete;
+            // The reached verdict IS the rollup-aware isCompleted — the same function
+            // gate satisfaction consults — so the reported milestone status and the
+            // gates it releases cannot diverge within this read (FEAT-011 criterion 1).
+            const reached = isCompleted(loc.id);
             milestones.push({
                 id: loc.id,
                 status: reached ? entry.complete_status : entry.incomplete_status,
@@ -1408,7 +1453,7 @@ function relationKindsOverlap(rt) {
  *  - a bare append of a role-less relation, or of a role-bearing DISJOINT-kind
  *    relation (self-orienting via the kind gate), passes through unchanged.
  */
-function orientAppendInput(config, rel) {
+export function orientAppendInput(config, rel) {
     const hasRole = rel.primary !== undefined || rel.counter !== undefined;
     const hasRaw = rel.parent !== undefined || rel.child !== undefined;
     if (hasRole && hasRaw) {
@@ -1804,6 +1849,264 @@ function matchesWhere(item, where) {
             return false;
     return true;
 }
+/**
+ * Evaluate every config-declared invariant (requires-edge, status-consistency,
+ * derived-status) against the given substrate state, returning the issue set.
+ * The ONE evaluation path shared by `validateContext` (read-side sweep) and
+ * the ops-layer write-time gate (delta-scoped surfacing/refusal of newly-
+ * introduced violations) — the two consumers cannot classify differently.
+ * Unknown invariant classes are skipped (forward-compat).
+ */
+export function evaluateConfigInvariants(cwd, config, index, relations) {
+    const issues = [];
+    // ── Config-declared invariants (DEC-0025: vocabulary-neutral) ─────────
+    // Replaces the two previously-hardcoded invariants (completed-task-has-
+    // verification, decision-cites-forcing-artifact). Every block / status /
+    // relation_type / direction literal comes from config.invariants[] DATA;
+    // this loop contains no vocabulary literal. Each requires-edge invariant:
+    // items in `block` matching `where` must occupy `direction`'s endpoint on
+    // ≥1 edge whose relation_type ∈ relation_types — else a diagnostic.
+    for (const inv of config.invariants ?? []) {
+        if (inv.class !== "requires-edge")
+            continue; // forward-compat: skip unknown classes
+        const relTypeSet = new Set(inv.relation_types);
+        const satisfied = new Set();
+        for (const edge of relations) {
+            if (!relTypeSet.has(edge.relation_type))
+                continue;
+            satisfied.add(inv.direction === "as_parent" ? endpointKey(edge.parent) : endpointKey(edge.child));
+        }
+        for (const loc of index.byRefname.values()) {
+            const id = loc.id;
+            if (loc.block !== inv.block)
+                continue;
+            if (!matchesWhere(loc.item, inv.where))
+                continue;
+            if (satisfied.has(id))
+                continue;
+            issues.push({
+                severity: inv.severity ?? "error",
+                message: (inv.message ?? `Item '{id}' in block '{block}' violates invariant '${inv.id}'`)
+                    .replaceAll("{id}", id)
+                    .replaceAll("{block}", inv.block),
+                block: inv.block,
+                field: `${id}.${inv.id}`,
+                code: inv.id,
+            });
+        }
+    }
+    // ── status-consistency invariants (DEC-0040 / FGAP-073) ──────────────
+    // Cross-block status drift: for each item in inv.block (optionally gated
+    // by when_bucket on the item's own status bucket), inspect edges whose
+    // relation_type ∈ inv.relation_types and whose inv.direction endpoint is
+    // the item; the OTHER endpoint is the target. Violation when the target's
+    // status bucket differs from require_target_bucket, or equals
+    // forbid_target_bucket. Vocabulary-free — every literal comes from `inv`
+    // or the config-resolved status vocabulary; no block/status/relation
+    // string is hardcoded. vocab resolved once, outside the loop.
+    const vocab = resolveStatusVocabulary(cwd);
+    const bucketOf = (item) => vocab[String(item.status)] ?? "unknown";
+    for (const inv of config.invariants ?? []) {
+        if (inv.class !== "status-consistency")
+            continue;
+        const relSet = new Set(inv.relation_types);
+        for (const loc of index.byRefname.values()) {
+            const id = loc.id;
+            if (loc.block !== inv.block)
+                continue;
+            if (inv.when_bucket && bucketOf(loc.item) !== inv.when_bucket)
+                continue;
+            for (const edge of relations) {
+                if (!relSet.has(edge.relation_type))
+                    continue;
+                const selfIsParent = inv.direction === "as_parent";
+                if ((selfIsParent ? endpointKey(edge.parent) : endpointKey(edge.child)) !== id)
+                    continue;
+                const otherId = selfIsParent ? endpointKey(edge.child) : endpointKey(edge.parent);
+                const otherLoc = index.byRefname.get(otherId);
+                if (!otherLoc)
+                    continue; // dangling endpoint handled by edge-integrity above
+                const otherBucket = bucketOf(otherLoc.item);
+                const violateRequire = inv.require_target_bucket !== undefined && otherBucket !== inv.require_target_bucket;
+                const violateForbid = inv.forbid_target_bucket !== undefined && otherBucket === inv.forbid_target_bucket;
+                if (violateRequire || violateForbid) {
+                    issues.push({
+                        severity: inv.severity ?? "error",
+                        message: (inv.message ?? `Item '{id}' (block '{block}') status-consistency '${inv.id}'`)
+                            .replaceAll("{id}", id)
+                            .replaceAll("{block}", inv.block),
+                        block: inv.block,
+                        field: `${id}.${inv.id}`,
+                        code: inv.id,
+                    });
+                }
+            }
+        }
+    }
+    // ── derived-status invariants (FEAT-011 — FGAP-116) ───────────────────
+    // For a rollup-declared kind (state_derivation.rollups), each item's
+    // STORED status must equal its DERIVED membership-rollup status —
+    // divergence in EITHER direction (stored behind or ahead of the
+    // derivation) is reported. Completeness comes from the SAME shared
+    // helper currentState's gate satisfaction uses (derivedRollupComplete),
+    // so validate-side verdicts match the derivation by construction. A
+    // declaration naming a block with no matching rollups entry is inert
+    // (the invariant has nothing to derive against). Vocabulary-free: kind,
+    // membership relation, and the status strings all come from config.
+    {
+        const sdInv = resolveStateDerivation(cwd);
+        const declared = (config.invariants ?? []).filter((inv) => inv.class === "derived-status");
+        if (sdInv !== null && declared.length > 0) {
+            const rollupByKind = new Map(sdInv.rollups.map((r) => [r.kind, r]));
+            const roleDir = new Map();
+            for (const rt of config.relation_types ?? []) {
+                if (rt.role_direction !== undefined)
+                    roleDir.set(rt.canonical_id, rt.role_direction);
+            }
+            for (const inv of declared) {
+                const entry = rollupByKind.get(inv.block);
+                if (entry === undefined)
+                    continue;
+                for (const loc of index.byRefname.values()) {
+                    if (loc.block !== inv.block)
+                        continue;
+                    const derived = derivedRollupComplete(index, relations, roleDir, rollupByKind, bucketOf, loc.id)
+                        ? entry.complete_status
+                        : entry.incomplete_status;
+                    const stored = String(loc.item.status);
+                    if (stored === derived)
+                        continue;
+                    issues.push({
+                        severity: inv.severity ?? "warning",
+                        message: (inv.message ??
+                            `Item '{id}' (block '{block}') stored status '{stored}' diverges from its derived rollup status '{derived}' (derived-status '${inv.id}')`)
+                            .replaceAll("{id}", loc.id)
+                            .replaceAll("{block}", inv.block)
+                            .replaceAll("{stored}", stored)
+                            .replaceAll("{derived}", derived),
+                        block: inv.block,
+                        field: `${loc.id}.${inv.id}`,
+                        code: inv.id,
+                    });
+                }
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * Declared-baseline currency sweep (FEAT-011 criterion 6 — TASK-089), the ONE
+ * evaluation path shared by `validateContext` (flags) and `reconcileContext`
+ * (the complete-to-stale transition) — detector and repair cannot disagree.
+ * Field-driven and vocabulary-neutral: no block-name literals — any item
+ * carrying a `stale_conditions` array is condition-evaluable, and any
+ * array-of-object field entry carrying a `content_pin` beside a `path`/`file`
+ * is drift-checkable. Bare-string conditions are never machine-judged. Typed
+ * conditions are judged only on items whose status buckets `complete` (the
+ * transition's precondition); pin drift elsewhere degrades to the flag-only
+ * `anchor-drift` kind. Unstamped baselines (no `baseline_hash`/`baseline_sha`
+ * — e.g. the file/ref was unreadable at write) are never judged.
+ */
+export function evaluateStalenessCandidates(cwd, index) {
+    const out = [];
+    const ctxRoot = tryResolveContextDir(cwd);
+    if (ctxRoot === null)
+        return out;
+    const projectRoot = path.dirname(ctxRoot);
+    const idx = index ?? buildIdIndex(cwd);
+    const vocab = resolveStatusVocabulary(cwd);
+    const bucketOf = (item) => vocab[String(item.status)] ?? "unknown";
+    const substrateAbs = path.resolve(ctxRoot);
+    // Substrate-internal paths are living state, not groundable artifacts — the
+    // write choke never stamps them, and a hand-authored pin/baseline on one is
+    // never judged here (it would drift on every substrate write and flag forever).
+    const isSubstrateInternal = (rel) => {
+        const abs = path.resolve(projectRoot, rel);
+        return abs === substrateAbs || abs.startsWith(substrateAbs + path.sep);
+    };
+    const fileHashOrNull = (rel) => {
+        const abs = path.resolve(projectRoot, rel);
+        try {
+            if (!fs.statSync(abs).isFile())
+                return null;
+            return computeFileBytesHash(abs);
+        }
+        catch {
+            return null;
+        }
+    };
+    for (const loc of idx.byRefname.values()) {
+        const item = loc.item;
+        const hasConditions = Array.isArray(item.stale_conditions);
+        const completeBucket = bucketOf(item) === "complete";
+        const firedReasons = [];
+        if (hasConditions && completeBucket) {
+            for (const cond of item.stale_conditions) {
+                if (!cond || typeof cond !== "object" || Array.isArray(cond))
+                    continue; // bare strings stay human-only
+                const c = cond;
+                if (c.kind === "item-status" && typeof c.item === "string" && typeof c.bucket === "string") {
+                    const target = idx.byRefname.get(c.item);
+                    if (target !== undefined && bucketOf(target.item) === c.bucket) {
+                        firedReasons.push(`stale condition fired: item '${c.item}' bucketed '${c.bucket}'`);
+                    }
+                }
+                else if (c.kind === "file-changed" &&
+                    typeof c.path === "string" &&
+                    typeof c.baseline_hash === "string" &&
+                    !isSubstrateInternal(c.path)) {
+                    const now = fileHashOrNull(c.path);
+                    if (now === null) {
+                        firedReasons.push(`stale condition fired: file '${c.path}' is gone`);
+                    }
+                    else if (now !== c.baseline_hash) {
+                        firedReasons.push(`stale condition fired: file '${c.path}' changed from its baseline`);
+                    }
+                }
+                else if (c.kind === "revision-moved" && typeof c.ref === "string" && typeof c.baseline_sha === "string") {
+                    const now = resolveGitRefOrNull(projectRoot, c.ref);
+                    if (now !== null && now !== c.baseline_sha) {
+                        firedReasons.push(`stale condition fired: ref '${c.ref}' moved from '${c.baseline_sha.slice(0, 12)}'`);
+                    }
+                }
+            }
+        }
+        const driftReasons = [];
+        for (const [field, value] of Object.entries(item)) {
+            if (!Array.isArray(value))
+                continue;
+            for (const el of value) {
+                if (!el || typeof el !== "object" || Array.isArray(el))
+                    continue;
+                const rec = el;
+                if (typeof rec.content_pin !== "string")
+                    continue;
+                const rel = typeof rec.path === "string" ? rec.path : typeof rec.file === "string" ? rec.file : null;
+                if (rel === null || isSubstrateInternal(rel))
+                    continue;
+                const now = fileHashOrNull(rel);
+                if (now === null) {
+                    driftReasons.push(`pin drift: '${field}' entry file '${rel}' is gone`);
+                }
+                else if (now !== rec.content_pin) {
+                    driftReasons.push(`pin drift: '${field}' entry file '${rel}' changed since pinned`);
+                }
+            }
+        }
+        if (hasConditions && completeBucket && (firedReasons.length > 0 || driftReasons.length > 0)) {
+            out.push({
+                id: loc.id,
+                block: loc.block,
+                kind: "staleness-candidate",
+                reasons: [...firedReasons, ...driftReasons],
+            });
+        }
+        else if (driftReasons.length > 0) {
+            out.push({ id: loc.id, block: loc.block, kind: "anchor-drift", reasons: driftReasons });
+        }
+    }
+    return out;
+}
 /**
  * Validate cross-block referential integrity against the EDGE model
  * (DEC-0013: `relations.json` closure-table edges are THE reference surface).
@@ -2007,90 +2310,11 @@ export function validateContext(cwd) {
             /* validateRelations is best-effort for cycle detection; a throw here
                must not mask the authoritative edge-integrity issues collected above. */
         }
-        // ── Config-declared invariants (DEC-0025: vocabulary-neutral) ─────────
-        // Replaces the two previously-hardcoded invariants (completed-task-has-
-        // verification, decision-cites-forcing-artifact). Every block / status /
-        // relation_type / direction literal comes from config.invariants[] DATA;
-        // this loop contains no vocabulary literal. Each requires-edge invariant:
-        // items in `block` matching `where` must occupy `direction`'s endpoint on
-        // ≥1 edge whose relation_type ∈ relation_types — else a diagnostic.
-        for (const inv of config.invariants ?? []) {
-            if (inv.class !== "requires-edge")
-                continue; // forward-compat: skip unknown classes
-            const relTypeSet = new Set(inv.relation_types);
-            const satisfied = new Set();
-            for (const edge of relations) {
-                if (!relTypeSet.has(edge.relation_type))
-                    continue;
-                satisfied.add(inv.direction === "as_parent" ? endpointKey(edge.parent) : endpointKey(edge.child));
-            }
-            for (const loc of index.byRefname.values()) {
-                const id = loc.id;
-                if (loc.block !== inv.block)
-                    continue;
-                if (!matchesWhere(loc.item, inv.where))
-                    continue;
-                if (satisfied.has(id))
-                    continue;
-                issues.push({
-                    severity: inv.severity ?? "error",
-                    message: (inv.message ?? `Item '{id}' in block '{block}' violates invariant '${inv.id}'`)
-                        .replaceAll("{id}", id)
-                        .replaceAll("{block}", inv.block),
-                    block: inv.block,
-                    field: `${id}.${inv.id}`,
-                    code: inv.id,
-                });
-            }
-        }
-        // ── status-consistency invariants (DEC-0040 / FGAP-073) ──────────────
-        // Cross-block status drift: for each item in inv.block (optionally gated
-        // by when_bucket on the item's own status bucket), inspect edges whose
-        // relation_type ∈ inv.relation_types and whose inv.direction endpoint is
-        // the item; the OTHER endpoint is the target. Violation when the target's
-        // status bucket differs from require_target_bucket, or equals
-        // forbid_target_bucket. Vocabulary-free — every literal comes from `inv`
-        // or the config-resolved status vocabulary; no block/status/relation
-        // string is hardcoded. vocab resolved once, outside the loop.
-        const vocab = resolveStatusVocabulary(cwd);
-        const bucketOf = (item) => vocab[String(item.status)] ?? "unknown";
-        for (const inv of config.invariants ?? []) {
-            if (inv.class !== "status-consistency")
-                continue;
-            const relSet = new Set(inv.relation_types);
-            for (const loc of index.byRefname.values()) {
-                const id = loc.id;
-                if (loc.block !== inv.block)
-                    continue;
-                if (inv.when_bucket && bucketOf(loc.item) !== inv.when_bucket)
-                    continue;
-                for (const edge of relations) {
-                    if (!relSet.has(edge.relation_type))
-                        continue;
-                    const selfIsParent = inv.direction === "as_parent";
-                    if ((selfIsParent ? endpointKey(edge.parent) : endpointKey(edge.child)) !== id)
-                        continue;
-                    const otherId = selfIsParent ? endpointKey(edge.child) : endpointKey(edge.parent);
-                    const otherLoc = index.byRefname.get(otherId);
-                    if (!otherLoc)
-                        continue; // dangling endpoint handled by edge-integrity above
-                    const otherBucket = bucketOf(otherLoc.item);
-                    const violateRequire = inv.require_target_bucket !== undefined && otherBucket !== inv.require_target_bucket;
-                    const violateForbid = inv.forbid_target_bucket !== undefined && otherBucket === inv.forbid_target_bucket;
-                    if (violateRequire || violateForbid) {
-                        issues.push({
-                            severity: inv.severity ?? "error",
-                            message: (inv.message ?? `Item '{id}' (block '{block}') status-consistency '${inv.id}'`)
-                                .replaceAll("{id}", id)
-                                .replaceAll("{block}", inv.block),
-                            block: inv.block,
-                            field: `${id}.${inv.id}`,
-                            code: inv.id,
-                        });
-                    }
-                }
-            }
-        }
+        // ── Config-declared invariants — the three classes evaluate through the
+        // SHARED evaluateConfigInvariants helper (also consumed by the write-time
+        // gate at the ops layer), so validate-side and write-side verdicts are
+        // identical by construction (the TASK-062 edge-gate lift pattern).
+        issues.push(...evaluateConfigInvariants(cwd, config, index, relations));
     }
     // Cross-block status-vocabulary check (FGAP-025): an item status value absent
     // from the declared vocabulary silently buckets to "unknown" in currentState /
@@ -2116,6 +2340,22 @@ export function validateContext(cwd) {
             }
         }
     }
+    // ── Declared-baseline staleness sweep (FEAT-011 criterion 6 — TASK-089) ──
+    // Fired typed stale_conditions and drifted content pins, through the SAME
+    // evaluateStalenessCandidates helper context-reconcile's transition sweep
+    // uses (identical verdicts). Warning-only, and validate NEVER mutates — the
+    // complete-to-stale transition belongs to reconcile or a human.
+    for (const cand of evaluateStalenessCandidates(cwd, index)) {
+        issues.push({
+            severity: "warning",
+            message: cand.kind === "staleness-candidate"
+                ? `Item '${cand.id}' (block '${cand.block}') is a staleness candidate — ${cand.reasons.join("; ")}. Apply the complete-to-stale transition via context-reconcile or by hand; validate never mutates.`
+                : `Item '${cand.id}' (block '${cand.block}') has drifted anchors — ${cand.reasons.join("; ")}. Re-review the cited locations; the flag never rewrites.`,
+            block: cand.block,
+            field: `${cand.id}.${cand.kind}`,
+            code: cand.kind,
+        });
+    }
     // ── Nested id-bearing array warning (content-addressed substrate identity,
     // Cycle 9.2) ─────────────────────────────────────────────────────────────
     // Schema-level, independent of block DATA + config: enumerate the active
@@ -2270,13 +2510,19 @@ function blockItemIdForInstancePath(cwd, blockName, instancePath) {
     }
 }
 /**
- * Gate task completion on verification. Reads the verification block to confirm
- * a passing verification entry exists, asserts a `verification_verifies_item`
- * closure-table edge links that verification (parent) to this task (child), then
- * atomically updates the task status to "completed". The edge IS the linkage —
- * no `verification` field is embedded on the task (the verification → task
+ * Verification-gated task completion — the closure transition ATOM. Reads the
+ * verification block to confirm a passing verification entry exists, FILES the
+ * `verification_verifies_item` closure-table edge itself (verification as
+ * parent, task as child; idempotent — an exact pre-existing edge is a no-op via
+ * appendRelation's dedup), then updates the task status to "completed", all in
+ * one call. Filing the edge here rather than requiring a prior append-relation
+ * is load-bearing: an error-severity invariant pair (passed-verification-
+ * verifies-completed-task / completed-task-has-verification) forbids BOTH
+ * intermediate resting states, so no two-op sequence can thread the write-time
+ * gate — only the joint end-state is legal. The edge IS the linkage — no
+ * `verification` field is embedded on the task (the verification → task
  * `verification.target`/`target_type` fields were removed from the verification
- * schema in favor of the edge; this gate reads the edge, not the removed fields).
+ * schema in favor of the edge).
  */
 export function completeTask(cwd, taskId, verificationId, ctx) {
     // 1. Read and validate verification entry
@@ -2315,14 +2561,14 @@ export function completeTask(cwd, taskId, verificationId, ctx) {
     if (currentStatus === "cancelled") {
         throw new Error(`Task '${taskId}' is already cancelled`);
     }
-    // 3. Assert the verification_verifies_item edge: verification (parent) →
-    // task (child). The closure-table edge — not a verification field — is the
-    // canonical linkage. Inbound edges point AT the task; compare the parent
-    // endpoint via endpointKey (the codebase's endpoint-comparison idiom).
-    const verifiesEdge = findReferencesInRepo(cwd, taskId, "inbound").find((e) => e.relation_type === "verification_verifies_item" && endpointKey(e.parent) === verificationId);
-    if (!verifiesEdge) {
-        throw new Error(`verification '${verificationId}' does not verify task '${taskId}' — no verification_verifies_item edge; file the link (append-relation parent=${verificationId} child=${taskId} relation_type=verification_verifies_item) before completing`);
-    }
+    // 3. File the verification_verifies_item edge: verification (parent) →
+    // task (child), through the same porcelain a standalone append-relation
+    // uses (registered-type + endpoint-kind validation, atomic write,
+    // exact-duplicate no-op). The closure-table edge — not a verification
+    // field — is the canonical linkage; filing it in the SAME call that flips
+    // status makes closure a single transition atom under the write-time
+    // invariant gate.
+    const { appended } = appendRelationByRef(cwd, { parent: verificationId, child: taskId, relation_type: "verification_verifies_item" }, ctx);
     // 4. Update task status. The edge is the linkage — no `verification` field is
     // embedded (a populated additionalProperties:false tasks schema would reject it).
     updateItemInBlock(cwd, "tasks", "tasks", (t) => t.id === taskId, { status: "completed" }, ctx);
@@ -2331,6 +2577,7 @@ export function completeTask(cwd, taskId, verificationId, ctx) {
         verificationId,
         verificationStatus: String(verification.status),
         previousStatus: currentStatus,
+        edgeAppended: appended,
     };
 }
 //# sourceMappingURL=context-sdk.js.map