@blundergoat/goat-flow
Version:
AI coding agent harness and local dashboard for Claude Code, OpenAI Codex, Google Antigravity, and GitHub Copilot - setup audits, guardrails, structured skills, deny hooks, and persistent learning loops.
58 lines • 3.01 kB
TypeScript
/**
* Evidence-provenance schema for audit checks.
*
* Co-located with each check's implementation so provenance travels with the
* check and can't drift from its source. Defined here as the stable import
* path so back-fill work can consume it without redefining.
*
* Schema adapted from agnix rules.json + rust emission in
* `/home/devgoat/projects/goat-flow-related/agnix/crates/agnix-core/`.
*
* The `"unknown"` source_type + required `reason` field is the critique-locked
* escape hatch: existing checks include historical entries that cannot
* have their provenance reconstructed. Such checks declare `source_type:
* "unknown"` and state the reason (e.g. "pre-dates v1.1.0 cleanup"),
* rather than fabricating a citation or stalling the back-fill.
*/
/** Where a check's norm came from. */
type ProvenanceSource = "spec" | "vendor_docs" | "paper" | "incident" | "community" | "unknown";
/**
* Strength of the rule the check enforces.
* - MUST: violation is a failure (fail the scope).
* - SHOULD: violation is a WARN finding; fails the scope.
* - BEST_PRACTICE: violation is an INFO finding; logged but does not fail.
*/
type NormativeLevel = "MUST" | "SHOULD" | "BEST_PRACTICE";
/** Evidence metadata for an audit check. Co-located with the check definition. */
export interface CheckEvidence {
source_type: ProvenanceSource;
/** URLs to specs, vendor docs, papers, or incident trails. Empty for `incident` if the citation is a footgun/lesson path in `evidence_paths`. */
source_urls: string[];
/** ISO-8601 date the evidence was last verified (YYYY-MM-DD). */
verified_on: string;
normative_level: NormativeLevel;
/** Optional repo-local paths (e.g. `.goat-flow/learning-loop/footguns/...`, session log) that back the check. */
evidence_paths?: string[];
/** Evidence paths that resolve against the goat-flow framework/package, not the audited target project. */
framework_evidence_paths?: string[];
/** Evidence paths that resolve against the audited target project. */
target_evidence_paths?: string[];
/**
* Required when `source_type === "unknown"`. Explains why the provenance
* can't be reconstructed. The type system does not enforce this because
* it depends on a runtime field; `validateProvenance` below does.
*/
reason?: string;
}
/** Filesystem lookup used to verify repo-local evidence paths when available. */
type EvidencePathExists = (path: string) => boolean;
/**
* Runtime check that a CheckEvidence record satisfies the audit schema.
*
* @param evidence - Provenance record attached to an audit check or runtime event.
* @param pathExists - Optional resolver used by development/preflight checks to reject stale local evidence paths.
* @returns Validation errors; an empty array means the record is usable.
*/
export declare function validateProvenance(evidence: CheckEvidence, pathExists?: EvidencePathExists): string[];
export {};
//# sourceMappingURL=provenance-types.d.ts.map