greprag 5.50.0 → 5.52.0

package/dist/hook.js

@@ -117,7 +117,13 @@ const coordinate_gate_1 = require("./commands/coordinate-gate");
 // logic lives in ./commands/inbox-drain. adr: adr/monitor-resilience.md
 const inbox_drain_1 = require("./commands/inbox-drain");
 const procedure_1 = require("./procedure");
+// Procedure System LEARN leg (docs/procedure-system.md §V1 LEARN-leg build
+// spec): the span watch — opened at UserPromptSubmit (procedureCheck), observed
+// per turn by the Stop hook (observeProcedureTurn), closed by negative
+// continuity, distilled server-side, transitions applied to the local store.
+const procedure_watch_1 = require("./procedure-watch");
 const skill_landing_1 = require("./skill-landing");
+const skill_mirror_client_1 = require("./skill-mirror-client");
 const API_URL_DEFAULT = 'https://api.greprag.com';
 const MAX_FIELD_CHARS = 500_000; // safety cap per text field
 // ---------- Env + config ---------------------------------------------------
@@ -806,6 +812,125 @@ function collectDocEvents(filesTouched, cwd) {
     }
     return events;
 }
+// ---------- Procedure span observer (docs/procedure-system.md) --------------
+//
+// The LEARN leg's per-turn observer (build spec component 3). Gated on "a
+// watch file exists" — zero cost otherwise. Each observed turn: build a
+// compact TurnDigest, append it to the watch, ask the server the negative-
+// continuity question (synchronous — a ~0.5s flash-lite call inside the Stop
+// hook's existing 10s budget), then apply the pure close logic. Fail-open end
+// to end: a dead judge extends the watch (offStreak untouched) and the
+// max-turn watchdog reaps it.
+/** Fire-and-forget the watchdog's fix-queue smell via `greprag fix log`
+ *  (detached CLI child — the guard-refresh spawn shape). Best-effort. */
+function spawnProcedureSmell(cwd, text) {
+    try {
+        const cliJs = path.join(__dirname, 'index.js');
+        const child = (0, proc_1.safeSpawn)(process.execPath, [cliJs, 'fix', 'log', text, '--scope', 'procedure-watch'], { cwd, detached: true, stdio: 'ignore', windowsHide: true });
+        child.unref();
+    }
+    catch { /* best-effort */ }
+}
+/** One observed turn of the active watch. Never throws (the caller also
+ *  guards); every network call fail-open. */
+async function observeProcedureTurn(cfg, anchor, turn, cwd, redaction) {
+    const watch = (0, procedure_watch_1.readProcedureWatch)(anchor.projectId);
+    if (!watch) {
+        // File exists but is unreadable/corrupt — drop it so it can't wedge the observer.
+        (0, procedure_watch_1.clearProcedureWatch)(anchor.projectId);
+        return;
+    }
+    // Watchdog BEFORE the judge call — the aborting turn costs nothing. Abort =
+    // clear the watch, log a fix-queue smell, NEVER distill (build spec comp. 4).
+    if ((0, procedure_watch_1.willExceedWatchdog)(watch)) {
+        (0, procedure_watch_1.clearProcedureWatch)(anchor.projectId);
+        spawnProcedureSmell(cwd, `procedure watchdog: ${watch.phase} watch on "${watch.verb}" hit ${watch.turnCount} turns `
+            + `without closing — endpoint never detected (docs/procedure-system.md)`);
+        return;
+    }
+    // Compact digest of THIS turn, scrubbed like the turn envelope (secrets
+    // never travel — adr/secret-scrubber.md).
+    const rawDigest = (0, procedure_watch_1.buildTurnDigest)({
+        userPrompt: turn.userPrompt,
+        toolCalls: turn.toolCalls,
+        filesTouched: turn.filesTouched,
+        status: turn.status,
+    }, watch.turnCount + 1);
+    const digest = {
+        ...rawDigest,
+        user: (0, secret_scrubber_1.scrubString)(rawDigest.user, redaction),
+        commands: rawDigest.commands.map(c => (0, secret_scrubber_1.scrubString)(c, redaction)),
+    };
+    // The negative-continuity question — synchronous, fail-open: any miss →
+    // live=null → offStreak untouched, the watch just extends.
+    let live = null;
+    try {
+        const res = await fetch(`${cfg.apiUrl}/v1/procedure/${anchor.projectId}/observe`, {
+            method: 'POST',
+            headers: { 'Authorization': `Bearer ${cfg.apiKey}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                projectName: anchor.projectName,
+                verb: watch.verb,
+                phase: watch.phase,
+                digest,
+                turnCount: watch.turnCount + 1,
+            }),
+        });
+        if (res.ok) {
+            const data = await res.json();
+            live = typeof data.live === 'boolean' ? data.live : null;
+        }
+    }
+    catch { /* judge unreachable → null */ }
+    const { watch: next, disposition } = (0, procedure_watch_1.advanceWatch)(watch, digest, live);
+    if (disposition === 'watchdog') {
+        (0, procedure_watch_1.clearProcedureWatch)(anchor.projectId);
+        spawnProcedureSmell(cwd, `procedure watchdog: ${next.phase} watch on "${next.verb}" hit ${next.turnCount} turns `
+            + `without closing — endpoint never detected (docs/procedure-system.md)`);
+        return;
+    }
+    if (disposition === 'close') {
+        // Span = [open, lastLiveTurn] — trailing not-live turns never distill.
+        const span = (0, procedure_watch_1.liveSpan)(next);
+        if (span.length > 0) {
+            try {
+                const res = await fetch(`${cfg.apiUrl}/v1/procedure/${anchor.projectId}/distill`, {
+                    method: 'POST',
+                    headers: { 'Authorization': `Bearer ${cfg.apiKey}`, 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        projectName: anchor.projectName,
+                        verb: next.verb,
+                        phase: next.phase,
+                        digests: span,
+                    }),
+                });
+                if (res.ok) {
+                    const data = await res.json();
+                    const outcome = data.outcome === 'clean' || data.outcome === 'floundered'
+                        ? data.outcome : null;
+                    const distilled = data.procedure
+                        && typeof data.procedure.steps === 'string' && data.procedure.steps
+                        && typeof data.procedure.endpoint === 'string' && data.procedure.endpoint
+                        ? {
+                            steps: data.procedure.steps,
+                            endpoint: data.procedure.endpoint,
+                            caveats: typeof data.procedure.caveats === 'string' && data.procedure.caveats
+                                ? data.procedure.caveats : undefined,
+                        }
+                        : null;
+                    const store = (0, procedure_1.readProcedureStore)(anchor.projectId);
+                    const { store: nextStore, action } = (0, procedure_watch_1.applyDistillTransition)(store, next, outcome, distilled, (0, procedure_watch_1.learnTriggersForVerb)(next.verb, store));
+                    if (action !== 'discarded')
+                        (0, procedure_1.writeProcedureStore)(anchor.projectId, nextStore);
+                }
+            }
+            catch { /* judge down → no write; watch discarded (transition table row 4) */ }
+        }
+        (0, procedure_watch_1.clearProcedureWatch)(anchor.projectId);
+        return;
+    }
+    (0, procedure_watch_1.writeProcedureWatch)(anchor.projectId, next);
+}
 /** SessionStart fetch: the live enrichment-health verdict (fix c2eb8777).
  *  Null = healthy OR unreachable — the outage announce only fires on a
  *  POSITIVE probe failure, so an API blip never cries wolf. The worker
@@ -862,20 +987,88 @@ async function fetchAndLandSkillGains(apiUrl, apiKey, anchor, cwd) {
         return undefined;
     }
 }
+/** Manifest-liveness policy — mirror of core's assessLiveness threshold (the CLI
+ *  is a zero-dep artifact, so the tiny policy is duplicated, like
+ *  DOCPTR_ANNOUNCE_LIMIT). A doc must cite ≥3 in-repo paths with ≥60% dead before
+ *  it BURIES; bias-to-keep. */
+const DOCPTR_BURY_MIN_REFS = 3;
+const DOCPTR_BURY_DEAD_RATIO = 0.6;
+/** Resolve ONE cited ref to alive/dead/external against the live tree. The
+ *  manifest stores paths verbatim from the doc, so a ref may be repo-root-
+ *  relative, sibling-relative (`mechanic-repairs.md` inside docs/), or dot-
+ *  relative (`../packages/...`). Resolution is the precision leg — without it,
+ *  live canon that cites siblings by basename false-buries:
+ *    • external (absolute / drive / ~ / URL / escapes the repo) → SKIP, never
+ *      counted: it's not a claim about THIS tree.
+ *    • alive if any candidate (as-given OR resolved against the doc's dir) is
+ *      tracked OR exists on disk (existsSync catches gitignored-but-present
+ *      files like .env).
+ *    • else dead. */
+function refState(ref, docDir, cwd, present) {
+    const raw = (ref || '').trim();
+    if (!raw)
+        return 'skip';
+    if (/^(~|[a-zA-Z]:|\/)/.test(raw) || /^[a-z]+:\/\//i.test(raw))
+        return 'skip'; // external
+    const candidates = [raw, docDir ? `${docDir}/${raw}` : raw]
+        .map(c => path.posix.normalize(c).replace(/^\.\//, ''));
+    let anyInside = false;
+    for (const c of candidates) {
+        if (c.startsWith('..'))
+            continue; // escapes the repo → not an in-tree claim
+        anyInside = true;
+        if (present.has(c))
+            return 'alive';
+        try {
+            if (fs.existsSync(path.join(cwd, c)))
+                return 'alive';
+        }
+        catch { /* ignore */ }
+    }
+    return anyInside ? 'dead' : 'skip';
+}
+function docPtrLiveness(refs, docPath, cwd, present) {
+    const docDir = path.posix.dirname((docPath || '').replace(/\\/g, '/'));
+    const dir = docDir === '.' ? '' : docDir;
+    let alive = 0, dead = 0;
+    for (const r of (refs || [])) {
+        const s = refState(r, dir, cwd, present);
+        if (s === 'alive')
+            alive++;
+        else if (s === 'dead')
+            dead++;
+    }
+    const total = alive + dead; // externals excluded from the denominator
+    if (total === 0 || dead === 0)
+        return { liveness: 'fresh', dead: 0, total };
+    if (total >= DOCPTR_BURY_MIN_REFS && dead / total >= DOCPTR_BURY_DEAD_RATIO) {
+        return { liveness: 'buried', dead, total };
+    }
+    return { liveness: 'decayed', dead, total };
+}
 /** SessionStart fetch: ONE reconcile+list round trip. Ships the project's
  *  tracked .md set (`git ls-files`) so vanished docs go stale server-side, and
- *  returns the active pointers for the announce. [] on any error → the
- *  announce stays silent (never blocks a session start). */
+ *  returns the active pointers for the announce. Then — the deterministic
+ *  staleness leg (docs/doc-pointer-system.md §staleness) — scores each pointer's
+ *  reference manifest against the FULL tracked-file set: a doc whose cited files
+ *  have vanished has decayed against the code it described. Recompute-not-restore:
+ *  liveness is derived here each session from the persisted manifest + the live
+ *  tree, never a stored verdict. [] on any error → the announce stays silent. */
 async function fetchDocPointers(apiUrl, apiKey, anchor, cwd) {
     try {
-        let presentPaths;
+        let presentPaths; // eligible .md — the existence sweep
+        let trackedAll; // ALL tracked files — the manifest oracle
         try {
-            const out = (0, proc_1.safeExecSync)('git ls-files -- "*.md"', {
+            const md = (0, proc_1.safeExecSync)('git ls-files -- "*.md"', {
+                cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true,
+            });
+            presentPaths = md.split('\n').map(s => s.trim()).filter(s => isDocPathEligible(s));
+            const all = (0, proc_1.safeExecSync)('git ls-files', {
                 cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true,
             });
-            presentPaths = out.split('\n').map(s => s.trim()).filter(s => isDocPathEligible(s));
+            trackedAll = new Set(all.split('\n').map(s => s.trim().replace(/\\/g, '/')).filter(Boolean));
         }
-        catch { /* not a git repo — list-only reconcile */ }
+        catch { /* not a git repo — list-only reconcile, no liveness scoring */ }
         const res = await fetch(`${apiUrl}/v1/docptr/${anchor.projectId}/reconcile`, {
             method: 'POST',
             headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
@@ -884,9 +1077,24 @@ async function fetchDocPointers(apiUrl, apiKey, anchor, cwd) {
         if (!res.ok)
             return [];
         const data = await res.json();
-        return (data.pointers || [])
+        const scored = (data.pointers || [])
             .filter(p => p.path && p.hook)
-            .map(p => ({ path: p.path, hook: p.hook }));
+            .map(p => {
+            const path = p.path;
+            const hook = p.hook;
+            // No git tree (non-repo) → skip scoring; everything reads fresh.
+            if (!trackedAll)
+                return { path, hook };
+            const v = docPtrLiveness(p.refs || [], path, cwd, trackedAll);
+            if (v.liveness === 'fresh')
+                return { path, hook };
+            const note = `${v.dead}/${v.total} cited files gone`;
+            return { path, hook, decayNote: note, buried: v.liveness === 'buried' };
+        });
+        // Fresh + decayed first, buried (probably-stale) sink to the bottom so the
+        // review signal reads as a tail, not scattered through the canon.
+        scored.sort((a, b) => Number(a.buried ?? false) - Number(b.buried ?? false));
+        return scored;
     }
     catch {
         return [];
@@ -986,6 +1194,28 @@ async function store(input, source = 'claude-code') {
         }
         catch { /* best-effort — a docptr outage never fails the Stop hook */ }
     }
+    // Procedure System span observer (docs/procedure-system.md V1 LEARN leg):
+    // gated on "a watch file exists" — zero cost when no watch is open. One
+    // synchronous flash-lite continuity call per observed turn; close/watchdog
+    // logic is pure in procedure-watch.ts. Best-effort, never throws.
+    if ((0, procedure_watch_1.hasProcedureWatch)(anchor.projectId)) {
+        try {
+            await observeProcedureTurn(cfg, anchor, turn, cwd, redaction);
+        }
+        catch { /* fail-open — a procedure outage never fails the Stop hook */ }
+    }
+    // Skill mirror (docs/load-system.md Tier 3): a skill-load turn shadows that
+    // skill's current markdown into the tenant's load store — upload ONLY on
+    // change (local hash state), so an unchanged skill costs zero network.
+    // Follower semantics: files stay canonical. Best-effort, never throws.
+    if (provenance === 'skill-injection') {
+        const mirrorSkill = (0, turn_provenance_1.provenanceHint)(provenance, turn.userPrompt);
+        if (mirrorSkill) {
+            await (0, skill_mirror_client_1.maybeMirrorSkill)({
+                skill: mirrorSkill, cwd, apiUrl: cfg.apiUrl, apiKey: cfg.apiKey,
+            });
+        }
+    }
 }
 // ---------- Main ---------------------------------------------------------
 // ---------- Recap (SessionStart) ------------------------------------------
@@ -1312,6 +1542,23 @@ async function recap(input, mode = 'plain', opts = {}) {
     // gains → auto-land references into learnings docs, hold rule/scope
     // proposals for the announce. Best-effort; undefined → announce silent.
     const skillGains = await fetchAndLandSkillGains(cfg.apiUrl, cfg.apiKey, anchor, cwd);
+    // Tier-3 skill-mirror pointer signal (docs/load-system.md): mirrored-skill
+    // count + freshest names for the one-line announce. Best-effort.
+    const mirroredSkills = await (async () => {
+        try {
+            const res = await fetch(`${cfg.apiUrl}/v1/skillmirror`, {
+                headers: { 'Authorization': `Bearer ${cfg.apiKey}` },
+            });
+            if (!res.ok)
+                return undefined;
+            const data = await res.json();
+            const names = (data.skills || []).map(s => s.skillName || '').filter(Boolean);
+            return names.length > 0 ? { count: names.length, names } : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    })();
     // Assistant doctrine auto-load — fires ONLY for the flagged assistant project
     // (isAssistantProject), so a normal project sees zero change. The hook owns the
     // doctrine-file read; the assistant-doctrine module routes the text. adr: adr/assistant-role.md
@@ -1347,6 +1594,7 @@ async function recap(input, mode = 'plain', opts = {}) {
         docPointers,
         enrichmentDown,
         skillGains,
+        mirroredSkills,
         updateAvailable,
     };
     let announceReg = mechanicKilled() ? reminder_registry_1.REGISTRY.filter(m => m.id !== 'mechanic-friction') : reminder_registry_1.REGISTRY;
@@ -1461,13 +1709,22 @@ function codexSubagentStart(input) {
     if (context)
         writeAdditionalContext(input.hook_event_name || 'SubagentStart', context);
 }
-/** UserPromptSubmit — Procedure System REPLAY leg (docs/procedure-system.md).
- *  Match the prompt against the project's procedure store; on a hit inject the
- *  recipe + gate as additionalContext BEFORE the agent moves, so an operational
- *  verb runs cleanly instead of by trial-and-error. Pure-local (no network on
- *  the hot path — reads the file beside the matchset cache), additive, and
- *  fail-open: a miss or any error never blocks the turn. The Tier-1 intent guard
- *  (in matchProcedure) suppresses keyword mention-not-request false-fires. */
+/** UserPromptSubmit — Procedure System trigger leg (docs/procedure-system.md
+ *  §V1 LEARN-leg build spec, component 2). Two paths off a Tier-1 trigger hit:
+ *
+ *    (a) known NON-STALE procedure → inject the recipe + gate BEFORE the agent
+ *        moves (the REPLAY inject) + open a bounded REPLAY watch.
+ *    (b) matched verb with NO procedure, or status=stale → open an open-ended
+ *        LEARN watch, NO injection (there's nothing to inject; the flounder
+ *        about to happen is the learning material). The LEARN trigger
+ *        vocabulary is the Tier-1 verb list (matchLearnTrigger), independent
+ *        of the store — build + test ride here with no seed.
+ *
+ *  A LEARN watch NEVER opens for a destructive verb (the seed is the canon
+ *  even when stale). One active watch at a time — an in-flight watch is never
+ *  replaced. Pure-local (no network on the hot path), additive, fail-open:
+ *  a miss or any error never blocks the turn. The Tier-1 intent guard (in
+ *  matchProcedure) suppresses keyword mention-not-request false-fires. */
 async function procedureCheck(input) {
     try {
         const prompt = typeof input.prompt === 'string' ? input.prompt : '';
@@ -1477,12 +1734,20 @@ async function procedureCheck(input) {
         if (!anchor.projectId)
             return;
         const store = (0, procedure_1.readProcedureStore)(anchor.projectId);
-        if (!store.procedures.length)
+        const m = store.procedures.length ? (0, procedure_1.matchProcedure)(prompt, store) : null;
+        if (m && m.procedure.status !== 'stale') {
+            writeAdditionalContext(input.hook_event_name || 'UserPromptSubmit', (0, procedure_1.buildProcedureInjection)(m.procedure));
+            (0, procedure_watch_1.openWatchIfIdle)(anchor.projectId, m.procedure.verb, 'REPLAY');
             return;
-        const m = (0, procedure_1.matchProcedure)(prompt, store);
-        if (!m)
+        }
+        // LEARN path: a stale store hit, or a Tier-1 vocabulary hit with no
+        // procedure for the verb. No injection either way.
+        const lm = m || (0, procedure_watch_1.matchLearnTrigger)(prompt);
+        if (!lm)
             return;
-        writeAdditionalContext(input.hook_event_name || 'UserPromptSubmit', (0, procedure_1.buildProcedureInjection)(m.procedure));
+        if ((0, procedure_watch_1.isDestructiveVerb)(lm.procedure.verb, store))
+            return; // never LEARN a destructive verb
+        (0, procedure_watch_1.openWatchIfIdle)(anchor.projectId, lm.procedure.verb, 'LEARN');
     }
     catch { /* fail-open — a procedure miss never blocks the turn */ }
 }