@mmnto/cli 1.35.0 → 1.36.0

package/dist/hook/runtime.d.ts

@@ -0,0 +1,47 @@
+import type { CompiledHookRule } from './schema.js';
+/**
+ * Hook runtime evaluator (ADR-104 § Decisions 1, 2 + § Convergence).
+ *
+ * Takes a single hook rule plus a tool-call payload (tool name + tool args
+ * as a single string) and returns a structured allow/reject decision. The
+ * runtime is deterministic Node.js — no LLM calls in this path (Tenet 15
+ * corollary, ADR-103 § 8).
+ *
+ * V1 matcher class is regex-only per execution plan § 4. ast-grep and
+ * other matcher classes are deferred to V2; the schema permits future
+ * `verification_shadow` blocks but the V1 runtime ignores them.
+ */
+export interface ToolCallPayload {
+    /** The tool the agent is attempting to invoke (e.g. "bash"). */
+    tool: string;
+    /** Serialized tool arguments. For bash this is the command string;
+     *  for structured tools, callers serialize to a stable string form. */
+    args: string;
+}
+export type AllowDecision = {
+    decision: 'allow';
+};
+export type RejectDecision = {
+    decision: 'reject';
+    message: string;
+    packId: string;
+    ruleId: string;
+    recoveryHint?: string;
+};
+export type HookDecision = AllowDecision | RejectDecision;
+/**
+ * Build the structured rejection message per ADR-104 § Decision 1:
+ *
+ *     [totem:hook-block] <packId>/<ruleId>: <message>
+ *       → <recoveryHint>
+ *
+ * The `→ <recoveryHint>` line is omitted when no recoveryHint is provided.
+ * Agents and operators grep for the `[totem:hook-block]` prefix; the
+ * `<packId>/<ruleId>` carries provenance.
+ *
+ * Parameter is narrowed to `RejectDecision` so the type system prevents
+ * passing an allow decision — no runtime guard needed.
+ */
+export declare function formatRejection(decision: RejectDecision): string;
+export declare function evaluateHook(rule: CompiledHookRule, payload: ToolCallPayload): HookDecision;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/hook/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/hook/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb;2EACuE;IACvE,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,aAAa,GAAG;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC;AAElD,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,aAAa,GAAG,cAAc,CAAC;AAE1D;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAMhE;AA4CD,wBAAgB,YAAY,CAAC,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,eAAe,GAAG,YAAY,CA4B3F"}

package/dist/hook/runtime.js

@@ -0,0 +1,85 @@
+/**
+ * Build the structured rejection message per ADR-104 § Decision 1:
+ *
+ *     [totem:hook-block] <packId>/<ruleId>: <message>
+ *       → <recoveryHint>
+ *
+ * The `→ <recoveryHint>` line is omitted when no recoveryHint is provided.
+ * Agents and operators grep for the `[totem:hook-block]` prefix; the
+ * `<packId>/<ruleId>` carries provenance.
+ *
+ * Parameter is narrowed to `RejectDecision` so the type system prevents
+ * passing an allow decision — no runtime guard needed.
+ */
+export function formatRejection(decision) {
+    const header = `[totem:hook-block] ${decision.packId}/${decision.ruleId}: ${decision.message}`;
+    if (decision.recoveryHint) {
+        return `${header}\n  → ${decision.recoveryHint}`;
+    }
+    return header;
+}
+/**
+ * Evaluate a single compiled hook rule against a tool-call payload.
+ *
+ * Two-stage gate:
+ * 1. Trigger gate: does this rule apply to this tool + args?
+ *    Rule applies when `rule.trigger.tool` equals `payload.tool` AND
+ *    `rule.trigger.pattern` matches `payload.args`.
+ * 2. Check gate: when the trigger matches, apply `rule.check.pattern` to
+ *    args. `reject-if-match` rejects on match; `reject-if-no-match`
+ *    rejects on non-match.
+ *
+ * Returns `{ decision: 'allow' }` when either gate passes the call through.
+ *
+ * V1 invariant: regex matching only. Future matcher classes (ast-grep,
+ * Rego-shadow) ship in V2 follow-on ADRs.
+ *
+ * Per ADR-104 § Convergence, any `verification_shadow` block on the rule
+ * is silently ignored at the runtime layer (V1 hooks are Interpretive
+ * Rule class — no formal-verification obligation). Warn-and-ignore of
+ * verification_shadow happens at the load layer when compiling pack
+ * hooks.yaml, not on every hook-run invocation.
+ */
+/**
+ * Memoizes compiled RegExp instances keyed by pattern string. Pack rule
+ * patterns are stable for the lifetime of a CLI process (the manifest is
+ * loaded once at startup), so a string-keyed cache is sufficient — there
+ * is no unbounded-growth concern in the single-shot CLI use case.
+ *
+ * Safe to memoize because the patterns are compiled with no flags, so the
+ * returned RegExp has no stateful `lastIndex` carry-over between `.test()`
+ * calls.
+ */
+const regexCache = new Map();
+function getCompiledRegex(pattern) {
+    const cached = regexCache.get(pattern);
+    if (cached)
+        return cached;
+    const compiled = new RegExp(pattern);
+    regexCache.set(pattern, compiled);
+    return compiled;
+}
+export function evaluateHook(rule, payload) {
+    if (rule.trigger.tool !== payload.tool) {
+        return { decision: 'allow' };
+    }
+    const triggerRegex = getCompiledRegex(rule.trigger.pattern);
+    if (!triggerRegex.test(payload.args)) {
+        return { decision: 'allow' };
+    }
+    const checkRegex = getCompiledRegex(rule.check.pattern);
+    const matched = checkRegex.test(payload.args);
+    const shouldReject = (rule.check.type === 'reject-if-match' && matched) ||
+        (rule.check.type === 'reject-if-no-match' && !matched);
+    if (!shouldReject) {
+        return { decision: 'allow' };
+    }
+    return {
+        decision: 'reject',
+        message: rule.message,
+        packId: rule.packId,
+        ruleId: rule.id,
+        recoveryHint: rule.recoveryHint,
+    };
+}
+//# sourceMappingURL=runtime.js.map

package/dist/hook/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/hook/runtime.ts"],"names":[],"mappings":"AAmCA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAAC,QAAwB;IACtD,MAAM,MAAM,GAAG,sBAAsB,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,MAAM,KAAK,QAAQ,CAAC,OAAO,EAAE,CAAC;IAC/F,IAAI,QAAQ,CAAC,YAAY,EAAE,CAAC;QAC1B,OAAO,GAAG,MAAM,SAAS,QAAQ,CAAC,YAAY,EAAE,CAAC;IACnD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;;;;;;;;;GASG;AACH,MAAM,UAAU,GAAG,IAAI,GAAG,EAAkB,CAAC;AAE7C,SAAS,gBAAgB,CAAC,OAAe;IACvC,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACvC,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,MAAM,QAAQ,GAAG,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC;IACrC,UAAU,CAAC,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAClC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAsB,EAAE,OAAwB;IAC3E,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,IAAI,EAAE,CAAC;QACvC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;IAC/B,CAAC;IAED,MAAM,YAAY,GAAG,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5D,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACrC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;IAC/B,CAAC;IAED,MAAM,UAAU,GAAG,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACxD,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9C,MAAM,YAAY,GAChB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,iBAAiB,IAAI,OAAO,CAAC;QAClD,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,oBAAoB,IAAI,CAAC,OAAO,CAAC,CAAC;IAEzD,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;IAC/B,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,QAAQ;QAClB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,MAAM,EAAE,IAAI,CAAC,EAAE;QACf,YAAY,EAAE,IAAI,CAAC,YAAY;KAChC,CAAC;AACJ,CAAC"}

package/dist/hook/runtime.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=runtime.test.d.ts.map

package/dist/hook/runtime.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.test.d.ts","sourceRoot":"","sources":["../../src/hook/runtime.test.ts"],"names":[],"mappings":""}

package/dist/hook/runtime.test.js

@@ -0,0 +1,135 @@
+import { describe, expect, it } from 'vitest';
+import { evaluateHook, formatRejection } from './runtime.js';
+function rule(overrides = {}) {
+    return {
+        id: 'gca-tag-xor-command',
+        packId: '@mmnto/pack-bot-gemini-code-assist',
+        trigger: { tool: 'bash', pattern: 'gh\\s+(pr|issue)\\s+comment' },
+        check: {
+            pattern: '(?=.*@gemini-code-assist)(?=.*\\/gemini review)',
+            type: 'reject-if-match',
+        },
+        message: 'GCA tag XOR command — never both; doubling wastes GCA quota.',
+        recoveryHint: 'Choose one: @-mention to comment, /gemini review for fresh review.',
+        ...overrides,
+    };
+}
+describe('evaluateHook', () => {
+    describe('trigger gate', () => {
+        it('allows when payload.tool does not match rule.trigger.tool', () => {
+            const result = evaluateHook(rule(), { tool: 'write', args: 'whatever' });
+            expect(result.decision).toBe('allow');
+        });
+        it('allows when payload.tool matches but trigger.pattern does not', () => {
+            // Trigger requires `gh pr comment` or `gh issue comment`; this is `gh pr list`.
+            const result = evaluateHook(rule(), { tool: 'bash', args: 'gh pr list' });
+            expect(result.decision).toBe('allow');
+        });
+    });
+    describe('check gate — reject-if-match', () => {
+        it('rejects when both trigger and check patterns match', () => {
+            const args = 'gh pr comment 123 --body "@gemini-code-assist /gemini review please"';
+            const result = evaluateHook(rule(), { tool: 'bash', args });
+            expect(result.decision).toBe('reject');
+            if (result.decision === 'reject') {
+                expect(result.message).toMatch(/GCA tag XOR/);
+                expect(result.packId).toBe('@mmnto/pack-bot-gemini-code-assist');
+                expect(result.ruleId).toBe('gca-tag-xor-command');
+            }
+        });
+        it('allows when trigger matches but check does not (only one of the two tags present)', () => {
+            // Trigger matches `gh pr comment` but the check requires BOTH the
+            // @mention AND the slash command — this comment has only the mention.
+            const args = 'gh pr comment 123 --body "@gemini-code-assist take a look"';
+            const result = evaluateHook(rule(), { tool: 'bash', args });
+            expect(result.decision).toBe('allow');
+        });
+    });
+    describe('check gate — reject-if-no-match', () => {
+        it('rejects when trigger matches but the required check pattern is absent', () => {
+            const r = rule({
+                id: 'requires-fixes-block',
+                check: { pattern: '## Fixes', type: 'reject-if-no-match' },
+                trigger: { tool: 'bash', pattern: 'git\\s+commit' },
+                message: 'Commit message must include a `## Fixes` section.',
+            });
+            const result = evaluateHook(r, { tool: 'bash', args: 'git commit -m "wip"' });
+            expect(result.decision).toBe('reject');
+        });
+        it('allows when the required check pattern is present', () => {
+            const r = rule({
+                check: { pattern: '## Fixes', type: 'reject-if-no-match' },
+                trigger: { tool: 'bash', pattern: 'git\\s+commit' },
+            });
+            const result = evaluateHook(r, {
+                tool: 'bash',
+                args: 'git commit -m "feat: x\\n\\n## Fixes\\n- y"',
+            });
+            expect(result.decision).toBe('allow');
+        });
+    });
+    describe('reject decision payload', () => {
+        it('carries packId and ruleId for provenance', () => {
+            const args = 'gh pr comment 1 --body "@gemini-code-assist /gemini review"';
+            const result = evaluateHook(rule(), { tool: 'bash', args });
+            expect(result).toMatchObject({
+                decision: 'reject',
+                packId: '@mmnto/pack-bot-gemini-code-assist',
+                ruleId: 'gca-tag-xor-command',
+            });
+        });
+        it('preserves recoveryHint when present', () => {
+            const args = 'gh pr comment 1 --body "@gemini-code-assist /gemini review"';
+            const result = evaluateHook(rule(), { tool: 'bash', args });
+            if (result.decision === 'reject') {
+                expect(result.recoveryHint).toMatch(/Choose one/);
+            }
+        });
+        it('returns undefined recoveryHint when the rule omits it', () => {
+            const r = rule({ recoveryHint: undefined });
+            const args = 'gh pr comment 1 --body "@gemini-code-assist /gemini review"';
+            const result = evaluateHook(r, { tool: 'bash', args });
+            if (result.decision === 'reject') {
+                expect(result.recoveryHint).toBeUndefined();
+            }
+        });
+    });
+    describe('verification_shadow ignored at runtime', () => {
+        it('evaluates as Interpretive Rule even when verification_shadow is present', () => {
+            // Per ADR-104 § Convergence: hooks fall into Interpretive Rule class
+            // in V1. verification_shadow on a hook rule is reserved schema field
+            // for future Spine-Rule promotion; the V1 runtime must not change
+            // its decision based on its presence or absence.
+            const args = 'gh pr comment 1 --body "@gemini-code-assist /gemini review"';
+            const withShadow = rule({ verification_shadow: { rego: 'package x' } });
+            const withoutShadow = rule();
+            expect(evaluateHook(withShadow, { tool: 'bash', args })).toEqual(evaluateHook(withoutShadow, { tool: 'bash', args }));
+        });
+    });
+});
+describe('formatRejection', () => {
+    it('formats the structured prefix with packId/ruleId when recoveryHint is absent', () => {
+        const decision = {
+            decision: 'reject',
+            packId: '@mmnto/pack-bot-coderabbit',
+            ruleId: 'r1',
+            message: 'do not commit secrets',
+        };
+        expect(formatRejection(decision)).toBe('[totem:hook-block] @mmnto/pack-bot-coderabbit/r1: do not commit secrets');
+    });
+    it('includes the recovery-hint line when present', () => {
+        const decision = {
+            decision: 'reject',
+            packId: '@mmnto/pack-bot-coderabbit',
+            ruleId: 'r1',
+            message: 'do not commit secrets',
+            recoveryHint: 'use git-crypt or vault',
+        };
+        expect(formatRejection(decision)).toBe('[totem:hook-block] @mmnto/pack-bot-coderabbit/r1: do not commit secrets\n' +
+            '  → use git-crypt or vault');
+    });
+    // The previous "throws when given an allow decision" runtime guard is gone —
+    // formatRejection's parameter is now narrowed to RejectDecision so the type
+    // system prevents the caller bug at compile time. TS-only enforcement.
+});
+//# sourceMappingURL=runtime.test.js.map

package/dist/hook/runtime.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.test.js","sourceRoot":"","sources":["../../src/hook/runtime.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAE9C,OAAO,EAAE,YAAY,EAAE,eAAe,EAAuB,MAAM,cAAc,CAAC;AAGlF,SAAS,IAAI,CAAC,YAAuC,EAAE;IACrD,OAAO;QACL,EAAE,EAAE,qBAAqB;QACzB,MAAM,EAAE,oCAAoC;QAC5C,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,6BAA6B,EAAE;QACjE,KAAK,EAAE;YACL,OAAO,EAAE,iDAAiD;YAC1D,IAAI,EAAE,iBAAiB;SACxB;QACD,OAAO,EAAE,8DAA8D;QACvE,YAAY,EAAE,oEAAoE;QAClF,GAAG,SAAS;KACb,CAAC;AACJ,CAAC;AAED,QAAQ,CAAC,cAAc,EAAE,GAAG,EAAE;IAC5B,QAAQ,CAAC,cAAc,EAAE,GAAG,EAAE;QAC5B,EAAE,CAAC,2DAA2D,EAAE,GAAG,EAAE;YACnE,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;YACzE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACxC,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,+DAA+D,EAAE,GAAG,EAAE;YACvE,gFAAgF;YAChF,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;YAC1E,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACxC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,8BAA8B,EAAE,GAAG,EAAE;QAC5C,EAAE,CAAC,oDAAoD,EAAE,GAAG,EAAE;YAC5D,MAAM,IAAI,GAAG,sEAAsE,CAAC;YACpF,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5D,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACvC,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;gBACjC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;gBAC9C,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,oCAAoC,CAAC,CAAC;gBACjE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;YACpD,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,mFAAmF,EAAE,GAAG,EAAE;YAC3F,kEAAkE;YAClE,sEAAsE;YACtE,MAAM,IAAI,GAAG,4DAA4D,CAAC;YAC1E,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5D,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACxC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,iCAAiC,EAAE,GAAG,EAAE;QAC/C,EAAE,CAAC,uEAAuE,EAAE,GAAG,EAAE;YAC/E,MAAM,CAAC,GAAG,IAAI,CAAC;gBACb,EAAE,EAAE,sBAAsB;gBAC1B,KAAK,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,oBAAoB,EAAE;gBAC1D,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE;gBACnD,OAAO,EAAE,mDAAmD;aAC7D,CAAC,CAAC;YACH,MAAM,MAAM,GAAG,YAAY,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,EAAE,CAAC,CAAC;YAC9E,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzC,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,mDAAmD,EAAE,GAAG,EAAE;YAC3D,MAAM,CAAC,GAAG,IAAI,CAAC;gBACb,KAAK,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,oBAAoB,EAAE;gBAC1D,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE;aACpD,CAAC,CAAC;YACH,MAAM,MAAM,GAAG,YAAY,CAAC,CAAC,EAAE;gBAC7B,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,6CAA6C;aACpD,CAAC,CAAC;YACH,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACxC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,yBAAyB,EAAE,GAAG,EAAE;QACvC,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;YAClD,MAAM,IAAI,GAAG,6DAA6D,CAAC;YAC3E,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5D,MAAM,CAAC,MAAM,CAAC,CAAC,aAAa,CAAC;gBAC3B,QAAQ,EAAE,QAAQ;gBAClB,MAAM,EAAE,oCAAoC;gBAC5C,MAAM,EAAE,qBAAqB;aAC9B,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,qCAAqC,EAAE,GAAG,EAAE;YAC7C,MAAM,IAAI,GAAG,6DAA6D,CAAC;YAC3E,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5D,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;gBACjC,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;YACpD,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,uDAAuD,EAAE,GAAG,EAAE;YAC/D,MAAM,CAAC,GAAG,IAAI,CAAC,EAAE,YAAY,EAAE,SAAS,EAAE,CAAC,CAAC;YAC5C,MAAM,IAAI,GAAG,6DAA6D,CAAC;YAC3E,MAAM,MAAM,GAAG,YAAY,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;YACvD,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;gBACjC,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,aAAa,EAAE,CAAC;YAC9C,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,wCAAwC,EAAE,GAAG,EAAE;QACtD,EAAE,CAAC,yEAAyE,EAAE,GAAG,EAAE;YACjF,qEAAqE;YACrE,qEAAqE;YACrE,kEAAkE;YAClE,iDAAiD;YACjD,MAAM,IAAI,GAAG,6DAA6D,CAAC;YAC3E,MAAM,UAAU,GAAG,IAAI,CAAC,EAAE,mBAAmB,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,CAAC,CAAC;YACxE,MAAM,aAAa,GAAG,IAAI,EAAE,CAAC;YAC7B,MAAM,CAAC,YAAY,CAAC,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,CAC9D,YAAY,CAAC,aAAa,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CACpD,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,iBAAiB,EAAE,GAAG,EAAE;IAC/B,EAAE,CAAC,8EAA8E,EAAE,GAAG,EAAE;QACtF,MAAM,QAAQ,GAAmB;YAC/B,QAAQ,EAAE,QAAQ;YAClB,MAAM,EAAE,4BAA4B;YACpC,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE,uBAAuB;SACjC,CAAC;QACF,MAAM,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CACpC,yEAAyE,CAC1E,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8CAA8C,EAAE,GAAG,EAAE;QACtD,MAAM,QAAQ,GAAmB;YAC/B,QAAQ,EAAE,QAAQ;YAClB,MAAM,EAAE,4BAA4B;YACpC,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE,uBAAuB;YAChC,YAAY,EAAE,wBAAwB;SACvC,CAAC;QACF,MAAM,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CACpC,2EAA2E;YACzE,4BAA4B,CAC/B,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,6EAA6E;IAC7E,4EAA4E;IAC5E,uEAAuE;AACzE,CAAC,CAAC,CAAC"}

package/dist/hook/schema.d.ts

@@ -0,0 +1,385 @@
+import { z } from 'zod';
+/**
+ * Hook rule schemas for the bot-pack wiring engine (ADR-104).
+ *
+ * Two surfaces:
+ * - `HooksYamlSchema` describes a pack's `hooks.yaml` (authoring surface).
+ * - `CompiledHooksManifestSchema` describes `.totem/compiled-hooks.json`
+ *   (runtime surface produced by `totem sync` from installed packs).
+ *
+ * The compiled manifest carries the staleness metadata required by
+ * ADR-104 § Decision 3: schemaVersion + compiledAt + sourcePackVersions.
+ */
+declare const HookCheckTypeSchema: z.ZodEnum<["reject-if-match", "reject-if-no-match"]>;
+export type HookCheckType = z.infer<typeof HookCheckTypeSchema>;
+/**
+ * Authoring-surface schema for a single hook rule in a pack's `hooks.yaml`.
+ *
+ * The optional `recoveryHint` field (ADR-104 § Decision 1) gives agents the
+ * WHAT-INSTEAD on a block — recommended but not required in V1. Adoption
+ * tracked toward a V2 upgrade-to-required trigger (>80% of published rules
+ * carry it, OR an empirically-observed retry-loop incident).
+ *
+ * The `verification_shadow` field is reserved for the Spine Rule
+ * classification path (ADR-104 § Convergence + Q1 binding). In V1 the engine
+ * MUST warn-and-ignore any verification_shadow on a hook rule (hooks are
+ * Interpretive Rule class — no formal verification obligation). Schema
+ * accepts it permissively so future Spine-Rule promotion does not require
+ * a schema break.
+ */
+export declare const HookRuleSchema: z.ZodObject<{
+    id: z.ZodString;
+    trigger: z.ZodObject<{
+        tool: z.ZodString;
+        pattern: z.ZodEffects<z.ZodString, string, string>;
+    }, "strip", z.ZodTypeAny, {
+        tool: string;
+        pattern: string;
+    }, {
+        tool: string;
+        pattern: string;
+    }>;
+    check: z.ZodObject<{
+        pattern: z.ZodEffects<z.ZodString, string, string>;
+        type: z.ZodEnum<["reject-if-match", "reject-if-no-match"]>;
+    }, "strip", z.ZodTypeAny, {
+        type: "reject-if-match" | "reject-if-no-match";
+        pattern: string;
+    }, {
+        type: "reject-if-match" | "reject-if-no-match";
+        pattern: string;
+    }>;
+    message: z.ZodString;
+    recoveryHint: z.ZodOptional<z.ZodString>;
+    verification_shadow: z.ZodOptional<z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    check: {
+        type: "reject-if-match" | "reject-if-no-match";
+        pattern: string;
+    };
+    message: string;
+    id: string;
+    trigger: {
+        tool: string;
+        pattern: string;
+    };
+    recoveryHint?: string | undefined;
+    verification_shadow?: unknown;
+}, {
+    check: {
+        type: "reject-if-match" | "reject-if-no-match";
+        pattern: string;
+    };
+    message: string;
+    id: string;
+    trigger: {
+        tool: string;
+        pattern: string;
+    };
+    recoveryHint?: string | undefined;
+    verification_shadow?: unknown;
+}>;
+export type HookRule = z.infer<typeof HookRuleSchema>;
+export declare const HOOKS_YAML_SCHEMA_VERSION: 1;
+/**
+ * Per-pack `hooks.yaml` file shape. The `version` field is the contract
+ * for forward-compat: when `totem sync` parses an unknown version (higher
+ * than the runner supports), it warns-and-skips that pack entirely
+ * (ADR-104 § Decision 4).
+ */
+export declare const HooksYamlSchema: z.ZodEffects<z.ZodObject<{
+    version: z.ZodNumber;
+    hooks: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        trigger: z.ZodObject<{
+            tool: z.ZodString;
+            pattern: z.ZodEffects<z.ZodString, string, string>;
+        }, "strip", z.ZodTypeAny, {
+            tool: string;
+            pattern: string;
+        }, {
+            tool: string;
+            pattern: string;
+        }>;
+        check: z.ZodObject<{
+            pattern: z.ZodEffects<z.ZodString, string, string>;
+            type: z.ZodEnum<["reject-if-match", "reject-if-no-match"]>;
+        }, "strip", z.ZodTypeAny, {
+            type: "reject-if-match" | "reject-if-no-match";
+            pattern: string;
+        }, {
+            type: "reject-if-match" | "reject-if-no-match";
+            pattern: string;
+        }>;
+        message: z.ZodString;
+        recoveryHint: z.ZodOptional<z.ZodString>;
+        verification_shadow: z.ZodOptional<z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        check: {
+            type: "reject-if-match" | "reject-if-no-match";
+            pattern: string;
+        };
+        message: string;
+        id: string;
+        trigger: {
+            tool: string;
+            pattern: string;
+        };
+        recoveryHint?: string | undefined;
+        verification_shadow?: unknown;
+    }, {
+        check: {
+            type: "reject-if-match" | "reject-if-no-match";
+            pattern: string;
+        };
+        message: string;
+        id: string;
+        trigger: {
+            tool: string;
+            pattern: string;
+        };
+        recoveryHint?: string | undefined;
+        verification_shadow?: unknown;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    hooks: {
+        check: {
+            type: "reject-if-match" | "reject-if-no-match";
+            pattern: string;
+        };
+        message: string;
+        id: string;
+        trigger: {
+            tool: string;
+            pattern: string;
+        };
+        recoveryHint?: string | undefined;
+        verification_shadow?: unknown;
+    }[];
+    version: number;
+}, {
+    hooks: {
+        check: {
+            type: "reject-if-match" | "reject-if-no-match";
+            pattern: string;
+        };
+        message: string;
+        id: string;
+        trigger: {
+            tool: string;
+            pattern: string;
+        };
+        recoveryHint?: string | undefined;
+        verification_shadow?: unknown;
+    }[];
+    version: number;
+}>, {
+    hooks: {
+        check: {
+            type: "reject-if-match" | "reject-if-no-match";
+            pattern: string;
+        };
+        message: string;
+        id: string;
+        trigger: {
+            tool: string;
+            pattern: string;
+        };
+        recoveryHint?: string | undefined;
+        verification_shadow?: unknown;
+    }[];
+    version: number;
+}, {
+    hooks: {
+        check: {
+            type: "reject-if-match" | "reject-if-no-match";
+            pattern: string;
+        };
+        message: string;
+        id: string;
+        trigger: {
+            tool: string;
+            pattern: string;
+        };
+        recoveryHint?: string | undefined;
+        verification_shadow?: unknown;
+    }[];
+    version: number;
+}>;
+export type HooksYaml = z.infer<typeof HooksYamlSchema>;
+export declare const COMPILED_HOOKS_SCHEMA_VERSION: 1;
+/**
+ * A compiled hook rule carries provenance (`packId`) so rejection messages
+ * can name `<packId>/<ruleId>` (ADR-104 § Decision 1) and so staleness
+ * checks can scope per-pack.
+ */
+export declare const CompiledHookRuleSchema: z.ZodObject<{
+    id: z.ZodString;
+    trigger: z.ZodObject<{
+        tool: z.ZodString;
+        pattern: z.ZodEffects<z.ZodString, string, string>;
+    }, "strip", z.ZodTypeAny, {
+        tool: string;
+        pattern: string;
+    }, {
+        tool: string;
+        pattern: string;
+    }>;
+    check: z.ZodObject<{
+        pattern: z.ZodEffects<z.ZodString, string, string>;
+        type: z.ZodEnum<["reject-if-match", "reject-if-no-match"]>;
+    }, "strip", z.ZodTypeAny, {
+        type: "reject-if-match" | "reject-if-no-match";
+        pattern: string;
+    }, {
+        type: "reject-if-match" | "reject-if-no-match";
+        pattern: string;
+    }>;
+    message: z.ZodString;
+    recoveryHint: z.ZodOptional<z.ZodString>;
+    verification_shadow: z.ZodOptional<z.ZodUnknown>;
+} & {
+    packId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    check: {
+        type: "reject-if-match" | "reject-if-no-match";
+        pattern: string;
+    };
+    message: string;
+    id: string;
+    trigger: {
+        tool: string;
+        pattern: string;
+    };
+    packId: string;
+    recoveryHint?: string | undefined;
+    verification_shadow?: unknown;
+}, {
+    check: {
+        type: "reject-if-match" | "reject-if-no-match";
+        pattern: string;
+    };
+    message: string;
+    id: string;
+    trigger: {
+        tool: string;
+        pattern: string;
+    };
+    packId: string;
+    recoveryHint?: string | undefined;
+    verification_shadow?: unknown;
+}>;
+export type CompiledHookRule = z.infer<typeof CompiledHookRuleSchema>;
+/**
+ * Runtime-surface manifest produced by `totem sync` and read on every
+ * `totem hook run` invocation. The metadata fields are load-bearing for
+ * ADR-104 § Decision 3 (staleness detection):
+ *
+ * - `schemaVersion`: bumps on breaking structural change to this manifest
+ * - `compiledAt`: ISO 8601 timestamp of last compile
+ * - `sourcePackVersions`: pack name → version at compile time; compared
+ *   against package.json resolutions to emit `[totem:hook-stale]` warnings
+ *   when packs have updated since last compile
+ */
+export declare const CompiledHooksManifestSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    compiledAt: z.ZodString;
+    sourcePackVersions: z.ZodRecord<z.ZodString, z.ZodString>;
+    hooks: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        trigger: z.ZodObject<{
+            tool: z.ZodString;
+            pattern: z.ZodEffects<z.ZodString, string, string>;
+        }, "strip", z.ZodTypeAny, {
+            tool: string;
+            pattern: string;
+        }, {
+            tool: string;
+            pattern: string;
+        }>;
+        check: z.ZodObject<{
+            pattern: z.ZodEffects<z.ZodString, string, string>;
+            type: z.ZodEnum<["reject-if-match", "reject-if-no-match"]>;
+        }, "strip", z.ZodTypeAny, {
+            type: "reject-if-match" | "reject-if-no-match";
+            pattern: string;
+        }, {
+            type: "reject-if-match" | "reject-if-no-match";
+            pattern: string;
+        }>;
+        message: z.ZodString;
+        recoveryHint: z.ZodOptional<z.ZodString>;
+        verification_shadow: z.ZodOptional<z.ZodUnknown>;
+    } & {
+        packId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        check: {
+            type: "reject-if-match" | "reject-if-no-match";
+            pattern: string;
+        };
+        message: string;
+        id: string;
+        trigger: {
+            tool: string;
+            pattern: string;
+        };
+        packId: string;
+        recoveryHint?: string | undefined;
+        verification_shadow?: unknown;
+    }, {
+        check: {
+            type: "reject-if-match" | "reject-if-no-match";
+            pattern: string;
+        };
+        message: string;
+        id: string;
+        trigger: {
+            tool: string;
+            pattern: string;
+        };
+        packId: string;
+        recoveryHint?: string | undefined;
+        verification_shadow?: unknown;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    hooks: {
+        check: {
+            type: "reject-if-match" | "reject-if-no-match";
+            pattern: string;
+        };
+        message: string;
+        id: string;
+        trigger: {
+            tool: string;
+            pattern: string;
+        };
+        packId: string;
+        recoveryHint?: string | undefined;
+        verification_shadow?: unknown;
+    }[];
+    schemaVersion: 1;
+    compiledAt: string;
+    sourcePackVersions: Record<string, string>;
+}, {
+    hooks: {
+        check: {
+            type: "reject-if-match" | "reject-if-no-match";
+            pattern: string;
+        };
+        message: string;
+        id: string;
+        trigger: {
+            tool: string;
+            pattern: string;
+        };
+        packId: string;
+        recoveryHint?: string | undefined;
+        verification_shadow?: unknown;
+    }[];
+    schemaVersion: 1;
+    compiledAt: string;
+    sourcePackVersions: Record<string, string>;
+}>;
+export type CompiledHooksManifest = z.infer<typeof CompiledHooksManifestSchema>;
+export {};
+//# sourceMappingURL=schema.d.ts.map