@neurcode-ai/governance-runtime 0.1.3 → 0.1.5

package/dist/agent-plan.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Agent Plan Capture V1
+ *
+ * Source-free model of the *agent's own stated plan* during an agentic coding
+ * session. This is intentionally distinct from the V0 diff-based plan
+ * verification primitives in `./index.ts` (PlanVerification*, PlanDiffFile,
+ * etc.). Here we capture what the agent *said it would do* so the runtime can
+ * answer: "is the agent still executing its own plan, or has it started making
+ * changes its plan never justified?"
+ *
+ * Hard rules honored by this module:
+ *  - Never store source code, diffs, patches, or file contents. Only file path
+ *    references, globs, and short natural-language summaries the agent emitted.
+ *  - Extraction is conservative: when no plan is present we return null rather
+ *    than inventing one, and a bare user prompt is never treated as an agent
+ *    plan.
+ *  - Everything is deterministic (no model calls, no randomness).
+ */
+export type AgentPlanSource = 'claude_prompt' | 'manual' | 'mcp' | 'unknown';
+export type AgentPlanConfidence = 'high' | 'medium' | 'low';
+export declare const AGENT_PLAN_SCHEMA_VERSION: 1;
+export interface AgentPlan {
+    schemaVersion: number;
+    /** Short natural-language description of the plan (source-free). */
+    summary: string;
+    /** Ordered plan steps as short text lines (source-free). */
+    steps: string[];
+    /** Concrete file paths the plan expects to touch. */
+    expectedFiles: string[];
+    /** Glob patterns the plan expects to touch. */
+    expectedGlobs: string[];
+    /** Stated constraints / guardrails the agent committed to. */
+    constraints: string[];
+    /** Stated risks / caveats the agent called out. */
+    risks: string[];
+    /** ISO-8601 timestamp of when the plan was captured. */
+    capturedAt: string;
+    source: AgentPlanSource;
+    confidence: AgentPlanConfidence;
+}
+export type PlanCoherenceVerdict = 'planned' | 'implied' | 'unplanned' | 'unknown';
+export interface PlanCoherenceResult {
+    verdict: PlanCoherenceVerdict;
+    /** 0-100; higher means the edit is better justified by the agent's plan. */
+    score: number;
+    /** Plan items (file/glob/step text) that matched the edited path. */
+    matchedPlanItems: string[];
+    /** Human-readable, deterministic explanation lines. */
+    reasons: string[];
+}
+export interface PlanCoherenceInput {
+    /** The captured agent plan, if any. */
+    agentPlan?: AgentPlan | null;
+    /** Repo-relative path being edited. */
+    filePath: string;
+    /**
+     * Support paths derived from the *user intent* contract (e.g. globs the
+     * intent allows as supporting work). Kept as an input so this module stays
+     * decoupled from the intent-contract shape.
+     */
+    intentSupportGlobs?: string[];
+    /**
+     * Explicit override for whether the plan implies support work (tests,
+     * utilities, refactors). When omitted we infer it deterministically from the
+     * plan text.
+     */
+    planImpliesSupportWork?: boolean;
+}
+/**
+ * Extract expected file paths and globs from free-form plan text. We only look
+ * at backtick code spans and whitespace-delimited tokens that pass strict
+ * path/glob shape checks — never arbitrary words.
+ */
+export declare function extractExpectedTargetsFromText(text: string): {
+    expectedFiles: string[];
+    expectedGlobs: string[];
+};
+/** Parse ordered/checklist step lines out of a markdown-ish block. */
+export declare function parsePlanSteps(text: string): string[];
+/** Does the plan text imply legitimate supporting work (tests/utils/refactor)? */
+export declare function planImpliesSupportWork(plan: AgentPlan | null | undefined): boolean;
+/** Is this path a conventional test or utility/support file? */
+export declare function isTestOrUtilityPath(filePath: string): boolean;
+/**
+ * Deterministically grade an edit against the agent's plan.
+ *
+ * Verdict precedence:
+ *  1. No agent plan captured           -> unknown
+ *  2. Path matches expectedFiles/globs -> planned
+ *  3. Path is intent-support/test/util AND plan implies support work -> implied
+ *  4. Otherwise                        -> unplanned
+ *
+ * NOTE: this is advisory in V1. Boundary/approval blocks always override this
+ * verdict at the call sites; an `unplanned` verdict alone must not block.
+ */
+export declare function evaluatePlanCoherence(input: PlanCoherenceInput): PlanCoherenceResult;
+export interface ExtractAgentPlanOptions {
+    /** Override capture timestamp (mainly for deterministic tests). */
+    now?: Date;
+    /** Override the recorded source (e.g. 'mcp' when called from the MCP server). */
+    source?: AgentPlanSource;
+}
+/**
+ * Deterministically extract an {@link AgentPlan} from a Claude Code hook
+ * payload. Returns null when no plan is present — callers must treat a null
+ * result as "no plan", never as a failure.
+ *
+ * This function never throws: any malformed payload yields null.
+ */
+export declare function extractAgentPlan(payload: unknown, options?: ExtractAgentPlanOptions): AgentPlan | null;
+/**
+ * Source-free projection of an agent plan for live sync / evidence export.
+ * Drops nothing sensitive (the model is already source-free) but enforces the
+ * shape and trims away anything unexpected callers may have attached.
+ */
+export declare function sanitizeAgentPlan(value: unknown): AgentPlan | undefined;
+/** Sanitize a plan-coherence result coming back over the wire. */
+export declare function sanitizePlanCoherence(value: unknown): PlanCoherenceResult | undefined;
+//# sourceMappingURL=agent-plan.d.ts.map

package/dist/agent-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-plan.d.ts","sourceRoot":"","sources":["../src/agent-plan.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,MAAM,eAAe,GAAG,eAAe,GAAG,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;AAC7E,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAE5D,eAAO,MAAM,yBAAyB,EAAG,CAAU,CAAC;AAEpD,MAAM,WAAW,SAAS;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,qDAAqD;IACrD,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,+CAA+C;IAC/C,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mDAAmD;IACnD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,eAAe,CAAC;IACxB,UAAU,EAAE,mBAAmB,CAAC;CACjC;AAED,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;AAEnF,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,oBAAoB,CAAC;IAC9B,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,uDAAuD;IACvD,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,uCAAuC;IACvC,SAAS,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAC7B,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAwED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,MAAM,GAAG;IAC5D,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB,CA0CA;AAMD,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAcrD;AAyCD,kFAAkF;AAClF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAMlF;AAkBD,gEAAgE;AAChE,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAM7D;AAuBD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,kBAAkB,GAAG,mBAAmB,CAuFpF;AAoKD,MAAM,WAAW,uBAAuB;IACtC,mEAAmE;IACnE,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,iFAAiF;IACjF,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,uBAA4B,GACpC,SAAS,GAAG,IAAI,CAwDlB;AAcD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CA4CvE;AAED,kEAAkE;AAClE,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,GAAG,SAAS,CAoBrF"}