greprag 5.49.16 → 5.51.0

package/dist/procedure.d.ts

@@ -0,0 +1,88 @@
+/** Procedure System — pure core + local store (docs/procedure-system.md).
+ *
+ *  A *procedure* is the repo-specific recipe behind an operational intent
+ *  (deploy / push / release / commit / merge). The system's job: when the user
+ *  asks for one, inject the known recipe + its gate BEFORE the agent moves, so
+ *  the operational verb runs cleanly instead of by trial-and-error.
+ *
+ *  This module is the PROOF slice — Tier 1 (deterministic keyword trigger) +
+ *  REPLAY (inject a seeded/learned recipe). It is intentionally local-file
+ *  backed, mirroring guard.ts's matchset cache: the UserPromptSubmit hook reads
+ *  it on the hot path, so there is NO network here (server persistence + the
+ *  LEARN/Stop-hook capture leg land later — docs/procedure-system.md phases).
+ *
+ *  Pure (matchProcedure / buildProcedureInjection / GIT_SEED_SET) is split from
+ *  the I/O (read/writeProcedureStore) so the matcher + injection text are
+ *  testable without touching disk — the coordinate-gate.ts shape.
+ */
+/** The status ladder IS the silent-reflex safety structure (docs/procedure-system.md):
+ *  a recipe is a hypothesis until reuse confirms it, and self-heals when it fails.
+ *    seeded     — hand-authored before any failure; injects with confidence.
+ *    discovered — Tier-2 only: a new procedure the judge proposed; below learned.
+ *    learned    — captured from one cold-start floundering→success span.
+ *    confirmed  — a clean injected REPLAY proved the recipe.
+ *    stale      — injection floundered → re-enter LEARN (overwrite). */
+export type ProcedureStatus = 'seeded' | 'discovered' | 'learned' | 'confirmed' | 'stale';
+export interface Procedure {
+    /** Normalized intent key (one per repo). */
+    verb: string;
+    /** Phrases in the user message that fire this procedure. Lowercased; matched
+     *  whole-word for single tokens, substring for multi-word phrases. */
+    triggers: string[];
+    /** The recipe — the winning command path. */
+    steps: string;
+    /** The gate / guardrail surfaced alongside the steps (load-bearing for
+     *  destructive verbs — a procedure carries gates, not just steps). */
+    caveats?: string;
+    /** The linked exit condition — how we know the procedure is done. */
+    endpoint?: string;
+    status: ProcedureStatus;
+    /** Destructive verbs (push → prod) MUST stay seeded and are never overwritten
+     *  by the LEARN leg — the one failure you can't afford even once. */
+    destructive?: boolean;
+    updatedAt?: string;
+}
+export interface ProcedureStore {
+    version: string;
+    procedures: Procedure[];
+}
+export interface ProcedureMatch {
+    procedure: Procedure;
+    /** Which trigger phrase fired — for diagnostics / the dry-run `match` command. */
+    trigger: string;
+}
+export declare const PROCEDURE_STORE_VERSION = "1";
+/** Beside the matchset cache (guard.ts), keyed by project_id so it survives
+ *  renames/worktrees and stays per-project. */
+export declare function procedureStorePath(projectId: string): string;
+/** Read the project's procedure store. Returns an empty store on any miss —
+ *  fail-open, so a read error never blocks the hot path. */
+export declare function readProcedureStore(projectId: string): ProcedureStore;
+export declare function writeProcedureStore(projectId: string, store: ProcedureStore): void;
+/** Insert-or-replace by verb. Destructive existing procedures are NOT silently
+ *  downgraded: a learned/auto write can't overwrite a destructive=true seed
+ *  (callers pass `force` for an explicit operator re-seed). Returns the store. */
+export declare function upsertProcedure(store: ProcedureStore, proc: Procedure, force?: boolean): ProcedureStore;
+export declare function removeProcedure(store: ProcedureStore, verb: string): ProcedureStore;
+/** True if a raw trigger hit should be SUPPRESSED — it reads as a mention, not
+ *  a request. PURE. (1) the trigger only appears inside a collision phrase;
+ *  (2) a negation sits within 3 tokens before the trigger. */
+export declare function intentSuppressed(promptLower: string, triggerLower: string): boolean;
+/** Match a user prompt against the store. Returns the procedure whose
+ *  LONGEST trigger phrase hits (most-specific wins — `git push` beats `push`,
+ *  `ship a release` beats `ship`), or null. PURE — no I/O. The Tier-1 intent
+ *  guard filters mention-not-request hits unless `ignoreIntentGuard` is set
+ *  (the `match` dry-run uses it to explain a suppression). */
+export declare function matchProcedure(prompt: string, store: ProcedureStore, opts?: {
+    ignoreIntentGuard?: boolean;
+}): ProcedureMatch | null;
+/** The additionalContext block injected at UserPromptSubmit when a procedure
+ *  matches. Leads with the gate for destructive verbs (the guardrail is the
+ *  point); otherwise leads with the steps. Bounded + labeled so the agent reads
+ *  it as a known recipe, not a new instruction to reason about. */
+export declare function buildProcedureInjection(proc: Procedure): string;
+/** The five operational verbs Travis conflates, encoded with their real recipes
+ *  + gates (docs/procedure-system.md). The deliberate contradiction —
+ *  deploy = don't-ask, push = always-ask — is exactly what trips a learning
+ *  dev; both gates ship on day one. `push` is destructive → seed-only. */
+export declare const GIT_SEED_SET: Procedure[];

package/dist/procedure.js

@@ -0,0 +1,269 @@
+"use strict";
+/** Procedure System — pure core + local store (docs/procedure-system.md).
+ *
+ *  A *procedure* is the repo-specific recipe behind an operational intent
+ *  (deploy / push / release / commit / merge). The system's job: when the user
+ *  asks for one, inject the known recipe + its gate BEFORE the agent moves, so
+ *  the operational verb runs cleanly instead of by trial-and-error.
+ *
+ *  This module is the PROOF slice — Tier 1 (deterministic keyword trigger) +
+ *  REPLAY (inject a seeded/learned recipe). It is intentionally local-file
+ *  backed, mirroring guard.ts's matchset cache: the UserPromptSubmit hook reads
+ *  it on the hot path, so there is NO network here (server persistence + the
+ *  LEARN/Stop-hook capture leg land later — docs/procedure-system.md phases).
+ *
+ *  Pure (matchProcedure / buildProcedureInjection / GIT_SEED_SET) is split from
+ *  the I/O (read/writeProcedureStore) so the matcher + injection text are
+ *  testable without touching disk — the coordinate-gate.ts shape.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GIT_SEED_SET = exports.PROCEDURE_STORE_VERSION = void 0;
+exports.procedureStorePath = procedureStorePath;
+exports.readProcedureStore = readProcedureStore;
+exports.writeProcedureStore = writeProcedureStore;
+exports.upsertProcedure = upsertProcedure;
+exports.removeProcedure = removeProcedure;
+exports.intentSuppressed = intentSuppressed;
+exports.matchProcedure = matchProcedure;
+exports.buildProcedureInjection = buildProcedureInjection;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+exports.PROCEDURE_STORE_VERSION = '1';
+// ---------- Store I/O (local, hot-path) --------------------------------------
+function stateDir() {
+    const home = process.env.HOME || process.env.USERPROFILE || '';
+    return path.join(home, '.greprag', 'state');
+}
+/** Beside the matchset cache (guard.ts), keyed by project_id so it survives
+ *  renames/worktrees and stays per-project. */
+function procedureStorePath(projectId) {
+    return path.join(stateDir(), `procedures-${projectId}.json`);
+}
+/** Read the project's procedure store. Returns an empty store on any miss —
+ *  fail-open, so a read error never blocks the hot path. */
+function readProcedureStore(projectId) {
+    try {
+        const raw = fs.readFileSync(procedureStorePath(projectId), 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed && Array.isArray(parsed.procedures)) {
+            return { version: parsed.version || exports.PROCEDURE_STORE_VERSION, procedures: parsed.procedures };
+        }
+    }
+    catch { /* missing / unreadable → empty */ }
+    return { version: exports.PROCEDURE_STORE_VERSION, procedures: [] };
+}
+function writeProcedureStore(projectId, store) {
+    const file = procedureStorePath(projectId);
+    const dir = path.dirname(file);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(store, null, 2) + '\n');
+}
+/** Insert-or-replace by verb. Destructive existing procedures are NOT silently
+ *  downgraded: a learned/auto write can't overwrite a destructive=true seed
+ *  (callers pass `force` for an explicit operator re-seed). Returns the store. */
+function upsertProcedure(store, proc, force = false) {
+    const existing = store.procedures.find(p => p.verb === proc.verb);
+    if (existing && existing.destructive && !force && proc.status !== 'seeded') {
+        return store; // protect the gate — never auto-overwrite a destructive seed
+    }
+    const next = store.procedures.filter(p => p.verb !== proc.verb);
+    next.push({ ...proc, updatedAt: proc.updatedAt || new Date().toISOString() });
+    return { version: store.version || exports.PROCEDURE_STORE_VERSION, procedures: next };
+}
+function removeProcedure(store, verb) {
+    return {
+        version: store.version || exports.PROCEDURE_STORE_VERSION,
+        procedures: store.procedures.filter(p => p.verb !== verb),
+    };
+}
+// ---------- Matching (PURE) --------------------------------------------------
+/** Does a trigger phrase occur in the (lowercased) prompt? Single tokens match
+ *  whole-word (`deploy` ≠ `redeployment`); multi-word phrases match as a
+ *  substring (`ship it`). */
+function triggerHits(promptLower, triggerLower) {
+    if (!triggerLower)
+        return false;
+    if (/\s/.test(triggerLower))
+        return promptLower.includes(triggerLower);
+    const re = new RegExp(`(^|[^a-z0-9])${escapeRegex(triggerLower)}([^a-z0-9]|$)`);
+    return re.test(promptLower);
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+// ---------- Intent guard (PURE) ----------------------------------------------
+/** Tier-1 intent guard — cheap, deterministic suppression of keyword
+ *  false-fires. A substring match injects on a *mention*, not a *request*
+ *  (docs/procedure-system.md): bare "deploy" fires on "don't deploy yet" and
+ *  "push" on "push back the deadline". For safe verbs that's noise; for a
+ *  destructive verb a false ⛔ gate is actively misleading. Suppresses two
+ *  classes — this is the deterministic stopgap; Tier-2's prompt-judge replaces
+ *  it with real intent recognition. */
+const INTENT_NEGATIONS = [
+    "don't", 'dont', 'not', 'no', 'never', 'without', 'avoid', "won't", 'wont',
+    "didn't", 'didnt', 'cannot', "can't", 'cant', 'stop',
+];
+/** The trigger token living inside a common NON-command phrase. */
+const INTENT_COLLISION_PHRASES = [
+    'push back', 'push for', 'push notification', 'push notifications', 'pushover',
+    'merge conflict', 'merge conflicts', 'merge request', 'merge sort',
+    'press release', 'release notes', 'release candidate', 'release date',
+    'commit message', 'commit hash', 'commit history', 'commit sha',
+];
+/** True if a raw trigger hit should be SUPPRESSED — it reads as a mention, not
+ *  a request. PURE. (1) the trigger only appears inside a collision phrase;
+ *  (2) a negation sits within 3 tokens before the trigger. */
+function intentSuppressed(promptLower, triggerLower) {
+    // (1) collision phrase — suppress only if the trigger has NO other occurrence
+    //     outside the collision phrase (a real command alongside the mention wins).
+    for (const phrase of INTENT_COLLISION_PHRASES) {
+        if (phrase.includes(triggerLower) && promptLower.includes(phrase)) {
+            const stripped = promptLower.split(phrase).join(' · ');
+            if (!triggerHits(stripped, triggerLower))
+                return true;
+        }
+    }
+    // (2) negation within 3 tokens before the trigger ("don't deploy", "no merge").
+    const idx = promptLower.search(new RegExp(`(^|[^a-z0-9])${escapeRegex(triggerLower)}([^a-z0-9]|$)`));
+    if (idx >= 0) {
+        const before = promptLower.slice(0, idx).split(/[^a-z']+/).filter(Boolean);
+        const window = ' ' + before.slice(-3).join(' ') + ' ';
+        if (INTENT_NEGATIONS.some(neg => window.includes(' ' + neg + ' ')))
+            return true;
+    }
+    return false;
+}
+/** Match a user prompt against the store. Returns the procedure whose
+ *  LONGEST trigger phrase hits (most-specific wins — `git push` beats `push`,
+ *  `ship a release` beats `ship`), or null. PURE — no I/O. The Tier-1 intent
+ *  guard filters mention-not-request hits unless `ignoreIntentGuard` is set
+ *  (the `match` dry-run uses it to explain a suppression). */
+function matchProcedure(prompt, store, opts = {}) {
+    if (!prompt)
+        return null;
+    const promptLower = prompt.toLowerCase();
+    let best = null;
+    let bestLen = -1;
+    for (const procedure of store.procedures) {
+        for (const trigger of procedure.triggers) {
+            const t = trigger.toLowerCase();
+            if (!triggerHits(promptLower, t))
+                continue;
+            if (!opts.ignoreIntentGuard && intentSuppressed(promptLower, t))
+                continue;
+            if (t.length > bestLen) {
+                best = { procedure, trigger };
+                bestLen = t.length;
+            }
+        }
+    }
+    return best;
+}
+// ---------- Injection text (PURE) --------------------------------------------
+/** The additionalContext block injected at UserPromptSubmit when a procedure
+ *  matches. Leads with the gate for destructive verbs (the guardrail is the
+ *  point); otherwise leads with the steps. Bounded + labeled so the agent reads
+ *  it as a known recipe, not a new instruction to reason about. */
+function buildProcedureInjection(proc) {
+    const lines = [];
+    const tag = proc.destructive ? ' ⚠ DESTRUCTIVE' : '';
+    lines.push(`[Procedure: ${proc.verb} — ${proc.status}${tag}] This repo has a known recipe for "${proc.verb}".`);
+    if (proc.destructive && proc.caveats) {
+        lines.push(`  ⛔ GATE: ${proc.caveats}`);
+        lines.push(`  STEPS (only after approval): ${proc.steps}`);
+    }
+    else {
+        lines.push(`  STEPS: ${proc.steps}`);
+        if (proc.caveats)
+            lines.push(`  GATE: ${proc.caveats}`);
+    }
+    if (proc.endpoint)
+        lines.push(`  ENDPOINT (done when): ${proc.endpoint}`);
+    lines.push(proc.destructive
+        ? `  Follow the gate exactly. Never run the steps without a fresh approval this turn.`
+        : `  Use this recipe. If it no longer works, say so — that's a stale procedure to re-learn.`);
+    return lines.join('\n');
+}
+// ---------- The git-ecosystem seed set ---------------------------------------
+/** The five operational verbs Travis conflates, encoded with their real recipes
+ *  + gates (docs/procedure-system.md). The deliberate contradiction —
+ *  deploy = don't-ask, push = always-ask — is exactly what trips a learning
+ *  dev; both gates ship on day one. `push` is destructive → seed-only. */
+exports.GIT_SEED_SET = [
+    {
+        verb: 'commit',
+        triggers: ['commit', 'check in', 'check it in', 'checkpoint this', 'land it'],
+        steps: 'git add -A && git commit -m "wip: <msg>"; then merge the feature branch into the default branch, prune the worktree, delete the merged branch (the /commit flow).',
+        caveats: 'Scope = only MY work — never sweep a parallel workstream\'s pending changes. STOPS before push.',
+        endpoint: 'changes committed and the feature branch merged into default',
+        status: 'seeded',
+    },
+    {
+        verb: 'merge',
+        triggers: ['merge', 'merge the branch', 'merge to main', 'merge into main'],
+        steps: 'git checkout <default> && git merge <branch> (folded into the commit flow).',
+        caveats: 'Another session live in this repo? Coordinate with the peer before merging shared state.',
+        endpoint: 'branch merged into the default branch with no conflicts',
+        status: 'seeded',
+    },
+    {
+        verb: 'push',
+        triggers: ['push', 'git push', 'push to remote', 'push it up', 'push upstream'],
+        steps: 'git push',
+        caveats: 'git push triggers a PRODUCTION deploy. STOP and get explicit fresh approval before pushing — never push without a fresh "yes" this turn.',
+        endpoint: 'operator approved the push AND it completed',
+        status: 'seeded',
+        destructive: true,
+    },
+    {
+        verb: 'deploy',
+        triggers: ['deploy', 'deploy the api', 'deploy the worker', 'redeploy'],
+        steps: 'cd packages/api && npm run deploy',
+        caveats: 'Routine — after a core fix + commit, run this WITHOUT asking. This is the wrangler deploy of the API worker; it is NOT a git push.',
+        endpoint: 'wrangler prints the published worker version (deploy success output)',
+        status: 'seeded',
+    },
+    {
+        verb: 'release',
+        triggers: ['release', 'ship it', 'ship a release', 'cut a release', 'publish the release', 'do a release'],
+        steps: 'Run the /release flow — greprag\'s actual ship path (version bump + publish).',
+        caveats: 'greprag ships via /release — NOT /commit and NOT /deploy. Do not conflate the three: commit lands code, deploy pushes the worker, release publishes a version.',
+        endpoint: 'the release is published (new version live)',
+        status: 'seeded',
+    },
+];
+//# sourceMappingURL=procedure.js.map

package/dist/procedure.js.map

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

package/dist/skill-landing.d.ts

@@ -0,0 +1,88 @@
+/** Skill-gain landing — the Skill Learning Loop's write-back half
+ *  (docs/skill-learning-loop.md §fuse shape, operator-ratified 2026-07-01).
+ *
+ *  THE SHAPE (Tony Stark's briefcase suit): the server-side distiller packaged
+ *  each gain as a focused doc + a blind one-liner. This leg — pure code, never
+ *  agent voluntarism (the skill-tuning autopsy's law) — lands both files:
+ *
+ *    docs/learned/<slug>.md   the laser-focused learning doc
+ *    SKILL.md (EOF)           one FUSE line: the one-liner + the schematic
+ *                             telling the NEXT invocation exactly what to do —
+ *                             expand the doc, fold it in where it belongs,
+ *                             delete the fuse and the doc.
+ *
+ *  The fuse is self-applying because it loads WITH the skill: the next agent
+ *  to invoke the skill reads it as part of the skill's own instructions, does
+ *  the short tune with the whole skill in context (the only actor that ever
+ *  legitimately has it), and the skill converges clean. If a run skips the
+ *  tune, the fuse persists as ordinary progressive disclosure — the learning
+ *  stays live either way (graceful degradation, no failure mode).
+ *
+ *  Guards: CAP 3 undigested fuses per skill (overflow waits server-side —
+ *  a skill drowning in briefcases isn't being used anyway); every artifact
+ *  stamped `skillgain:<id>`; `greprag skillgain reject <id>` is the undo
+ *  (removes fuse + doc). Landing routes through resolveSkillDir — the ONE
+ *  seam that swaps to the greprag-load skill store when skills move into the
+ *  CLI (the no-SKILL.md endgame).
+ *
+ *  Write-target routing (the trap): greprag's bundled skills publish from the
+ *  repo source (packages/cli/skill/<name>/) — ~/.claude/skills/<name>/ is an
+ *  init-overwritten artifact. Bundled + repo present → repo source; otherwise
+ *  the global skills dir; neither → the gain stays pending. */
+export interface PendingSkillGain {
+    nodeId: string;
+    skill: string;
+    gainType: 'rule' | 'scope' | 'reference';
+    text: string;
+    oneLiner?: string;
+    docSlug?: string;
+    docBody?: string;
+}
+/** Skills that ship FROM the greprag repo — their canonical source is
+ *  packages/cli/skill/<name>/; the installed copy is overwritten at init. */
+export declare const BUNDLED_SKILLS: string[];
+export declare const LEARNED_DIR_RELPATH: string;
+/** v1 legacy zone — reject still scans it for stamps landed before the recut. */
+export declare const LEARNINGS_RELPATH: string;
+/** Max undigested fuse lines a SKILL.md may carry; past this, new gains wait
+ *  server-side. Operator-ratified (2026-07-01). */
+export declare const MAX_FUSES_PER_SKILL = 3;
+/** Resolve the canonical directory for a skill. `existsFn` injectable for
+ *  tests. Order: bundled repo source (when cwd IS the greprag repo) → global
+ *  skills dir → null (defer). THE storage seam — the greprag-load skill-store
+ *  backend replaces this resolution, nothing above it. */
+export declare function resolveSkillDir(skill: string, cwd: string, homeDir: string, existsFn?: (p: string) => boolean): string | null;
+export declare function hasGainStamp(content: string, nodeId: string): boolean;
+/** Count undigested fuse lines in a SKILL.md body (digested ones were deleted
+ *  by the tune, so the count self-heals as briefcases get absorbed). PURE. */
+export declare function countFuses(skillMdContent: string): number;
+/** The fuse line — the briefcase's button. One line, blind (the one-liner
+ *  names the learning; the mass lives in the doc), carrying the exact
+ *  schematic for the next invocation. PURE — unit-tested. */
+export declare function buildFuseLine(gain: PendingSkillGain, docRelPath: string, projectName: string, dateISO: string): string;
+export type LandOutcome = 'landed' | 'already-landed' | 'capped' | 'deferred';
+/** Land ONE briefcase: write the learned doc + append the fuse to SKILL.md.
+ *  Deterministic file work only — never throws (failure defers the gain). */
+export declare function landBriefcase(gain: PendingSkillGain, cwd: string, homeDir: string, projectName: string): LandOutcome;
+/** Remove a gain's artifacts wherever they landed — the `skillgain reject`
+ *  undo: the fuse line (SKILL.md), the learned doc, and any v1-legacy
+ *  learnings.md line. Returns true if anything was removed. Never throws. */
+export declare function removeLandedGain(skill: string, nodeId: string, cwd: string, homeDir: string): boolean;
+export interface SkillGainLandingReport {
+    /** Briefcases landed this session start (for the informational announce). */
+    landed: Array<{
+        nodeId: string;
+        skill: string;
+        oneLiner: string;
+    }>;
+}
+/** The full landing pass. Every gain with a payload lands as a briefcase
+ *  (capped per skill + per start); payload-less/unroutable gains stay pending.
+ *  Returns the report (announce) + the status updates to POST back. */
+export declare function landPendingGains(pending: PendingSkillGain[], cwd: string, homeDir: string, projectName: string): {
+    report: SkillGainLandingReport;
+    statusUpdates: Array<{
+        nodeId: string;
+        status: 'landed';
+    }>;
+};