audit-tools 0.28.0

package/dist/audit/orchestrator/dependencyMap.js

@@ -0,0 +1,193 @@
+import { AGENT_FEEDBACK_FILENAME } from "audit-tools/shared";
+/**
+ * THE single canonical staleness DAG (ARC-cebe3421).
+ *
+ * Keyed by an artifact → the list of artifacts it DEPENDS ON (its upstream
+ * inputs). When any upstream input's content hash or revision changes, this
+ * artifact is stale and must be rebuilt. This is the natural direction for
+ * `computeArtifactMetadata` (which records each artifact's dependency
+ * revisions) and reduces stale detection to a single revision/hash compare
+ * against the recorded upstream revisions.
+ *
+ * The forward "X → its dependents" view (`ARTIFACT_DEPENDENTS_MAP`, used by
+ * `computeStaleArtifacts` to propagate staleness downstream) is DERIVED from
+ * this table by `invertDependencyMap` — it is not maintained separately, so the
+ * two can never drift. There is exactly one hand-authored adjacency
+ * representation; everything else is computed from it.
+ *
+ * `satisfies` (rather than a type annotation) keeps the literal's precise keys
+ * for downstream `keyof`-style derivations while still type-checking every key
+ * and value against the known artifact filenames.
+ */
+export const ARTIFACT_DEPENDS_ON_MAP = {
+    // Phase 1 — intake. repo_manifest is rebuilt when the tooling/environment
+    // probe changes (a different analyzer version can classify files differently).
+    "repo_manifest.json": ["tooling_manifest.json"],
+    "file_disposition.json": ["repo_manifest.json"],
+    // Phase 2 — structure. The graph is rebuilt from the manifest + disposition;
+    // the optional analyzer-enrichment marker tracks the post-enrichment graph.
+    // No cycle: the enrichment executor writes graph_bundle AND the marker in one
+    // advanceAudit call, and computeArtifactMetadata is dependency-first, so the
+    // marker records the post-enrichment graph_bundle revision (mirrors
+    // audit-findings → narrative).
+    "graph_bundle.json": ["repo_manifest.json", "file_disposition.json"],
+    "analyzer_capability.json": ["graph_bundle.json"],
+    "unit_manifest.json": ["repo_manifest.json", "file_disposition.json"],
+    "surface_manifest.json": ["repo_manifest.json", "file_disposition.json"],
+    "critical_flows.json": [
+        "repo_manifest.json",
+        "file_disposition.json",
+        "surface_manifest.json",
+    ],
+    "risk_register.json": [
+        "repo_manifest.json",
+        "file_disposition.json",
+        "unit_manifest.json",
+        "surface_manifest.json",
+        "critical_flows.json",
+    ],
+    "design_assessment.json": ["unit_manifest.json", "critical_flows.json"],
+    // Phase 3 — planning & execution. scope.json (delta vs. full) gates coverage;
+    // it is also a DIRECT input to audit_tasks so a scope change that produces an
+    // identical coverage_matrix (same files/buckets) still re-stales tasks
+    // (ARC-cebe3421-3) — the transitive scope→coverage_matrix→audit_tasks path
+    // only fires when coverage_matrix content changes. No cycle: planning writes
+    // scope.json, coverage_matrix.json, and audit_tasks.json in one advanceAudit
+    // call, dependency-first.
+    "coverage_matrix.json": [
+        "repo_manifest.json",
+        "file_disposition.json",
+        "unit_manifest.json",
+        "intent_checkpoint.json",
+        "external_analyzer_results.json",
+        "scope.json",
+        "audit_results.jsonl",
+    ],
+    "audit_tasks.json": [
+        "repo_manifest.json",
+        "file_disposition.json",
+        "unit_manifest.json",
+        "critical_flows.json",
+        "intent_checkpoint.json",
+        "external_analyzer_results.json",
+        "scope.json",
+    ],
+    "audit_plan_metrics.json": [
+        "repo_manifest.json",
+        "file_disposition.json",
+        "unit_manifest.json",
+        "critical_flows.json",
+        "intent_checkpoint.json",
+        "external_analyzer_results.json",
+        "coverage_matrix.json",
+        "audit_tasks.json",
+        "audit_results.jsonl",
+    ],
+    // Provider-neutral task-affinity graph derived from audit_tasks (Phase A of
+    // the plan/dispatch seam). Dispatch partitions it just-in-time and persists
+    // nothing back. See docs/audit-workflow-design.md.
+    "task_affinity_graph.json": ["audit_tasks.json"],
+    "flow_coverage.json": [
+        "repo_manifest.json",
+        "file_disposition.json",
+        "critical_flows.json",
+        "external_analyzer_results.json",
+        "coverage_matrix.json",
+        "audit_results.jsonl",
+    ],
+    "requeue_tasks.json": [
+        "repo_manifest.json",
+        "file_disposition.json",
+        "unit_manifest.json",
+        "critical_flows.json",
+        "intent_checkpoint.json",
+        "external_analyzer_results.json",
+        "coverage_matrix.json",
+        "flow_coverage.json",
+        "audit_results.jsonl",
+    ],
+    "runtime_validation_tasks.json": [
+        "repo_manifest.json",
+        "file_disposition.json",
+        "unit_manifest.json",
+        "surface_manifest.json",
+        "critical_flows.json",
+        "external_analyzer_results.json",
+        "coverage_matrix.json",
+        "flow_coverage.json",
+        "audit_results.jsonl",
+    ],
+    "runtime_validation_report.json": [
+        "repo_manifest.json",
+        "file_disposition.json",
+        "critical_flows.json",
+        "external_analyzer_results.json",
+        "coverage_matrix.json",
+        "flow_coverage.json",
+        "audit_results.jsonl",
+    ],
+    // Phase 4 — reporting. The human render depends on every analysis artifact;
+    // the canonical machine contract (audit-findings.json) is co-produced by
+    // synthesis. The optional narrative marker tracks audit-findings so a
+    // re-synthesized contract re-stales the themes/exec-summary/top-risks pass.
+    "audit-report.md": [
+        "repo_manifest.json",
+        "file_disposition.json",
+        "unit_manifest.json",
+        "surface_manifest.json",
+        "critical_flows.json",
+        "design_assessment.json",
+        "syntax_resolution_status.json",
+        "external_analyzer_results.json",
+        "coverage_matrix.json",
+        "flow_coverage.json",
+        "runtime_validation_report.json",
+        "audit_results.jsonl",
+        // Opt-in worker reflections (appended by workers, read-only to the
+        // orchestrator). Only the markdown render's "Process Feedback" section
+        // depends on it — NOT audit-findings.json, whose machine contract carries
+        // no reflections. advanceAudit hashes it fresh every advance so a
+        // reflection appended after synthesis re-stales the report exactly once and
+        // an unchanged file never churns finalization.
+        AGENT_FEEDBACK_FILENAME,
+    ],
+    "synthesis-narrative.json": ["audit-findings.json"],
+};
+/**
+ * Invert a `{ artifact: dependsOn[] }` map into a `{ upstream: dependents[] }`
+ * map. The sole derivation from the canonical table — keeps the two adjacency
+ * views in lockstep by construction.
+ */
+function invertDependencyMap(dependsOn) {
+    const dependents = {};
+    for (const [artifact, upstreams] of Object.entries(dependsOn)) {
+        if (!upstreams)
+            continue;
+        for (const upstream of upstreams) {
+            (dependents[upstream] ??= []).push(artifact);
+        }
+    }
+    return dependents;
+}
+/**
+ * Forward staleness adjacency: keyed by an UPSTREAM artifact → the list of
+ * DOWNSTREAM artifacts that depend on it (and so become stale when it changes).
+ * DERIVED from `ARTIFACT_DEPENDS_ON_MAP` (the single canonical table) — never
+ * hand-maintained, so it cannot drift from the dependency direction.
+ * `computeStaleArtifacts` uses this view to propagate staleness downstream.
+ */
+export const ARTIFACT_DEPENDENTS_MAP = invertDependencyMap(ARTIFACT_DEPENDS_ON_MAP);
+/**
+ * Every artifact participating in the staleness DAG — the union of those that
+ * depend on something (`ARTIFACT_DEPENDS_ON_MAP` keys) and those that are
+ * depended upon (`ARTIFACT_DEPENDENTS_MAP` keys, i.e. leaf inputs like
+ * scope.json / intent_checkpoint.json that have no upstream of their own).
+ * `computeArtifactMetadata` enumerates present artifacts from this set so a
+ * pure-input artifact still gets a metadata entry (and so its dependents can
+ * compare against its revision).
+ */
+export const ALL_DAG_ARTIFACTS = new Set([
+    ...Object.keys(ARTIFACT_DEPENDS_ON_MAP),
+    ...Object.keys(ARTIFACT_DEPENDENTS_MAP),
+]);
+//# sourceMappingURL=dependencyMap.js.map

package/dist/audit/orchestrator/dependencyMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependencyMap.js","sourceRoot":"","sources":["../../../src/audit/orchestrator/dependencyMap.ts"],"names":[],"mappings":"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"}

package/dist/audit/orchestrator/designReviewProjection.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Semantic / structural projection for audit-code's design-review passes
+ * (B2/B3 parity port).
+ *
+ * The design-review passes (contract-assessment + conceptual-design-critique)
+ * read a structural context assembled from several intake/structure artifacts
+ * (`renderSharedStructuralContext` in `designReviewPrompt.ts`): the file
+ * inventory, unit boundaries, dependency graph, externally-reachable surfaces,
+ * critical flows, the risk register, and the deterministic structural findings.
+ * When any of those upstreams change, the review's verdict can go stale.
+ *
+ * The naive trigger — "any byte changed" — re-runs the (expensive, LLM-driven)
+ * review on cosmetic churn: a re-derived `generated_at`, a file's content hash
+ * moving, a reordered list. This module is the audit-code half of the shared
+ * semantic-projection policy (remediate-code's `contractPipeline/
+ * semanticProjection.ts` is the other): each reviewed input is projected to ONLY
+ * the load-bearing structure the review actually reasons about — provenance and
+ * metrics stripped, each entry narrowed to its derivable fields and the
+ * collections canonically ordered. A cosmetic upstream edit projects to the same
+ * value (review stays fresh); a real structural change (a new module, a changed
+ * interface, a new surface, a re-scored risk) projects differently and correctly
+ * re-stales the review.
+ *
+ * This mirrors remediate-code's `DERIVABLE_MODULE_CONTRACT_FIELDS` narrowing —
+ * the "finalized-style structural projection" — applied to audit's structural
+ * artifact set. The generic diff + hashing machinery is single-sourced in
+ * `audit-tools/shared/reReview`.
+ */
+import { type CriticalFlowManifest, type GraphBundle, type RiskRegister, type SurfaceManifest } from "audit-tools/shared";
+import type { RepoManifest, UnitManifest } from "../types.js";
+import type { DesignAssessment } from "../types/designAssessment.js";
+/**
+ * The narrow read-only slice of the artifact bundle the design-review projection
+ * needs. Defined locally (rather than importing `ArtifactBundle` from
+ * `io/artifacts.ts`) so this module — and `designReviewSnapshot.ts`, which the
+ * bundle loader imports — do not form an import cycle with `io/artifacts.ts`.
+ * `ArtifactBundle` is structurally assignable to this.
+ */
+export interface DesignReviewBundle {
+    repo_manifest?: RepoManifest;
+    unit_manifest?: UnitManifest;
+    graph_bundle?: GraphBundle;
+    surface_manifest?: SurfaceManifest;
+    critical_flows?: CriticalFlowManifest;
+    risk_register?: RiskRegister;
+    design_assessment?: DesignAssessment;
+}
+/**
+ * The structural artifacts the design-review passes read. A design-review
+ * snapshot records the projection of each of these; a change to any of them
+ * (in projection) re-stales the review.
+ */
+export declare const DESIGN_REVIEW_INPUTS: readonly ["repo_manifest", "unit_manifest", "graph_bundle", "surface_manifest", "critical_flows", "risk_register", "design_assessment"];
+export type DesignReviewInput = (typeof DESIGN_REVIEW_INPUTS)[number];
+/**
+ * Project a single design-review input artifact from the bundle to its
+ * load-bearing structure. Returns `null` when the artifact is absent.
+ */
+export declare function projectDesignReviewInput(input: DesignReviewInput, bundle: DesignReviewBundle): unknown;
+/**
+ * Project every design-review input to its load-bearing structure, keyed by
+ * input name — the captured shape a design-review snapshot records and a
+ * re-review diffs against.
+ */
+export declare function projectDesignReviewInputs(bundle: DesignReviewBundle): Record<DesignReviewInput, unknown>;
+//# sourceMappingURL=designReviewProjection.d.ts.map

package/dist/audit/orchestrator/designReviewProjection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"designReviewProjection.d.ts","sourceRoot":"","sources":["../../../src/audit/orchestrator/designReviewProjection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,eAAe,EACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAErE;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,aAAa,CAAC,EAAE,YAAY,CAAC;IAC7B,aAAa,CAAC,EAAE,YAAY,CAAC;IAC7B,YAAY,CAAC,EAAE,WAAW,CAAC;IAC3B,gBAAgB,CAAC,EAAE,eAAe,CAAC;IACnC,cAAc,CAAC,EAAE,oBAAoB,CAAC;IACtC,aAAa,CAAC,EAAE,YAAY,CAAC;IAC7B,iBAAiB,CAAC,EAAE,gBAAgB,CAAC;CACtC;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,yIAQvB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAgKtE;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,iBAAiB,EACxB,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAET;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,kBAAkB,GACzB,MAAM,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAMpC"}

package/dist/audit/orchestrator/designReviewProjection.js

@@ -0,0 +1,215 @@
+/**
+ * Semantic / structural projection for audit-code's design-review passes
+ * (B2/B3 parity port).
+ *
+ * The design-review passes (contract-assessment + conceptual-design-critique)
+ * read a structural context assembled from several intake/structure artifacts
+ * (`renderSharedStructuralContext` in `designReviewPrompt.ts`): the file
+ * inventory, unit boundaries, dependency graph, externally-reachable surfaces,
+ * critical flows, the risk register, and the deterministic structural findings.
+ * When any of those upstreams change, the review's verdict can go stale.
+ *
+ * The naive trigger — "any byte changed" — re-runs the (expensive, LLM-driven)
+ * review on cosmetic churn: a re-derived `generated_at`, a file's content hash
+ * moving, a reordered list. This module is the audit-code half of the shared
+ * semantic-projection policy (remediate-code's `contractPipeline/
+ * semanticProjection.ts` is the other): each reviewed input is projected to ONLY
+ * the load-bearing structure the review actually reasons about — provenance and
+ * metrics stripped, each entry narrowed to its derivable fields and the
+ * collections canonically ordered. A cosmetic upstream edit projects to the same
+ * value (review stays fresh); a real structural change (a new module, a changed
+ * interface, a new surface, a re-scored risk) projects differently and correctly
+ * re-stales the review.
+ *
+ * This mirrors remediate-code's `DERIVABLE_MODULE_CONTRACT_FIELDS` narrowing —
+ * the "finalized-style structural projection" — applied to audit's structural
+ * artifact set. The generic diff + hashing machinery is single-sourced in
+ * `audit-tools/shared/reReview`.
+ */
+import { stableStringifyProjection, } from "audit-tools/shared";
+/**
+ * The structural artifacts the design-review passes read. A design-review
+ * snapshot records the projection of each of these; a change to any of them
+ * (in projection) re-stales the review.
+ */
+export const DESIGN_REVIEW_INPUTS = [
+    "repo_manifest",
+    "unit_manifest",
+    "graph_bundle",
+    "surface_manifest",
+    "critical_flows",
+    "risk_register",
+    "design_assessment",
+];
+/** Stable sort of a collection by its projection string (order-independent input). */
+function sortByProjection(items) {
+    return [...items].sort((a, b) => stableStringifyProjection(a).localeCompare(stableStringifyProjection(b)));
+}
+function sortStrings(values) {
+    return [...(values ?? [])].sort();
+}
+/**
+ * Project the file inventory to repository identity + the set of source files
+ * by path and language. Per-file metrics (`size_bytes`, `hash`) and the
+ * `generated_at` stamp are provenance — a content edit that does not add/remove a
+ * file or change its language does not re-stale the architecture review (which
+ * re-roams the live code regardless). Excluded files are dropped: they are not
+ * part of the reviewed surface, and toggling exclusion is captured via their
+ * presence/absence here.
+ */
+function projectRepoManifest(bundle) {
+    const manifest = bundle.repo_manifest;
+    if (!manifest)
+        return null;
+    const files = (manifest.files ?? [])
+        .filter((file) => !file.excluded)
+        .map((file) => ({ path: file.path, language: file.language }));
+    return {
+        name: manifest.repository?.name ?? null,
+        files: sortByProjection(files),
+    };
+}
+/** Project units to their boundaries: id, name, kind, files, lenses, flows. */
+function projectUnitManifest(bundle) {
+    const units = bundle.unit_manifest?.units;
+    if (!units)
+        return null;
+    const projected = units.map((unit) => ({
+        unit_id: unit.unit_id,
+        name: unit.name,
+        kind: unit.kind ?? null,
+        files: sortStrings(unit.files),
+        required_lenses: sortStrings(unit.required_lenses),
+        critical_flows: sortStrings(unit.critical_flows),
+    }));
+    return sortByProjection(projected);
+}
+/**
+ * Project the dependency graph to its edge sets per kind. Each edge narrows to
+ * its endpoints (`from`/`to`, or a route's `path`/`handler`/`method`); the
+ * `confidence`/`reason`/`direction` annotations are analyzer provenance, not the
+ * structure the review reasons about. Language-neutral: every graph kind is
+ * walked, not a hardcoded subset.
+ */
+function projectGraphBundle(bundle) {
+    const graphs = bundle.graph_bundle?.graphs;
+    if (!graphs)
+        return null;
+    const out = {};
+    for (const [kind, edges] of Object.entries(graphs)) {
+        if (!Array.isArray(edges))
+            continue;
+        const projected = edges.map((edge) => {
+            const record = (edge ?? {});
+            if ("from" in record || "to" in record) {
+                return { from: record.from ?? null, to: record.to ?? null };
+            }
+            if ("path" in record || "handler" in record) {
+                return {
+                    path: record.path ?? null,
+                    handler: record.handler ?? null,
+                    method: record.method ?? null,
+                };
+            }
+            return record;
+        });
+        out[kind] = sortByProjection(projected);
+    }
+    return out;
+}
+/** Project surfaces to id, kind, entrypoint, exposure, methods (notes dropped). */
+function projectSurfaceManifest(bundle) {
+    const surfaces = bundle.surface_manifest?.surfaces;
+    if (!surfaces)
+        return null;
+    const projected = surfaces.map((surface) => ({
+        id: surface.id,
+        kind: surface.kind,
+        entrypoint: surface.entrypoint,
+        exposure: surface.exposure ?? null,
+        methods: sortStrings(surface.methods),
+    }));
+    return sortByProjection(projected);
+}
+/** Project flows to id, name, entrypoints, paths, concerns, confidence. */
+function projectCriticalFlows(bundle) {
+    const flows = bundle.critical_flows?.flows;
+    if (!flows)
+        return null;
+    const projected = flows.map((flow) => ({
+        id: flow.id,
+        name: flow.name,
+        entrypoints: sortStrings(flow.entrypoints),
+        paths: sortStrings(flow.paths),
+        concerns: sortStrings(flow.concerns),
+        confidence: flow.confidence ?? null,
+    }));
+    return sortByProjection(projected);
+}
+/** Project risk items to unit_id, score, signals (notes dropped). */
+function projectRiskRegister(bundle) {
+    const items = bundle.risk_register?.items;
+    if (!items)
+        return null;
+    const projected = items.map((item) => ({
+        unit_id: item.unit_id,
+        risk_score: item.risk_score,
+        signals: sortStrings(item.signals),
+    }));
+    return sortByProjection(projected);
+}
+/**
+ * Project the design assessment to ONLY its deterministic structural `findings`
+ * (the slice the review actually reads), each narrowed to its identity/content
+ * fields. The review verdicts the passes themselves write
+ * (`contract_findings` / `conceptual_findings` / the `*_reviewed` flags) are
+ * deliberately excluded — including them would make the review's own output an
+ * input to its staleness (a self-referential re-stale loop). `generated_at` is
+ * provenance.
+ */
+function projectDesignAssessmentFindings(bundle) {
+    const findings = bundle.design_assessment?.findings;
+    if (!findings)
+        return null;
+    const projected = findings.map((finding) => ({
+        id: finding.id,
+        title: finding.title,
+        category: finding.category,
+        severity: finding.severity,
+        confidence: finding.confidence,
+        lens: finding.lens,
+        summary: finding.summary,
+        affected_files: sortStrings((finding.affected_files ?? []).map((location) => location.path)),
+        systemic: finding.systemic ?? false,
+    }));
+    return sortByProjection(projected);
+}
+const PROJECTORS = {
+    repo_manifest: projectRepoManifest,
+    unit_manifest: projectUnitManifest,
+    graph_bundle: projectGraphBundle,
+    surface_manifest: projectSurfaceManifest,
+    critical_flows: projectCriticalFlows,
+    risk_register: projectRiskRegister,
+    design_assessment: projectDesignAssessmentFindings,
+};
+/**
+ * Project a single design-review input artifact from the bundle to its
+ * load-bearing structure. Returns `null` when the artifact is absent.
+ */
+export function projectDesignReviewInput(input, bundle) {
+    return PROJECTORS[input](bundle);
+}
+/**
+ * Project every design-review input to its load-bearing structure, keyed by
+ * input name — the captured shape a design-review snapshot records and a
+ * re-review diffs against.
+ */
+export function projectDesignReviewInputs(bundle) {
+    const out = {};
+    for (const input of DESIGN_REVIEW_INPUTS) {
+        out[input] = PROJECTORS[input](bundle);
+    }
+    return out;
+}
+//# sourceMappingURL=designReviewProjection.js.map

package/dist/audit/orchestrator/designReviewProjection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"designReviewProjection.js","sourceRoot":"","sources":["../../../src/audit/orchestrator/designReviewProjection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EACL,yBAAyB,GAK1B,MAAM,oBAAoB,CAAC;AAqB5B;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,eAAe;IACf,eAAe;IACf,cAAc;IACd,kBAAkB;IAClB,gBAAgB;IAChB,eAAe;IACf,mBAAmB;CACX,CAAC;AAIX,sFAAsF;AACtF,SAAS,gBAAgB,CAAI,KAAmB;IAC9C,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAC9B,yBAAyB,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAC,CACzE,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,MAAqC;IACxD,OAAO,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AACpC,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,mBAAmB,CAAC,MAA0B;IACrD,MAAM,QAAQ,GAAG,MAAM,CAAC,aAAa,CAAC;IACtC,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3B,MAAM,KAAK,GAAG,CAAC,QAAQ,CAAC,KAAK,IAAI,EAAE,CAAC;SACjC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC;SAChC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IACjE,OAAO;QACL,IAAI,EAAE,QAAQ,CAAC,UAAU,EAAE,IAAI,IAAI,IAAI;QACvC,KAAK,EAAE,gBAAgB,CAAC,KAAK,CAAC;KAC/B,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,SAAS,mBAAmB,CAAC,MAA0B;IACrD,MAAM,KAAK,GAAG,MAAM,CAAC,aAAa,EAAE,KAAK,CAAC;IAC1C,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,SAAS,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACrC,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI;QACvB,KAAK,EAAE,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC;QAC9B,eAAe,EAAE,WAAW,CAAC,IAAI,CAAC,eAAe,CAAC;QAClD,cAAc,EAAE,WAAW,CAAC,IAAI,CAAC,cAAc,CAAC;KACjD,CAAC,CAAC,CAAC;IACJ,OAAO,gBAAgB,CAAC,SAAS,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;GAMG;AACH,SAAS,kBAAkB,CAAC,MAA0B;IACpD,MAAM,MAAM,GAAG,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC;IAC3C,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,SAAS;QACpC,MAAM,SAAS,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;YACnC,MAAM,MAAM,GAAG,CAAC,IAAI,IAAI,EAAE,CAA4B,CAAC;YACvD,IAAI,MAAM,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,EAAE,CAAC;gBACvC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC;YAC9D,CAAC;YACD,IAAI,MAAM,IAAI,MAAM,IAAI,SAAS,IAAI,MAAM,EAAE,CAAC;gBAC5C,OAAO;oBACL,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,IAAI;oBACzB,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI;oBAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,IAAI;iBAC9B,CAAC;YACJ,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC,CAAC,CAAC;QACH,GAAG,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,mFAAmF;AACnF,SAAS,sBAAsB,CAAC,MAA0B;IACxD,MAAM,QAAQ,GAAG,MAAM,CAAC,gBAAgB,EAAE,QAAQ,CAAC;IACnD,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3B,MAAM,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAC3C,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI;QAClC,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC;KACtC,CAAC,CAAC,CAAC;IACJ,OAAO,gBAAgB,CAAC,SAAS,CAAC,CAAC;AACrC,CAAC;AAED,2EAA2E;AAC3E,SAAS,oBAAoB,CAAC,MAA0B;IACtD,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,EAAE,KAAK,CAAC;IAC3C,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,SAAS,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACrC,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,WAAW,EAAE,WAAW,CAAC,IAAI,CAAC,WAAW,CAAC;QAC1C,KAAK,EAAE,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC;QAC9B,QAAQ,EAAE,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC;QACpC,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,IAAI;KACpC,CAAC,CAAC,CAAC;IACJ,OAAO,gBAAgB,CAAC,SAAS,CAAC,CAAC;AACrC,CAAC;AAED,qEAAqE;AACrE,SAAS,mBAAmB,CAAC,MAA0B;IACrD,MAAM,KAAK,GAAG,MAAM,CAAC,aAAa,EAAE,KAAK,CAAC;IAC1C,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,SAAS,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACrC,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,OAAO,EAAE,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC;KACnC,CAAC,CAAC,CAAC;IACJ,OAAO,gBAAgB,CAAC,SAAS,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,+BAA+B,CAAC,MAA0B;IACjE,MAAM,QAAQ,GAAG,MAAM,CAAC,iBAAiB,EAAE,QAAQ,CAAC;IACpD,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3B,MAAM,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAC3C,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,cAAc,EAAE,WAAW,CACzB,CAAC,OAAO,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAChE;QACD,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,KAAK;KACpC,CAAC,CAAC,CAAC;IACJ,OAAO,gBAAgB,CAAC,SAAS,CAAC,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,GAAuE;IACrF,aAAa,EAAE,mBAAmB;IAClC,aAAa,EAAE,mBAAmB;IAClC,YAAY,EAAE,kBAAkB;IAChC,gBAAgB,EAAE,sBAAsB;IACxC,cAAc,EAAE,oBAAoB;IACpC,aAAa,EAAE,mBAAmB;IAClC,iBAAiB,EAAE,+BAA+B;CACnD,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CACtC,KAAwB,EACxB,MAA0B;IAE1B,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC;AACnC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CACvC,MAA0B;IAE1B,MAAM,GAAG,GAAG,EAAwC,CAAC;IACrD,KAAK,MAAM,KAAK,IAAI,oBAAoB,EAAE,CAAC;QACzC,GAAG,CAAC,KAAK,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/audit/orchestrator/designReviewPrompt.d.ts

@@ -0,0 +1,82 @@
+import type { ArtifactBundle } from "../io/artifacts.js";
+export interface DesignReviewOptions {
+    max_units?: number;
+    conceptual_depth?: "shallow" | "deep";
+}
+/**
+ * A conceptual-review perspective: a deliberately narrow value system one
+ * independent reviewer adopts. The deep conceptual pass fans these out to real
+ * parallel subagents (one perspective each), then merges via an independent
+ * judge. Provider-neutral — a perspective is a *lens*, never a model.
+ */
+export interface ConceptualPerspective {
+    name: string;
+    /** The value system this reviewer judges the codebase through. */
+    lens: string;
+}
+/**
+ * Built-in conceptual perspectives, ordered most-to-least commonly useful. The
+ * deep fan-out takes the first `perspectives` of these. Each is a maximally
+ * dissimilar value system so the union covers angles no single pass would. A
+ * reviewer may sharpen its lens to the codebase, but stays in character.
+ */
+export declare const CONCEPTUAL_PERSPECTIVES: readonly ConceptualPerspective[];
+/** Default number of deep-review perspectives when the host does not specify. */
+export declare const DEFAULT_CONCEPTUAL_PERSPECTIVES = 5;
+/**
+ * Clamp a requested perspective count into the supported range: at least 2
+ * (one perspective is just a shallow review) and at most the number of built-in
+ * perspectives. Non-finite / undefined ⇒ the default.
+ */
+export declare function clampPerspectiveCount(requested?: number): number;
+/** The first `count` (clamped) built-in perspectives for a deep fan-out. */
+export declare function selectPerspectives(count?: number): ConceptualPerspective[];
+/**
+ * Render the shared structural context block that is identical for both the
+ * contract-review and conceptual-review passes. Placing it first in both
+ * prompts makes it cache-eligible when the same bundle is used for both agents.
+ */
+export declare function renderSharedStructuralContext(bundle: ArtifactBundle, maxUnits: number): string;
+/**
+ * Contract-review prompt (adversarial pass).
+ * Infers existing contracts from the codebase and attacks them with counterexamples.
+ * Categories: inferred_contract_gap, trust_boundary_gap, invariant_counterexample,
+ * critical_invariant_coverage_gap.
+ */
+export declare function renderContractReviewPrompt(bundle: ArtifactBundle, options?: DesignReviewOptions): string;
+/**
+ * Conceptual-design review prompt (generative pass — shallow / single agent).
+ * Produces broad architectural and design improvement observations.
+ * Categories: tool_opportunity, architecture_pattern, design_simplification,
+ * integration, missing_capability.
+ *
+ * The deep multi-perspective variant is real dispatch fan-out, not an in-prompt
+ * instruction — see `renderConceptualPerspectivePrompt` /
+ * `renderConceptualJudgePrompt`.
+ */
+export declare function renderConceptualReviewPrompt(bundle: ArtifactBundle, options?: DesignReviewOptions): string;
+/**
+ * One perspective's conceptual-review prompt (deep fan-out). Each perspective
+ * is dispatched to an independent subagent that reviews *only* through its
+ * assigned value system and must not see the other perspectives' output — a
+ * separate judge merges them. This is the real fan-out that replaces the old
+ * single-agent "imagine several perspectives" instruction.
+ */
+export declare function renderConceptualPerspectivePrompt(bundle: ArtifactBundle, perspective: ConceptualPerspective, index: number, total: number, options?: DesignReviewOptions): string;
+/**
+ * The independent judge prompt (deep fan-out). The judge is a fresh agent —
+ * never one of the perspective authors — that reads every perspective's
+ * findings, merges and deduplicates them, resolves contradictions, drops
+ * low-confidence observations no other perspective corroborates, and writes the
+ * single merged conceptual-review result the orchestrator ingests.
+ */
+export declare function renderConceptualJudgePrompt(perspectiveResults: Array<{
+    name: string;
+    path: string;
+}>): string;
+/**
+ * Combined fallback prompt for non-dispatch paths: both contract-assessment and
+ * conceptual-design-critique sections in a single agent turn.
+ */
+export declare function renderDesignReviewPrompt(bundle: ArtifactBundle, options?: DesignReviewOptions): string;
+//# sourceMappingURL=designReviewPrompt.d.ts.map

package/dist/audit/orchestrator/designReviewPrompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"designReviewPrompt.d.ts","sourceRoot":"","sources":["../../../src/audit/orchestrator/designReviewPrompt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAmKzD,MAAM,WAAW,mBAAmB;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;CACvC;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,qBAAqB,EAoCnE,CAAC;AAEF,iFAAiF;AACjF,eAAO,MAAM,+BAA+B,IAAI,CAAC;AAEjD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAKhE;AAED,4EAA4E;AAC5E,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAE1E;AA+DD;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,MAAM,GACf,MAAM,CA4CR;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,mBAAwB,GAChC,MAAM,CAyCR;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,mBAAwB,GAChC,MAAM,CAgBR;AAED;;;;;;GAMG;AACH,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,cAAc,EACtB,WAAW,EAAE,qBAAqB,EAClC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,mBAAwB,GAChC,MAAM,CAsBR;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,kBAAkB,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GACxD,MAAM,CA8BR;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,mBAAwB,GAChC,MAAM,CAsDR"}