@lannguyensi/harness 0.63.0 → 1.0.0

package/dist/runtime/workflow-policies.d.ts

@@ -1,207 +0,0 @@
-import type { Manifest, Policy, Workflow } from "../schema/index.js";
-/**
- * Runtime enforcement for `workflows:` (99f47307, Slice 1).
- *
- * `manifest.workflows[]` describes a review-then-merge process (schema:
- * `src/schema/workflows.ts`), but until now nothing read it at
- * enforcement time: `src/runtime/intercept.ts` (the Risk Gate / policy
- * engine `harness policy intercept` runs on every PreToolUse) only ever
- * evaluates `manifest.policies[]`. A `workflows:` declaration alone was
- * documentation, not a gate (`docs/for-agents.md`, pre-Slice-1 wording:
- * "The schema cannot enforce that today").
- *
- * This module closes that gap for exactly ONE step pairing: a
- * `review_subagent` step with `spawn: "required"` followed (at any
- * later index in the same workflow) by a `merge` step. When BOTH
- * `require-review-evidence` and `require-review-evidence-bash` are
- * declared in `manifest.hooks[]`, `deriveWorkflowGatePolicies` returns
- * the SAME policies `harness init --template full` would hand-author
- * (`src/cli/init/templates.ts` `review-before-merge` /
- * `review-before-merge-bash`), renamed per workflow so the provenance
- * is visible in `harness list policies` / `harness explain`.
- *
- * Task 2699b476 added the two task-scoped merge surfaces to that set:
- * `review-before-task-merge` (`mcp__agent-tasks__task_merge`) and
- * `review-before-task-finish-automerge`
- * (`mcp__agent-tasks__task_finish` narrowed by `trigger.input_match` to
- * `autoMerge: true`), each derived only when its own hook
- * (`require-review-evidence-task-merge` /
- * `require-review-evidence-task-finish`) is declared. A manifest that
- * predates those hooks derives exactly the pair it always did.
- *
- * Deliberately does NOT touch `src/runtime/intercept.ts`: the engine
- * already knows how to evaluate a `Policy`, so the only thing missing
- * was a `Policy` to hand it. `src/cli/loader.ts#loadManifest` calls
- * `withDerivedPolicies` after parsing and appends the result to
- * `manifest.policies` before any consumer (the CLI `policy intercept`
- * entrypoint, `list`, `explain`, `explain-policy`) reads it.
- *
- * TWO VIEWS OF ONE MANIFEST (review round 3, 99f47307 Slice 1). Every
- * reader of a parsed manifest sees exactly one of:
- *
- * - the HAND-AUTHORED view: `parseManifest(...)` as-is, only what the
- *   operator wrote under `policies:`. Right for anything that writes a
- *   manifest back to disk or serialises it for later comparison
- *   (`harness export`, the `.last-apply` manifest snapshot, `add` /
- *   `remove` / `adopt` / `pack reseed` file rewrites, the schema gate in
- *   `io/validate-before-write.ts`), because a derived policy written out
- *   as if hand-authored would be re-derived on top of itself next time.
- *   `withoutDerivedPolicies` turns a derived view back into this one.
- * - the DERIVED view: `withDerivedPolicies(parseManifest(...))`, hand-
- *   authored policies plus the workflow gate pair. Right for enforcement
- *   (`policy intercept`, hook entrypoints), validation (`validate`,
- *   `doctor`, `add`'s asset gate), display (`list`, `explain[-policy]`,
- *   `describe`, `dry-run`), and every COMPARISON where the other side is
- *   also derived (`diff --since` ref side vs working side; the
- *   `.last-apply` snapshot vs the current manifest in restart hints).
- *   `loadManifest` hands out this view; the few readers that parse
- *   without it (`validate`, `diff`'s ref side, `apply`'s snapshot
- *   reader, `add`'s gate) call `withDerivedPolicies` themselves.
- *
- * Both helpers are idempotent and accept either view as input (they
- * partition on `isDerivedPolicy`), so a reader can never "double derive"
- * or strip a hand-authored policy by calling them on the wrong view.
- * Review rounds 1 and 2 each found one reader on the wrong side of this
- * line (`apply` vs `validate`; `diff --since`'s two sides); the table
- * above plus tests/cli/manifest-view-parity.test.ts are the guard.
- *
- * Fail direction: when the two evidence hooks are NOT wired, this
- * returns `[]` for every workflow rather than deriving an
- * unenforceable policy (there would be no hook name to bind it to, and
- * `manifest.policies[].hook` must reference a declared hook, see
- * `ManifestSchema`'s superRefine in `src/schema/index.ts`). That silent
- * non-enforcement case is exactly what `checkWorkflowGateWiring`
- * (`src/cli/validate/checks.ts`) turns into a loud `validate` error, so
- * "declared `spawn: required`, gate never wired" cannot pass silently.
- */
-/** The two hooks templates.ts wires for the hand-authored merge gate. */
-export declare const REVIEW_EVIDENCE_HOOK_MCP = "require-review-evidence";
-export declare const REVIEW_EVIDENCE_HOOK_BASH = "require-review-evidence-bash";
-/**
- * The two hooks templates.ts wires for the task-scoped merge surfaces
- * (task 2699b476). Unlike the pair above these are NOT part of
- * `hasWiredMergeGateHooks`: a manifest that predates them still derives
- * the `pull_requests_merge` / `gh pr merge` gates exactly as before, and
- * each task-scoped gate is derived only when ITS OWN hook is declared.
- *
- * That per-hook gating is not a style choice. A derived policy's `hook:`
- * must name a declared hook (`ManifestSchema`'s superRefine), and, more
- * importantly, the hook's `match` is what `harness apply` projects into
- * settings.json's tool-name matcher: without a matcher for
- * `mcp__agent-tasks__task_merge`, Claude Code never spawns `harness
- * policy intercept` for that verb, so a gate derived anyway would be
- * INERT while looking enforced in `harness list policies` (the exact
- * "No-Op that LOOKS protective" shape `checkWorkflowGateWiring` exists
- * to prevent). Deriving nothing until the hook is wired keeps the
- * absence visible instead of fake-covering it.
- */
-export declare const REVIEW_EVIDENCE_HOOK_TASK_MERGE = "require-review-evidence-task-merge";
-export declare const REVIEW_EVIDENCE_HOOK_TASK_FINISH = "require-review-evidence-task-finish";
-export declare const MERGE_MCP_MATCH = "mcp__agent-tasks__pull_requests_merge";
-export declare const MERGE_BASH_MATCH = "(^|\\n|;|\\||&|\\()\\s*(\\w+=\\S+\\s+)*gh pr merge\\b";
-export declare const TASK_MERGE_MCP_MATCH = "mcp__agent-tasks__task_merge";
-export declare const TASK_FINISH_MCP_MATCH = "mcp__agent-tasks__task_finish";
-/**
- * The `trigger.input_match` predicate that separates the merging mode of
- * `task_finish` from the ordinary one. Both auto-merge modes the MCP
- * server documents (soloMode work claim, review claim + approve) carry
- * `autoMerge: true`; a plain finish omits the argument entirely, and a
- * missing path never satisfies an `input_match` entry, so the gate stays
- * out of the way of the non-merging call.
- */
-export declare const TASK_FINISH_AUTOMERGE_INPUT_MATCH: Record<string, boolean>;
-/** `toolArgs.taskId` is the only identifier either task-scoped verb carries. */
-export declare const TASK_ID_EXTRACT: Record<string, string>;
-export declare const PR_NUMBER_EXTRACT: Record<string, string>;
-/**
- * True when `workflow.steps` contains a `review_subagent` step with
- * `spawn: "required"` at an index earlier than some `merge` step
- * (not necessarily adjacent; a `ci_gate` or another step may sit
- * between them). A workflow with no `merge` step at all, or whose only
- * `review_subagent` steps are `spawn: "optional"` / `"skip"`, returns
- * `false`.
- */
-export declare function workflowRequiresMergeGate(workflow: Workflow): boolean;
-/** True when both merge-gate evidence hooks are declared in `manifest.hooks[]`. */
-export declare function hasWiredMergeGateHooks(manifest: Manifest): boolean;
-/** True when `policy` is an object this module derived (see `withDerivedPolicies`). */
-export declare function isDerivedPolicy(policy: Policy): boolean;
-/**
- * The hand-authored slice of `manifest.policies`: everything the operator
- * wrote under `policies:`, none of the workflow-derived entries. Works on
- * either view (see module doc); on a hand-authored view it is the
- * identity.
- */
-export declare function handAuthoredPolicies(manifest: Manifest): Policy[];
-/** One weaker hand-authored policy sharing a derived gate's trigger surface. */
-export interface WeakGatePolicyOverlap {
-    /** The workflow whose `spawn: "required"` step derives the gate. */
-    workflowName: string;
-    /** Name of the derived policy that is ALSO in force (`workflow:<name>:review-before-merge[-bash]`). */
-    derivedPolicyName: string;
-    /** Human-readable surface label for the message (`mcp__agent-tasks__pull_requests_merge` or `` `gh pr merge` (Bash) ``). */
-    surface: string;
-    /** The weaker hand-authored policy's name. */
-    handPolicyName: string;
-    /** Why it does not stand in for the derived gate (see `nonEquivalenceReason`). */
-    reason: string;
-}
-/**
- * Derive the merge-gate `Policy` pair for every workflow that needs one
- * and does not already have an equivalent policy (hand-authored, or
- * derived from an earlier workflow in the same manifest) intercepting
- * the same surface for the same evidence tag.
- *
- * Returns `[]` when `manifest.hooks[]` is missing either evidence hook
- * (see module doc: that gap is a `validate` error, not silent
- * derivation of an unenforceable policy) or when no workflow declares
- * a `spawn: "required"` review step followed by a merge step.
- */
-export declare function deriveWorkflowGatePolicies(manifest: Manifest): Policy[];
-/**
- * Every hand-authored policy that shares an ACTUALLY DERIVED gate's
- * trigger surface + ledger_tag but does not stand in for it: weaker
- * (F1, review round 2) or extracting its variables differently (F4,
- * review round 3). Both policies apply in that case, and the overlap is
- * worth flagging: an operator reading `enforcement: warn` on a
- * `two-reviewers-required`-shaped policy might reasonably believe THAT
- * is the only gate on the surface. `src/cli/validate/checks.ts` turns
- * each entry into a warning Diagnostic; `src/cli/doctor/index.ts`
- * renders the same list in the Workflows section.
- *
- * Mirrors `deriveWorkflowGatePolicies` exactly (same walk, same `seen`
- * set): a surface an equivalent hand-authored policy already covers
- * derives nothing and therefore reports nothing, even when a second,
- * weaker policy sits on it too. Returns `[]` when the evidence hooks are
- * not wired or no workflow needs a gate.
- */
-export declare function findWeakGatePolicyOverlaps(manifest: Manifest): WeakGatePolicyOverlap[];
-/**
- * The ONE place `workflows[]` gets folded into `manifest.policies` (F2,
- * review round 2). Before this, `src/cli/loader.ts#loadManifest` inlined
- * the append, so every OTHER manifest consumer that parses the manifest
- * a different way (`src/cli/validate/index.ts`'s `loadMergedRaw` +
- * `parseManifest`, notably) saw a manifest with no derived policies at
- * all, and `apply` and `validate` diverged. See the module doc for the
- * full list of readers and which view each one takes.
- *
- * Idempotent and view-agnostic (review round 3): the derivation runs on
- * `handAuthoredPolicies(manifest)` only and any derived entries already
- * present are replaced, so calling this on an already-derived view yields
- * the same policy names with no duplicates. Returns the input object
- * unchanged when there is nothing to derive and nothing to replace.
- *
- * Registers each derived `Policy` object in the module-level
- * `derivedPolicyRegistry` (F7) so `isDerivedPolicy` can later distinguish
- * it from a hand-authored one (used by `harness export`'s filter and
- * `list`/`doctor`'s "(derived from workflows[])" marker).
- */
-export declare function withDerivedPolicies(manifest: Manifest): Manifest;
-/**
- * The hand-authored view of a manifest that may carry derived policies:
- * what `harness export` emits and what the `.last-apply` manifest
- * snapshot stores, so nothing that gets written out or re-read later
- * carries a derived policy as if the operator had declared it. Returns
- * the input object unchanged when it carries no derived policy.
- */
-export declare function withoutDerivedPolicies(manifest: Manifest): Manifest;