@dzhechkov/harness-core 0.3.149 → 0.4.1

package/dist/recall-domain-boost.js

@@ -0,0 +1,158 @@
+/**
+ * Domain-aware recall re-ranking — the pure half of `dz recall --domain <name>`.
+ *
+ * WHY THIS EXISTS. `dz teach --domain <name>` has always recorded a domain, and
+ * `dz recall --all --stats` prints the per-domain histogram — but the RANKING path
+ * (`recallHybrid`: lexical FTS5 + optional vector leg merged by RRF) never looked at
+ * the field. So a store shared by different KINDS of work returns them interleaved:
+ * medical-research lessons dilute a coding recall and vice versa, and the dilution
+ * gets worse as either side grows.
+ *
+ * WHY A BOOST AND NOT A FILTER. Cross-pollination here is real, not theoretical:
+ * "a reviewer's evidence needs the same execute-don't-describe discipline as your
+ * own claims" was learned reviewing code and applies verbatim to medical sources;
+ * the medical report's core insight ("was the source ever opened?") is the same
+ * principle as our claim-check. A hard filter would cut exactly the transfers that
+ * make one store worth more than two. So: matching-domain hits move UP, foreign
+ * ones stay in the list.
+ *
+ * THE PROMISE, NARROWLY: this reorders. It NEVER drops a hit, never invents one,
+ * and never changes how many are returned. If the boost is wrong, the cost is
+ * ordering; it can't hide a lesson from you.
+ */
+/** How many places a same-domain lesson may climb. STATED AS POSITIONS, not as a
+ * score multiplier: "moves up at most two places" is a sentence a reader can check
+ * against the output, while "index × 0.55" is an opaque constant whose behaviour
+ * changes with position (it could not lift index 2 past index 1 at all, but did
+ * lift index 3 past index 2 — an accident, not a design). A bounded lift keeps
+ * lexical relevance dominant: a domain tag is a hint about relevance, not evidence
+ * of it, so it breaks near-ties instead of overruling the ranking. */
+export const DOMAIN_LIFT_EXACT = 2;
+/** A prefix/suffix relative (`health-research` against `health`) climbs less. */
+export const DOMAIN_LIFT_RELATED = 1;
+/** Normalize a domain tag for comparison: case- and separator-insensitive, so
+ * `Health-Research`, `health_research` and `health research` are one domain. */
+export function normalizeDomain(domain) {
+    return String(domain ?? '')
+        .toLowerCase()
+        .replace(/[\s_]+/g, '-')
+        // COLLAPSE hyphen runs. `Health - Research` became `health---research`, which the
+        // doc comment above calls one domain with `health-research` and the code then
+        // treated as unrelated. Only ordering is at stake here — the export hold-out has its
+        // own stricter key — but a comment that describes behaviour the code lacks is the
+        // same defect wherever it sits.
+        .replace(/-{2,}/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/** How a hit's domain relates to the requested one. `related` covers the common
+ * hierarchy shapes (`health` ↔ `health-research`) without a taxonomy: a taxonomy
+ * nobody maintains drifts, and a wrong taxonomy is worse than none. */
+export function domainMatch(hitDomain, wanted) {
+    const a = normalizeDomain(hitDomain);
+    const b = normalizeDomain(wanted);
+    if (a === '' || b === '')
+        return 'none';
+    if (a === b)
+        return 'exact';
+    if (a.startsWith(`${b}-`) || b.startsWith(`${a}-`))
+        return 'related';
+    return 'none';
+}
+/**
+ * Re-rank hits so same-domain lessons surface first, keeping every hit.
+ *
+ * Effective position = `index - lift`. The original relevance order dominates; the
+ * domain only breaks near-ties, and the lift is BOUNDED so a tail match can never
+ * teleport to the top. Ties keep the incoming order (stable sort), so the function
+ * is deterministic — the same input always yields the same output, which is what
+ * makes it testable at all.
+ */
+export function applyDomainBoost(hits, wanted) {
+    const target = normalizeDomain(wanted);
+    if (target === '' || hits.length === 0) {
+        return { hits, exact: 0, related: 0, moved: 0, noMatches: true };
+    }
+    let exact = 0;
+    let related = 0;
+    const scored = hits.map((hit, index) => {
+        const match = domainMatch(hit.pattern.domain, target);
+        if (match === 'exact')
+            exact += 1;
+        else if (match === 'related')
+            related += 1;
+        const lift = match === 'exact' ? DOMAIN_LIFT_EXACT : match === 'related' ? DOMAIN_LIFT_RELATED : 0;
+        return { hit, index, lift, effective: index - lift };
+    });
+    // Tie-break: at equal effective position the LIFTED hit goes first, then the
+    // original order. Without this the foreign hit it landed level with won the tie
+    // by having the lower original index, so a lift of N moved the hit only N-1
+    // places — the code quietly delivered less than the constant promised. A test
+    // asserting the documented bound caught it; the fix is here, not in the test.
+    scored.sort((a, b) => (a.effective - b.effective) || (b.lift - a.lift) || (a.index - b.index));
+    const reordered = scored.map((s) => s.hit);
+    let moved = 0;
+    scored.forEach((s, newIndex) => { if (s.index !== newIndex)
+        moved += 1; });
+    return { hits: reordered, exact, related, moved, noMatches: exact === 0 && related === 0 };
+}
+/**
+ * How many hits the CUT hid that an unboosted recall would have shown.
+ *
+ * WHY THIS EXISTS. `applyDomainBoost` never drops a hit — but the CLI still cuts the
+ * list at `--limit`, and a promotion INTO the top N necessarily pushes something out
+ * of it. Cross-model review found the resulting sentence to be a lie by omission: the
+ * note said "foreign-domain lessons kept" while `foreign-B`, visible without
+ * `--domain`, had vanished from the printed output. Both statements were true of
+ * different lists, which is exactly how an honest tool ends up misleading its reader.
+ *
+ * The fix is not to stop promoting — that would be the filter we refused to build. It
+ * is to COUNT what fell past the cut and say so, because the reader can act on that
+ * (raise `--limit`) only if they know it happened.
+ *
+ * Compares by identity: both lists hold the same hit objects.
+ */
+export function countDisplacedByCut(original, boosted, limit) {
+    if (!Number.isFinite(limit) || limit <= 0)
+        return 0;
+    const shownAfter = new Set(boosted.slice(0, limit));
+    let displaced = 0;
+    for (const hit of original.slice(0, limit)) {
+        if (!shownAfter.has(hit))
+            displaced += 1;
+    }
+    return displaced;
+}
+/** The line that reports the cut. Empty when nothing was displaced, so the common
+ * case stays quiet. */
+export function renderDomainCutNote(displaced, limit) {
+    if (displaced <= 0)
+        return '';
+    const plural = displaced === 1 ? 'lesson' : 'lessons';
+    return `  ${displaced} lower-ranked ${plural} fell past the --limit ${limit} cut to make room — raise --limit to see them (the boost promotes; the cut is what hides)`;
+}
+/** One honest line about what the boost did — including the case where it did
+ * nothing, which a silent reorder would hide.
+ *
+ * The two tail phrases below are a WIRE CONTRACT: `learning_bridge.py` in the
+ * `goap-research-ed25519` skill detects whether the installed `dz` supports
+ * `--domain` by looking for them, because an older CLI ignores the flag and exits 0
+ * (so an exit code cannot tell the versions apart). A test pins both strings — if you
+ * reword them, update the bridge in the same change or you switch that loop into
+ * permanent degraded mode without a single test turning red. */
+export function renderDomainBoostNote(result, wanted) {
+    if (result.noMatches) {
+        return `  domain "${wanted}": no lesson in this result carries it — order unchanged, nothing was hidden`;
+    }
+    const parts = [`${result.exact} exact`];
+    if (result.related > 0)
+        parts.push(`${result.related} related`);
+    const effect = result.moved === 0
+        ? 'the order was already correct — nothing moved'
+        : `${result.moved} changed position`;
+    // The counts describe the CANDIDATES the boost ranked, which is a longer list than
+    // the one printed (the caller over-fetches, then cuts at --limit). Saying "3 changed
+    // position" above two printed lines reads as an arithmetic error unless the note
+    // names the list it is talking about — so it does.
+    return `  domain "${wanted}": among ${result.hits.length} candidate(s) — ${parts.join(', ')} match(es), ${effect}; foreign-domain lessons kept (a boost, not a filter)`;
+}
+//# sourceMappingURL=recall-domain-boost.js.map

package/dist/recall-domain-boost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall-domain-boost.js","sourceRoot":"","sources":["../src/recall-domain-boost.ts"],"names":[],"mappings":"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"}

package/dist/store-lock.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Cross-process exclusive lock for the JSON pattern store — built on `proper-lockfile`.
+ *
+ * WHY THIS EXISTS. The JSON backend writes ATOMICALLY (temp file + rename), so no reader
+ * ever sees a torn file. That is a different property from the one needed here. A teach is
+ * a read-modify-write: load every record, add one, write them all back. Two teaches that
+ * overlap both load the same N records, and each writes back N+1 — the second rename wins
+ * and the first lesson is gone. BOTH processes report success, so a lost lesson is silent.
+ * Atomicity prevents corruption; only mutual exclusion prevents a lost update.
+ *
+ * The SQLite backend has its own transaction locking and does not go through here.
+ *
+ * WHY `proper-lockfile` AND NOT THE PREVIOUS HAND-ROLLED LOCK. An independent review
+ * (Codex gpt-5.6-sol) graded the hand-rolled `wx`-file lock F. Its findings, and how this
+ * implementation answers them:
+ *
+ * 1. *Stale-break deleted a successor's live lock* — the old code `rmSync`'d a lock file
+ *    by PATHNAME after deciding it was stale, so two waiters breaking the same stale lock
+ *    could delete each other's freshly created locks in a cascade. `proper-lockfile`
+ *    acquires with an atomic `mkdir`, and a waiter that breaks a stale lock retries with
+ *    staleness DISABLED, so per acquisition attempt it can remove at most the one lock it
+ *    observed as stale — never a successor's fresh lock in a loop. The residual
+ *    microsecond window (stat-stale → holder replaced → rmdir) is closed by DETECTION:
+ *    every holder heartbeats its lock's mtime and treats a foreign mtime as ECOMPROMISED,
+ *    which {@link withStoreLock} converts into a loud error instead of a silent lost
+ *    update. (This is also the model the RVF spec uses for `.rvf` writer locks:
+ *    single-writer advisory lock file + ownership verification before unlink —
+ *    `ruvector/docs/research/rvf/spec/09-concurrency-versioning.md`.)
+ *
+ * 2. *"Unparseable means dead" deleted live locks* — there is no lock BODY to parse any
+ *    more. The lock is a directory; its existence is the lock, so the empty-file /
+ *    half-written-file misclassification class is structurally gone.
+ *
+ * 3. *Age was mistaken for liveness* — staleness is now filesystem mtime plus a HEARTBEAT:
+ *    the holder refreshes the lock's mtime on a timer (every `staleMs / 2`, ≥ 1s), so a
+ *    holder slower than `staleMs` is never broken while alive, and a crashed holder's lock
+ *    stops being refreshed and is reclaimed after `staleMs`. Nothing trusts a
+ *    self-reported timestamp, so a forged far-future `ts` can no longer block forever.
+ *    NOTE: the heartbeat runs on the event loop, so a SYNCHRONOUS critical section longer
+ *    than `staleMs` could still be observed as stale — keep {@link withStoreLockSync}
+ *    bodies short (they are: single-file JSON rewrites) or raise `staleMs`.
+ *
+ * 4. *The timeout was not an acquisition deadline* — the retry loops below compute a real
+ *    deadline (`now + timeoutMs`), re-check it after EVERY sleep, clamp the last sleep to
+ *    the remaining budget, and never acquire after the deadline has passed.
+ *
+ * 5. *The lock was not store-wide* — every JSON-tier writer in `patterns.ts` now runs
+ *    under this lock (see the writer inventory in that module).
+ *
+ * On timeout this THROWS ({@link StoreLockTimeoutError}) rather than proceeding unlocked.
+ * Proceeding would restore exactly the silent lost-update this exists to stop, and a teach
+ * that failed loudly can be retried — one that vanished cannot.
+ *
+ * MIGRATION: the pre-`proper-lockfile` implementation left a regular FILE at
+ * `.dz/store.lock`; the library's lock is a DIRECTORY at the same path. A leftover file
+ * from a crashed old process is removed only once it is older than `staleMs` — a fresh
+ * one is honoured as held, same as any other lock.
+ */
+/** A lock whose HEARTBEAT stopped this long ago is presumed abandoned (crashed holder). */
+export declare const STALE_LOCK_MS = 30000;
+/** Give up waiting after this long and say so, rather than blocking a CLI forever. */
+export declare const LOCK_TIMEOUT_MS = 10000;
+/** Path of the lock guarding a project's pattern store (a DIRECTORY when held). */
+export declare function storeLockPath(projectRoot: string): string;
+/** Options accepted by {@link withStoreLock} / {@link withStoreLockSync}. */
+export interface StoreLockOptions {
+    /** Heartbeat-stopped threshold before a lock is presumed abandoned (min 2000, lib-enforced). */
+    readonly staleMs?: number;
+    /** Acquisition deadline. Also overridable via `DZ_STORE_LOCK_TIMEOUT_MS` (tests/ops). */
+    readonly timeoutMs?: number;
+    /** Delay between acquisition attempts while the lock is held by someone else. */
+    readonly pollMs?: number;
+}
+/** Acquisition gave up at the deadline. Nothing was written; the operation can be retried. */
+export declare class StoreLockTimeoutError extends Error {
+    readonly code = "ELOCKTIMEOUT";
+    constructor(lockPath: string, waitedMs: number);
+}
+/**
+ * The holder detected that its lock was broken out from under it (ECOMPROMISED) — e.g. a
+ * waiter reclaimed the lock after this process was suspended past `staleMs`. The critical
+ * section DID run, but it may have raced another writer, so the operation must be treated
+ * as failed and retried (store writes are idempotent by deterministic record id).
+ */
+export declare class StoreLockCompromisedError extends Error {
+    readonly code = "ECOMPROMISED";
+    constructor(lockPath: string, cause: Error);
+}
+/**
+ * Run `fn` while holding the store lock, releasing it however `fn` ends.
+ *
+ * Throws {@link StoreLockTimeoutError} when the lock cannot be acquired by the deadline
+ * (nothing has run), and {@link StoreLockCompromisedError} when the lock was broken while
+ * `fn` ran (it DID run, but may have raced — retry; store writes are idempotent).
+ */
+export declare function withStoreLock<T>(projectRoot: string, fn: () => Promise<T>, opts?: StoreLockOptions): Promise<T>;
+/**
+ * Synchronous {@link withStoreLock}, for the store's synchronous writers (prune / remove).
+ * Same deadline and failure semantics. The heartbeat cannot fire while `fn` blocks the
+ * event loop, so keep bodies well under `staleMs` (they are: single-file JSON rewrites).
+ *
+ * CAVEAT: do not contend with an ASYNC `withStoreLock` holder in the SAME process — the
+ * sync wait blocks the event loop that would release that holder, so the wait can only
+ * end in the loud {@link StoreLockTimeoutError} (never a lost update). Cross-process
+ * contention, the case this lock exists for, is unaffected.
+ */
+export declare function withStoreLockSync<T>(projectRoot: string, fn: () => T, opts?: StoreLockOptions): T;
+//# sourceMappingURL=store-lock.d.ts.map

package/dist/store-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-lock.d.ts","sourceRoot":"","sources":["../src/store-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAMH,2FAA2F;AAC3F,eAAO,MAAM,aAAa,QAAS,CAAC;AACpC,sFAAsF;AACtF,eAAO,MAAM,eAAe,QAAS,CAAC;AAKtC,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,6EAA6E;AAC7E,MAAM,WAAW,gBAAgB;IAC/B,gGAAgG;IAChG,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,yFAAyF;IACzF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,iFAAiF;IACjF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,8FAA8F;AAC9F,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,kBAAkB;gBACnB,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAO/C;AAED;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,IAAI,kBAAkB;gBACnB,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK;CAI3C;AA0ED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,CAAC,CAAC,CAuBZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,CAAC,EACX,IAAI,GAAE,gBAAqB,GAC1B,CAAC,CAuBH"}

package/dist/store-lock.js

@@ -0,0 +1,231 @@
+/**
+ * Cross-process exclusive lock for the JSON pattern store — built on `proper-lockfile`.
+ *
+ * WHY THIS EXISTS. The JSON backend writes ATOMICALLY (temp file + rename), so no reader
+ * ever sees a torn file. That is a different property from the one needed here. A teach is
+ * a read-modify-write: load every record, add one, write them all back. Two teaches that
+ * overlap both load the same N records, and each writes back N+1 — the second rename wins
+ * and the first lesson is gone. BOTH processes report success, so a lost lesson is silent.
+ * Atomicity prevents corruption; only mutual exclusion prevents a lost update.
+ *
+ * The SQLite backend has its own transaction locking and does not go through here.
+ *
+ * WHY `proper-lockfile` AND NOT THE PREVIOUS HAND-ROLLED LOCK. An independent review
+ * (Codex gpt-5.6-sol) graded the hand-rolled `wx`-file lock F. Its findings, and how this
+ * implementation answers them:
+ *
+ * 1. *Stale-break deleted a successor's live lock* — the old code `rmSync`'d a lock file
+ *    by PATHNAME after deciding it was stale, so two waiters breaking the same stale lock
+ *    could delete each other's freshly created locks in a cascade. `proper-lockfile`
+ *    acquires with an atomic `mkdir`, and a waiter that breaks a stale lock retries with
+ *    staleness DISABLED, so per acquisition attempt it can remove at most the one lock it
+ *    observed as stale — never a successor's fresh lock in a loop. The residual
+ *    microsecond window (stat-stale → holder replaced → rmdir) is closed by DETECTION:
+ *    every holder heartbeats its lock's mtime and treats a foreign mtime as ECOMPROMISED,
+ *    which {@link withStoreLock} converts into a loud error instead of a silent lost
+ *    update. (This is also the model the RVF spec uses for `.rvf` writer locks:
+ *    single-writer advisory lock file + ownership verification before unlink —
+ *    `ruvector/docs/research/rvf/spec/09-concurrency-versioning.md`.)
+ *
+ * 2. *"Unparseable means dead" deleted live locks* — there is no lock BODY to parse any
+ *    more. The lock is a directory; its existence is the lock, so the empty-file /
+ *    half-written-file misclassification class is structurally gone.
+ *
+ * 3. *Age was mistaken for liveness* — staleness is now filesystem mtime plus a HEARTBEAT:
+ *    the holder refreshes the lock's mtime on a timer (every `staleMs / 2`, ≥ 1s), so a
+ *    holder slower than `staleMs` is never broken while alive, and a crashed holder's lock
+ *    stops being refreshed and is reclaimed after `staleMs`. Nothing trusts a
+ *    self-reported timestamp, so a forged far-future `ts` can no longer block forever.
+ *    NOTE: the heartbeat runs on the event loop, so a SYNCHRONOUS critical section longer
+ *    than `staleMs` could still be observed as stale — keep {@link withStoreLockSync}
+ *    bodies short (they are: single-file JSON rewrites) or raise `staleMs`.
+ *
+ * 4. *The timeout was not an acquisition deadline* — the retry loops below compute a real
+ *    deadline (`now + timeoutMs`), re-check it after EVERY sleep, clamp the last sleep to
+ *    the remaining budget, and never acquire after the deadline has passed.
+ *
+ * 5. *The lock was not store-wide* — every JSON-tier writer in `patterns.ts` now runs
+ *    under this lock (see the writer inventory in that module).
+ *
+ * On timeout this THROWS ({@link StoreLockTimeoutError}) rather than proceeding unlocked.
+ * Proceeding would restore exactly the silent lost-update this exists to stop, and a teach
+ * that failed loudly can be retried — one that vanished cannot.
+ *
+ * MIGRATION: the pre-`proper-lockfile` implementation left a regular FILE at
+ * `.dz/store.lock`; the library's lock is a DIRECTORY at the same path. A leftover file
+ * from a crashed old process is removed only once it is older than `staleMs` — a fresh
+ * one is honoured as held, same as any other lock.
+ */
+import { mkdirSync, rmSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { lockSync } from 'proper-lockfile';
+/** A lock whose HEARTBEAT stopped this long ago is presumed abandoned (crashed holder). */
+export const STALE_LOCK_MS = 30_000;
+/** Give up waiting after this long and say so, rather than blocking a CLI forever. */
+export const LOCK_TIMEOUT_MS = 10_000;
+/** `proper-lockfile` silently clamps `stale` up to this minimum. */
+const MIN_STALE_MS = 2_000;
+/** Path of the lock guarding a project's pattern store (a DIRECTORY when held). */
+export function storeLockPath(projectRoot) {
+    return join(projectRoot, '.dz', 'store.lock');
+}
+/** Acquisition gave up at the deadline. Nothing was written; the operation can be retried. */
+export class StoreLockTimeoutError extends Error {
+    code = 'ELOCKTIMEOUT';
+    constructor(lockPath, waitedMs) {
+        super(`the pattern store at ${lockPath} stayed locked for ${waitedMs}ms — ` +
+            'another dz process is still writing. Nothing was written; retry.');
+        this.name = 'StoreLockTimeoutError';
+    }
+}
+/**
+ * The holder detected that its lock was broken out from under it (ECOMPROMISED) — e.g. a
+ * waiter reclaimed the lock after this process was suspended past `staleMs`. The critical
+ * section DID run, but it may have raced another writer, so the operation must be treated
+ * as failed and retried (store writes are idempotent by deterministic record id).
+ */
+export class StoreLockCompromisedError extends Error {
+    code = 'ECOMPROMISED';
+    constructor(lockPath, cause) {
+        super(`the pattern store lock at ${lockPath} was compromised while held (${cause.message}) — retry the operation.`);
+        this.name = 'StoreLockCompromisedError';
+    }
+}
+const defaultTimeoutMs = () => {
+    const env = Number(process.env['DZ_STORE_LOCK_TIMEOUT_MS']);
+    return Number.isFinite(env) && env > 0 ? env : LOCK_TIMEOUT_MS;
+};
+const sleep = (ms) => new Promise((r) => { setTimeout(r, ms); });
+/** Synchronous sleep without spinning (Atomics.wait on a throwaway buffer). */
+const sleepSync = (ms) => {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+};
+/**
+ * Remove a REGULAR-FILE lock left by the pre-`proper-lockfile` implementation, but only
+ * once it is stale — a fresh legacy lock belongs to a live old-version process and is
+ * honoured. (Never deletes a directory: that is a live library lock.)
+ */
+function clearStaleLegacyLockFile(lockPath, staleMs) {
+    try {
+        const st = statSync(lockPath);
+        if (st.isFile() && Date.now() - st.mtimeMs >= staleMs)
+            rmSync(lockPath, { force: true });
+    }
+    catch { /* gone already — fine */ }
+}
+/**
+ * One acquisition attempt. Returns `'held'` when someone else holds the lock (retry later);
+ * throws on real I/O errors. `mkdir`-based, so creation is atomic; staleness is heartbeat
+ * mtime, and the library's own stale-break retries with staleness disabled (see header §1).
+ */
+function tryAcquire(projectRoot, staleMs, onCompromised) {
+    const lockPath = storeLockPath(projectRoot);
+    try {
+        const release = lockSync(resolve(projectRoot, '.dz', 'store'), {
+            lockfilePath: lockPath,
+            stale: staleMs,
+            realpath: false, // the guarded resource is a concept, not an existing file
+            onCompromised,
+        });
+        return {
+            release: () => {
+                try {
+                    release();
+                }
+                catch { /* ERELEASED after a compromise — the lock is no longer ours to remove */ }
+            },
+            compromise: () => undefined,
+        };
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ELOCKED')
+            return 'held';
+        if (code === 'ENOTDIR') {
+            // A stale legacy FILE lock: the library can only rmdir directories. Clear it (only
+            // if actually stale) and report 'held' so the caller's loop retries.
+            clearStaleLegacyLockFile(lockPath, staleMs);
+            return 'held';
+        }
+        throw err;
+    }
+}
+function resolveOpts(opts) {
+    return {
+        staleMs: Math.max(opts.staleMs ?? STALE_LOCK_MS, MIN_STALE_MS),
+        timeoutMs: opts.timeoutMs ?? defaultTimeoutMs(),
+        pollMs: opts.pollMs ?? 25,
+    };
+}
+/**
+ * Run `fn` while holding the store lock, releasing it however `fn` ends.
+ *
+ * Throws {@link StoreLockTimeoutError} when the lock cannot be acquired by the deadline
+ * (nothing has run), and {@link StoreLockCompromisedError} when the lock was broken while
+ * `fn` ran (it DID run, but may have raced — retry; store writes are idempotent).
+ */
+export async function withStoreLock(projectRoot, fn, opts = {}) {
+    const { staleMs, timeoutMs, pollMs } = resolveOpts(opts);
+    mkdirSync(join(projectRoot, '.dz'), { recursive: true });
+    const started = Date.now();
+    const deadline = started + timeoutMs;
+    let compromised;
+    const onCompromised = (e) => { compromised = e; };
+    for (;;) {
+        const got = tryAcquire(projectRoot, staleMs, onCompromised);
+        if (got !== 'held') {
+            let result;
+            try {
+                result = await fn();
+            }
+            finally {
+                got.release();
+            }
+            if (compromised !== undefined)
+                throw new StoreLockCompromisedError(storeLockPath(projectRoot), compromised);
+            return result;
+        }
+        const now = Date.now();
+        if (now >= deadline)
+            throw new StoreLockTimeoutError(storeLockPath(projectRoot), now - started);
+        await sleep(Math.min(pollMs, deadline - now));
+    }
+}
+/**
+ * Synchronous {@link withStoreLock}, for the store's synchronous writers (prune / remove).
+ * Same deadline and failure semantics. The heartbeat cannot fire while `fn` blocks the
+ * event loop, so keep bodies well under `staleMs` (they are: single-file JSON rewrites).
+ *
+ * CAVEAT: do not contend with an ASYNC `withStoreLock` holder in the SAME process — the
+ * sync wait blocks the event loop that would release that holder, so the wait can only
+ * end in the loud {@link StoreLockTimeoutError} (never a lost update). Cross-process
+ * contention, the case this lock exists for, is unaffected.
+ */
+export function withStoreLockSync(projectRoot, fn, opts = {}) {
+    const { staleMs, timeoutMs, pollMs } = resolveOpts(opts);
+    mkdirSync(join(projectRoot, '.dz'), { recursive: true });
+    const started = Date.now();
+    const deadline = started + timeoutMs;
+    let compromised;
+    const onCompromised = (e) => { compromised = e; };
+    for (;;) {
+        const got = tryAcquire(projectRoot, staleMs, onCompromised);
+        if (got !== 'held') {
+            let result;
+            try {
+                result = fn();
+            }
+            finally {
+                got.release();
+            }
+            if (compromised !== undefined)
+                throw new StoreLockCompromisedError(storeLockPath(projectRoot), compromised);
+            return result;
+        }
+        const now = Date.now();
+        if (now >= deadline)
+            throw new StoreLockTimeoutError(storeLockPath(projectRoot), now - started);
+        sleepSync(Math.min(pollMs, deadline - now));
+    }
+}
+//# sourceMappingURL=store-lock.js.map

package/dist/store-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-lock.js","sourceRoot":"","sources":["../src/store-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE3C,2FAA2F;AAC3F,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC;AACpC,sFAAsF;AACtF,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC;AAEtC,oEAAoE;AACpE,MAAM,YAAY,GAAG,KAAK,CAAC;AAE3B,mFAAmF;AACnF,MAAM,UAAU,aAAa,CAAC,WAAmB;IAC/C,OAAO,IAAI,CAAC,WAAW,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;AAChD,CAAC;AAYD,8FAA8F;AAC9F,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IACrC,IAAI,GAAG,cAAc,CAAC;IAC/B,YAAY,QAAgB,EAAE,QAAgB;QAC5C,KAAK,CACH,wBAAwB,QAAQ,sBAAsB,QAAQ,OAAO;YACrE,kEAAkE,CACnE,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IACzC,IAAI,GAAG,cAAc,CAAC;IAC/B,YAAY,QAAgB,EAAE,KAAY;QACxC,KAAK,CAAC,6BAA6B,QAAQ,gCAAgC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;QACpH,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;IAC1C,CAAC;CACF;AAED,MAAM,gBAAgB,GAAG,GAAW,EAAE;IACpC,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC,CAAC;IAC5D,OAAO,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,eAAe,CAAC;AACjE,CAAC,CAAC;AAEF,MAAM,KAAK,GAAG,CAAC,EAAU,EAAiB,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAExF,+EAA+E;AAC/E,MAAM,SAAS,GAAG,CAAC,EAAU,EAAQ,EAAE;IACrC,OAAO,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;AACnE,CAAC,CAAC;AAEF;;;;GAIG;AACH,SAAS,wBAAwB,CAAC,QAAgB,EAAE,OAAe;IACjE,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAC9B,IAAI,EAAE,CAAC,MAAM,EAAE,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,OAAO,IAAI,OAAO;YAAE,MAAM,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3F,CAAC;IAAC,MAAM,CAAC,CAAC,yBAAyB,CAAC,CAAC;AACvC,CAAC;AAOD;;;;GAIG;AACH,SAAS,UAAU,CAAC,WAAmB,EAAE,OAAe,EAAE,aAAiC;IACzF,MAAM,QAAQ,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;IAC5C,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,WAAW,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE;YAC7D,YAAY,EAAE,QAAQ;YACtB,KAAK,EAAE,OAAO;YACd,QAAQ,EAAE,KAAK,EAAE,0DAA0D;YAC3E,aAAa;SACd,CAAC,CAAC;QACH,OAAO;YACL,OAAO,EAAE,GAAG,EAAE;gBACZ,IAAI,CAAC;oBACH,OAAO,EAAE,CAAC;gBACZ,CAAC;gBAAC,MAAM,CAAC,CAAC,yEAAyE,CAAC,CAAC;YACvF,CAAC;YACD,UAAU,EAAE,GAAG,EAAE,CAAC,SAAS;SAC5B,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;QACjD,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC;QACtC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,mFAAmF;YACnF,qEAAqE;YACrE,wBAAwB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAC5C,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,IAAsB;IACzC,OAAO;QACL,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,aAAa,EAAE,YAAY,CAAC;QAC9D,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,gBAAgB,EAAE;QAC/C,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,EAAE;KAC1B,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,WAAmB,EACnB,EAAoB,EACpB,OAAyB,EAAE;IAE3B,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IACzD,SAAS,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC3B,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;IACrC,IAAI,WAA8B,CAAC;IACnC,MAAM,aAAa,GAAG,CAAC,CAAQ,EAAQ,EAAE,GAAG,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/D,SAAS,CAAC;QACR,MAAM,GAAG,GAAG,UAAU,CAAC,WAAW,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC;QAC5D,IAAI,GAAG,KAAK,MAAM,EAAE,CAAC;YACnB,IAAI,MAAS,CAAC;YACd,IAAI,CAAC;gBACH,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC;YACtB,CAAC;oBAAS,CAAC;gBACT,GAAG,CAAC,OAAO,EAAE,CAAC;YAChB,CAAC;YACD,IAAI,WAAW,KAAK,SAAS;gBAAE,MAAM,IAAI,yBAAyB,CAAC,aAAa,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC,CAAC;YAC5G,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,GAAG,IAAI,QAAQ;YAAE,MAAM,IAAI,qBAAqB,CAAC,aAAa,CAAC,WAAW,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,CAAC;QAChG,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,GAAG,GAAG,CAAC,CAAC,CAAC;IAChD,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC/B,WAAmB,EACnB,EAAW,EACX,OAAyB,EAAE;IAE3B,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IACzD,SAAS,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC3B,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;IACrC,IAAI,WAA8B,CAAC;IACnC,MAAM,aAAa,GAAG,CAAC,CAAQ,EAAQ,EAAE,GAAG,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/D,SAAS,CAAC;QACR,MAAM,GAAG,GAAG,UAAU,CAAC,WAAW,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC;QAC5D,IAAI,GAAG,KAAK,MAAM,EAAE,CAAC;YACnB,IAAI,MAAS,CAAC;YACd,IAAI,CAAC;gBACH,MAAM,GAAG,EAAE,EAAE,CAAC;YAChB,CAAC;oBAAS,CAAC;gBACT,GAAG,CAAC,OAAO,EAAE,CAAC;YAChB,CAAC;YACD,IAAI,WAAW,KAAK,SAAS;gBAAE,MAAM,IAAI,yBAAyB,CAAC,aAAa,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC,CAAC;YAC5G,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,GAAG,IAAI,QAAQ;YAAE,MAAM,IAAI,qBAAqB,CAAC,aAAa,CAAC,WAAW,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,CAAC;QAChG,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,GAAG,GAAG,CAAC,CAAC,CAAC;IAC9C,CAAC;AACH,CAAC"}

package/dist/workflows.d.ts

@@ -1,28 +1,22 @@
 /**
- * Dynamic workflow templates for Opus 4.8+ orchestration.
+ * RETIRED — the ADR-005 workflow templates are gone (feature loop-designer, AM-6 / architecture
+ * §8.2). They emitted a pre-`meta`/`phases` format (`export default {tasks, maxConcurrency}`) the
+ * current Workflow runtime cannot execute — a broken command, not a feature.
  *
- * Per ADR-005: workflows live in the orchestration layer only.
- * They generate JS scripts that Claude Code's dynamic workflow engine executes.
- * Core schema, adapters, and skill content remain model-agnostic.
+ * Replacement: `dz workflow init` (scaffold a `loop-plan/1` plan), `dz workflow validate`,
+ * `dz workflow render` (plan → executable region-delimited loop script), plus the sibling gates
+ * `dz workflow-lint` and `dz workflow-trace`. See `loop-plan.ts` / `loop-render.ts`.
  *
- * @packageDocumentation
+ * BREAKING (deliberate, channeled): removing `WorkflowTemplate`/`WORKFLOWS`/`getWorkflow` is a
+ * public API change for harness-core. harness-core is 0.x, where MINOR is this repo's breaking
+ * channel; the removal is named in the CHANGELOG and README — never silent. The only internal
+ * importer was `harness-cli`'s `cmdWorkflow` (MEASURED at plan time), rewritten in the same change.
+ *
+ * This module stays as a deprecation shim so stale imports fail LOUDLY with a pointer, not with a
+ * confusing "module not found".
  */
-/** A workflow template — generates a JS orchestration script from parameters. */
-export interface WorkflowTemplate {
-    readonly name: string;
-    readonly description: string;
-    readonly generate: (options: WorkflowOptions) => string;
-}
-/** Options passed to workflow generation. */
-export interface WorkflowOptions {
-    readonly projectRoot: string;
-    readonly dryRun?: boolean;
-    readonly packages?: readonly string[];
-}
-/** All registered workflow templates. */
-export declare const WORKFLOWS: Record<string, WorkflowTemplate>;
-/** Valid workflow names. */
+/** The pinned retirement message the CLI prints (tested by workflow-legacy-shim.test.ts). */
+export declare const WORKFLOW_TEMPLATES_RETIRED_MESSAGE = "dz workflow: the ADR-005 templates are retired (they emitted a pre-meta format the runtime cannot run) \u2014 use dz workflow init/render";
+/** Empty by design: no legacy template names remain. */
 export declare const WORKFLOW_NAMES: string[];
-/** Look up a workflow by name. */
-export declare function getWorkflow(name: string): WorkflowTemplate | undefined;
 //# sourceMappingURL=workflows.d.ts.map

package/dist/workflows.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflows.d.ts","sourceRoot":"","sources":["../src/workflows.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,MAAM,CAAC;CACzD;AAED,6CAA6C;AAC7C,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAsFD,yCAAyC;AACzC,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAKtD,CAAC;AAEF,4BAA4B;AAC5B,eAAO,MAAM,cAAc,UAAyB,CAAC;AAErD,kCAAkC;AAClC,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAEtE"}
+{"version":3,"file":"workflows.d.ts","sourceRoot":"","sources":["../src/workflows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,6FAA6F;AAC7F,eAAO,MAAM,kCAAkC,8IACyF,CAAC;AAEzI,wDAAwD;AACxD,eAAO,MAAM,cAAc,EAAE,MAAM,EAAO,CAAC"}