greprag 5.49.16 → 5.51.0

package/dist/hook.js

@@ -116,6 +116,14 @@ const coordinate_gate_1 = require("./commands/coordinate-gate");
 // read, advances the poll cursor. Closes the watcher dead-window gap. All real
 // 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 ---------------------------------------------------
@@ -747,6 +755,268 @@ function capField(text) {
     const originalKb = (text.length / 1000).toFixed(1);
     return `${truncated}\n\n[truncated: original ${originalKb}KB]`;
 }
+// ---------- Doc pointers (docs/doc-pointer-system.md) ----------------------
+//
+// The Document Pointer System's detect half. No new hook: the Stop hook already
+// sees every file the turn touched (filesTouched), so .md writes ride the same
+// event — a deterministic path filter here, the Flash-Lite worthiness judge
+// server-side. Best-effort end to end: a docptr failure never blocks a turn.
+/** Deterministic pre-filter — the cheap gate BEFORE the LLM judge. Rejects the
+ *  obvious never-index classes so they don't even cost a judge call: non-.md,
+ *  dot-directories (.tmp-*, .claude/, .github/ — harness/scratch, not project
+ *  docs), dependency/build trees, and the harness-owned CLAUDE.md/MEMORY.md
+ *  (always injected anyway — indexing them is circular noise). Judge-worthy
+ *  ambiguity (drafts, beats, plans) is the JUDGE's call, not this filter's. */
+function isDocPathEligible(relPath) {
+    const p = relPath.replace(/\\/g, '/');
+    if (!p.toLowerCase().endsWith('.md'))
+        return false;
+    const segments = p.split('/');
+    const base = segments[segments.length - 1];
+    if (base === 'CLAUDE.md' || base === 'MEMORY.md')
+        return false;
+    for (const seg of segments.slice(0, -1)) {
+        if (seg.startsWith('.'))
+            return false;
+        if (seg === 'node_modules' || seg === 'dist' || seg === 'build' || seg === 'vendor')
+            return false;
+    }
+    return true;
+}
+/** Head-snippet cap posted to the judge (server re-caps defensively). */
+const DOC_EVENT_SNIPPET_CHARS = 2_000;
+/** Max doc events per turn (mirrors the server's MAX_EVENTS_PER_POST). */
+const DOC_EVENTS_PER_TURN = 8;
+/** Turn's touched files → judge-ready doc events: project-relative eligible
+ *  .md paths + head snippets. Files outside cwd (scratchpad, other repos) and
+ *  unreadable files (deleted later in the turn) are skipped silently. */
+function collectDocEvents(filesTouched, cwd) {
+    const events = [];
+    const seen = new Set();
+    for (const abs of filesTouched) {
+        if (events.length >= DOC_EVENTS_PER_TURN)
+            break;
+        const rel = path.relative(cwd, abs).replace(/\\/g, '/');
+        if (!rel || rel.startsWith('..') || path.isAbsolute(rel))
+            continue;
+        if (!isDocPathEligible(rel) || seen.has(rel))
+            continue;
+        try {
+            const snippet = fs.readFileSync(abs, 'utf-8').slice(0, DOC_EVENT_SNIPPET_CHARS);
+            if (!snippet.trim())
+                continue;
+            seen.add(rel);
+            events.push({ path: rel, snippet });
+        }
+        catch { /* deleted/unreadable — skip */ }
+    }
+    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
+ *  caches the probe ~5 min; this adds one cheap GET per session start. */
+async function fetchEnrichmentDown(apiUrl, apiKey) {
+    try {
+        const res = await fetch(`${apiUrl}/v1/health/enrichment`, {
+            headers: { 'Authorization': `Bearer ${apiKey}` },
+        });
+        if (!res.ok)
+            return null;
+        const data = await res.json();
+        const e = data.enrichment;
+        if (!e || e.ok || !e.errorClass)
+            return null;
+        return { errorClass: e.errorClass, detail: e.detail, actionHint: e.actionHint };
+    }
+    catch {
+        return null;
+    }
+}
+/** SessionStart pass: the Skill Learning Loop's LANDING leg
+ *  (docs/skill-learning-loop.md — the write-back is CODE, not agent
+ *  voluntarism). Fetch pending gains → auto-land reference-tier into each
+ *  skill's docs/learnings.md → POST landed statuses back → return the report
+ *  for the announce. Undefined on any error → announce silent, gains stay
+ *  pending for the next session start. */
+async function fetchAndLandSkillGains(apiUrl, apiKey, anchor, cwd) {
+    try {
+        const res = await fetch(`${apiUrl}/v1/skillgain/${anchor.projectId}/pending`, {
+            headers: { 'Authorization': `Bearer ${apiKey}` },
+        });
+        if (!res.ok)
+            return undefined;
+        const data = await res.json();
+        const pending = (data.gains || []).filter(g => g.nodeId && g.skill && g.text);
+        if (pending.length === 0)
+            return undefined;
+        const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+        const { report, statusUpdates } = (0, skill_landing_1.landPendingGains)(pending, cwd, homeDir, anchor.projectName);
+        if (statusUpdates.length > 0) {
+            try {
+                await fetch(`${apiUrl}/v1/skillgain/${anchor.projectId}/status`, {
+                    method: 'POST',
+                    headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ projectName: anchor.projectName, updates: statusUpdates }),
+                });
+            }
+            catch { /* statuses re-sync next start — the stamp keeps lands idempotent */ }
+        }
+        return report.landed.length > 0 ? report : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 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). */
+async function fetchDocPointers(apiUrl, apiKey, anchor, cwd) {
+    try {
+        let presentPaths;
+        try {
+            const out = (0, proc_1.safeExecSync)('git ls-files -- "*.md"', {
+                cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true,
+            });
+            presentPaths = out.split('\n').map(s => s.trim()).filter(s => isDocPathEligible(s));
+        }
+        catch { /* not a git repo — list-only reconcile */ }
+        const res = await fetch(`${apiUrl}/v1/docptr/${anchor.projectId}/reconcile`, {
+            method: 'POST',
+            headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify({ projectName: anchor.projectName, presentPaths }),
+        });
+        if (!res.ok)
+            return [];
+        const data = await res.json();
+        return (data.pointers || [])
+            .filter(p => p.path && p.hook)
+            .map(p => ({ path: p.path, hook: p.hook }));
+    }
+    catch {
+        return [];
+    }
+}
 // ---------- Store ---------------------------------------------------------
 async function store(input, source = 'claude-code') {
     const cwd = input.cwd || process.cwd();
@@ -828,6 +1098,41 @@ async function store(input, source = 'claude-code') {
         source,
         provenance,
     });
+    // Doc Pointer System detect half (docs/doc-pointer-system.md): .md writes this
+    // turn → one best-effort event POST; the worthiness judge runs server-side in
+    // waitUntil. After the turn POST (memory capture always wins), never throws.
+    const docEvents = collectDocEvents(turn.filesTouched, cwd);
+    if (docEvents.length > 0) {
+        try {
+            await apiCall(`${cfg.apiUrl}/v1/docptr/${anchor.projectId}/events`, cfg.apiKey, {
+                projectName: anchor.projectName,
+                events: docEvents,
+            });
+        }
+        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) ------------------------------------------
@@ -1143,6 +1448,34 @@ async function recap(input, mode = 'plain', opts = {}) {
     // tap, so the corpus module can tell the agent to search them before answering
     // from training data. Best-effort; empty → the announce stays silent.
     const corpusApiDocs = await fetchCorpusApiDocs(cfg.apiUrl, cfg.apiKey);
+    // Doc-pointer announce signal (docs/doc-pointer-system.md) — one reconcile+list
+    // round trip: vanished docs go stale server-side, active pointers come back for
+    // the "core documents" block. Best-effort; empty → the announce stays silent.
+    const docPointers = await fetchDocPointers(cfg.apiUrl, cfg.apiKey, anchor, cwd);
+    // Enrichment-health signal (fix c2eb8777) — the live Gemini probe verdict.
+    // Null when healthy or unreachable; a positive failure fires the outage announce.
+    const enrichmentDown = await fetchEnrichmentDown(cfg.apiUrl, cfg.apiKey);
+    // Skill Learning Loop landing leg (docs/skill-learning-loop.md): pending
+    // 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
@@ -1175,6 +1508,10 @@ async function recap(input, mode = 'plain', opts = {}) {
         setupWarning,
         assistantDoctrine,
         corpusApiDocs,
+        docPointers,
+        enrichmentDown,
+        skillGains,
+        mirroredSkills,
         updateAvailable,
     };
     let announceReg = mechanicKilled() ? reminder_registry_1.REGISTRY.filter(m => m.id !== 'mechanic-friction') : reminder_registry_1.REGISTRY;
@@ -1289,6 +1626,48 @@ function codexSubagentStart(input) {
     if (context)
         writeAdditionalContext(input.hook_event_name || 'SubagentStart', context);
 }
+/** 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 : '';
+        if (!prompt.trim())
+            return;
+        const anchor = (0, project_anchor_1.readAnchor)(input.cwd || process.cwd());
+        if (!anchor.projectId)
+            return;
+        const store = (0, procedure_1.readProcedureStore)(anchor.projectId);
+        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;
+        }
+        // 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;
+        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 */ }
+}
 async function notify(input, source = 'claude-code') {
     if (source === 'codex')
         cacheCodexPrompt(input);
@@ -1738,7 +2117,7 @@ async function main() {
     const subcommand = process.argv[2];
     const validSubs = new Set([
         'store', 'recap', 'recompact', 'notify', 'mail', 'friction-reminder', 'session-id', 'pre-spawn-check', 'armcheck',
-        'collision-check', 'drain', 'coordinate-gate',
+        'collision-check', 'drain', 'coordinate-gate', 'procedure-check',
         'guard', 'guard-refresh', 'guard-flush',
         'context-probe', 'context-check', 'crush-wrap',
         'pre-compact', 'archive-pointer',
@@ -1746,7 +2125,7 @@ async function main() {
         'codex-permission-context', 'codex-subagent-start',
     ]);
     if (!validSubs.has(subcommand)) {
-        process.stderr.write(`Usage: greprag-hook <store|recap|recompact|notify|mail|friction-reminder|session-id|pre-spawn-check|armcheck|collision-check|drain|coordinate-gate|guard|guard-refresh|guard-flush|context-probe|context-check|crush-wrap|pre-compact|archive-pointer|codex-store|codex-notify|codex-inbox|codex-recap|codex-permission-context|codex-subagent-start>\n`);
+        process.stderr.write(`Usage: greprag-hook <store|recap|recompact|notify|mail|friction-reminder|procedure-check|session-id|pre-spawn-check|armcheck|collision-check|drain|coordinate-gate|guard|guard-refresh|guard-flush|context-probe|context-check|crush-wrap|pre-compact|archive-pointer|codex-store|codex-notify|codex-inbox|codex-recap|codex-permission-context|codex-subagent-start>\n`);
         process.exit(1);
     }
     let input = {};
@@ -1781,6 +2160,11 @@ async function main() {
     else if (subcommand === 'mail') {
         await mail(input);
     }
+    else if (subcommand === 'procedure-check') {
+        // UserPromptSubmit — Procedure System REPLAY: inject a matched recipe + gate
+        // before the agent moves. Local, additive, fail-open. docs/procedure-system.md
+        await procedureCheck(input);
+    }
     else if (subcommand === 'friction-reminder') {
         // UserPromptSubmit — the active Mechanic's dynamic friction reminder (beside
         // the arm directive). Stress-driven tier: silent/ambient/nudge/nag. Reads the