@open-agent-toolkit/cli 0.3.19 → 0.3.21

package/dist/commands/project/delivery/evidence.d.ts

@@ -0,0 +1,171 @@
+import type { GitRunner } from '../../project/sync/git.js';
+import { type GoalDelivery, type MilestoneGateCarrier, type ReviewStatus } from '@open-agent-toolkit/control-plane';
+/**
+ * The shared delivery-evidence evaluator (design "Delivery registry and
+ * closeout boundary", bookkeeping-successor freshness, A2). `delivery
+ * refresh`, `delivery check` and the closeout boundary all derive freshness
+ * here; nothing else compares revisions.
+ *
+ * Evidence keeps the revision actually reviewed. Evidence reviewed at R covers
+ * a published head H when R = H, or when R is an ancestor of H and every
+ * intervening commit — merge-introduced changes included — changes only
+ * permitted bookkeeping. Each commit is inspected on its own, so a substantive
+ * change followed by its revert is never a bookkeeping successor. Missing
+ * objects, failed inspection, unknown paths and disallowed edits fail closed.
+ */
+/** Where the evidence lives: the project and the review artifacts it records. */
+export interface EvidenceScope {
+    /** Absolute repository root; every Git command runs here. */
+    repoRoot: string;
+    /** Repository-relative POSIX path of the project directory. */
+    projectDir: string;
+    /**
+     * Project-relative review artifacts belonging to the evidence being
+     * recorded or archived (`reviews/…`). Each also permits its archived
+     * counterpart (`reviews/archived/<name>`), so receive's archival move is
+     * bookkeeping.
+     */
+    evidenceArtifacts: readonly string[];
+    /**
+     * Each delivery's OWN review artifacts: the artifacts its own Reviews rows
+     * record (Scope cell = the delivery ID or its milestone), keyed by delivery
+     * ID and kept apart from the shared allowlist above. Never derived from the
+     * registry's `integrated_review.artifact`, which is the very pointer a
+     * judged commit may rewrite. Only a new artifact from this set may replace a
+     * delivery's review identity or member revisions, so a sharing sibling's
+     * artifact (admitted by the allowlist as bookkeeping) or an artifact no
+     * Reviews row records never unlocks them. A delivery with no entry unlocks
+     * nothing.
+     */
+    ownEvidenceArtifacts?: ReadonlyMap<string, readonly string[]>;
+}
+export type FreshnessFailureCode = 'missing-revision' | 'missing-object' | 'not-ancestor' | 'inspection-failed' | 'disallowed-path' | 'substantive-change' | 'base-changed';
+export type SuccessorResult = {
+    fresh: true;
+    code: 'identical' | 'bookkeeping-successor';
+    reason: string;
+    /** Every commit inspected between the reviewed and published heads. */
+    inspected: string[];
+} | {
+    fresh: false;
+    code: FreshnessFailureCode;
+    reason: string;
+    commit?: string;
+    path?: string;
+};
+/**
+ * Whether `published` covers evidence reviewed at `reviewed` under the
+ * bookkeeping-successor contract.
+ */
+export declare function evaluateSuccessor(git: GitRunner, scope: EvidenceScope, reviewed: string | null | undefined, published: string | null | undefined): Promise<SuccessorResult>;
+export type BookkeepingPathKind = 'state' | 'plan' | 'implementation' | 'project-log' | 'summary' | 'review-artifact';
+/**
+ * The bookkeeping kind of a repository-relative path, or `null` when the
+ * path is outside the allowlist: this project's `state.md`, `plan.md`,
+ * `implementation.md`, `project-log.md`, `summary.md`, and the exact review
+ * artifacts of the evidence being recorded or archived (including those of
+ * deliveries that share its member pull request).
+ */
+export declare function classifyPath(scope: EvidenceScope, repoPath: string): BookkeepingPathKind | null;
+/**
+ * Whether `after` only adds entries to the project log `before`. `oat project
+ * log append` writes at the end of the log, or, once the log carries its
+ * end-of-run synthesis section, immediately before that section; every byte
+ * of the previous log is kept either way. Insertion anywhere else, a change to
+ * an existing entry, or a change to the synthesis section is a rewrite.
+ */
+export declare function isProjectLogAppend(before: string, after: string): boolean;
+export interface CarrierExpectation {
+    /** The subject kind the carrier must bind. */
+    kind: 'plan' | 'code';
+    /** The ordered phase set the carrier's resolution must apply to. */
+    scope: readonly string[];
+    /**
+     * `exact` (default): the carrier binds exactly `scope`, as a milestone's
+     * scoped closeout records it. `covers`: the carrier binds at least every
+     * phase of `scope`, as a delivery's milestone carrier does after a later
+     * correction phase joined its milestone.
+     */
+    match?: 'exact' | 'covers';
+    /** Whether the project override currently disables the carrier's gate. */
+    overrideDisabled?: boolean | null;
+    /** The current resolution, when the caller resolved configuration. */
+    resolution?: string | null;
+    /** The current configuration fingerprint, when the caller computed one. */
+    configFingerprint?: string | null;
+}
+export interface CarrierEvaluation {
+    /** The recorded gate outcome, independent of freshness. */
+    outcome: 'allowed' | 'blocked' | 'missing' | 'invalid';
+    freshness: 'fresh' | 'stale';
+    reason: string | null;
+}
+/**
+ * Evaluate one gate carrier (A2). The outcome is the recorded status; the
+ * freshness asks whether that resolution still applies: a `no_gate` or
+ * `project_disabled` carrier has no reviewed revision and is bound by its
+ * subject, so a changed configuration, override or subject makes it stale and
+ * a fabricated `reviewed_head` makes it invalid. A configured code carrier
+ * keeps its actual reviewed revision and must cover every published head as
+ * a bookkeeping successor. A plan carrier binds the approved brief and
+ * membership at activation, so implementation commits never stale it.
+ */
+export declare function evaluateGateCarrier(carrier: MilestoneGateCarrier | null, expected: CarrierExpectation, successor?: {
+    git: GitRunner;
+    scope: EvidenceScope;
+    publishedHeads: readonly (string | null)[];
+}): Promise<CarrierEvaluation>;
+export interface ReviewEvaluation {
+    artifact: string | null;
+    /** The recorded disposition or Reviews-row status, as stored. */
+    disposition: string | null;
+    fresh: boolean;
+    reason: string | null;
+    /** Every published head is covered by the reviewed revision. */
+    members: {
+        member: number;
+        fresh: boolean;
+        reason: string | null;
+    }[];
+}
+/**
+ * Evaluate a registered delivery's integrated review against its observed
+ * members (A2): each member's reviewed revision must cover its observed head
+ * as a bookkeeping successor, and a member base change invalidates the
+ * evidence independently. The review must bind every phase of
+ * `requiredScope`. Historical deliveries are judged against their own
+ * observed revisions, never the branch's latest head.
+ */
+export declare function evaluateDeliveryReview(git: GitRunner, scope: EvidenceScope, delivery: GoalDelivery, requiredScope: readonly string[]): Promise<ReviewEvaluation>;
+/**
+ * Review artifacts a delivery's evidence records, for the bookkeeping
+ * allowlist. `sharing` lists the deliveries that share one of its member pull
+ * requests (terminal deliveries registered from one head branch, brief
+ * contract 12.7 "Shared members"): their review artifacts are recorded on the
+ * same member head, so they are bookkeeping for this delivery as well. Each
+ * delivery is still judged on its own frozen scope and bound revisions.
+ */
+export declare function deliveryEvidenceArtifacts(delivery: GoalDelivery, reviewRowArtifacts?: readonly string[], sharing?: readonly GoalDelivery[]): string[];
+/** Code review rows whose Scope cell names a label (the bare id or `<id>: …`). */
+export declare function reviewRowsFor(reviews: readonly ReviewStatus[], labels: readonly string[]): ReviewStatus[];
+/** The project facts the evidence scope of a delivery is built from. */
+export interface DeliveryEvidenceProject {
+    repoRoot: string;
+    projectDir: string;
+    state: {
+        reviews: readonly ReviewStatus[];
+    };
+}
+/**
+ * The one evidence scope for a registered delivery, shared by `delivery
+ * check`, `delivery refresh` and the closeout boundary: the review rows
+ * labelled with the delivery, its milestone and every delivery sharing one of
+ * its member pull requests, plus their integrated-review artifacts.
+ */
+export declare function deliveryEvidenceScope(project: DeliveryEvidenceProject, deliveries: readonly GoalDelivery[], delivery: GoalDelivery): EvidenceScope;
+/**
+ * The other registered deliveries that share at least one member pull request
+ * URL with `delivery` (brief contract 12.7 "Shared members").
+ */
+export declare function deliveriesSharingMembers(deliveries: readonly GoalDelivery[], delivery: GoalDelivery): GoalDelivery[];
+//# sourceMappingURL=evidence.d.ts.map

package/dist/commands/project/delivery/evidence.d.ts.map

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