docs(governance): validate policy/eval repo assumptions for MWS planning

docs/repo_assumptions.md

@@ -1,25 +1,95 @@
-# Startup Scouting Repo Assumptions
+# Repo Assumptions Validation — Policy/Eval/CI Intake
 
-## Confirmed Paths
+Date: 2026-04-08 (UTC)
+Scope: `src/`, `.github/workflows/`, `docs/`
 
-- `src/connectors/` is available for startup source ingestion adapters.
-- `src/graphrag/` supports enrichment pipeline logic for entity normalization.
-- `src/agents/` is available for deterministic scoring and report generation.
-- `.github/workflows/ci-verify.yml` is the CI target for verification gate additions.
+## Objective
+Validate the intake assumptions for a policy-gated agent execution slice before opening implementation PRs.
 
-## Must-Not-Touch Constraints
+## Validation Results
 
-- `.github/workflows/ci-core.yml` remains unchanged.
-- `src/api/graphql/` remains unchanged to avoid schema stability risk.
+### 1) Agent execution entrypoints (`src/agents/*`)
+**Status: Verified present**
 
-## Validation Checklist
+Observed execution/control files include:
+- `src/agents/runtime/saga/SagaRuntime.ts`
+- `src/agents/controlplane/router/routeTask.ts`
+- `src/agents/controlplane/policy/PolicyDecisionPoint.ts`
+- `src/agents/composable-investigation/index.ts`
 
-- [x] Add startup-specific connectors under `src/connectors/startups/`.
-- [x] Add startup entity model and enrichment pipeline under `src/graphrag/`.
-- [x] Add deterministic scoring + ranked output pipeline under `src/agents/`.
-- [ ] Add CI policy enforcement updates (deferred pending workflow owner review).
+Implication: runtime gating can be attached in existing controlplane/runtime paths without introducing a new top-level agent runtime package.
 
-## Readiness Assertion
+### 2) CI workflows and likely gate locations
+**Status: Verified present**
 
-This slice is intentionally constrained to deterministic ingestion, enrichment, and scoring.
-CI policy gate expansion is deferred pending ownership review of shared workflow policy.
+Observed relevant workflow files include:
+- `.github/workflows/ci-core.yml`
+- `.github/workflows/ci-verify.yml`
+- `.github/workflows/summit-eval.yml`
+- `.github/workflows/agent-evals.yml`
+- `.github/workflows/policy-engine-gate.yml`
+- `.github/workflows/pr-quality-gate.yml`
+
+Implication: evaluation threshold enforcement can be integrated in existing CI gate workflows (prefer `ci-verify` / eval-specific pipelines) instead of creating net-new root pipeline complexity.
+
+### 3) Evidence schema conventions (`report.json` / `metrics.json`)
+**Status: Verified present and reused broadly**
+
+Observed evidence/metric contracts and checks include:
+- `scripts/evidence_validate.py` checks for `report.json` and `metrics.json`
+- `scripts/ci/verify_evidence_consistency.mjs` includes both filenames in required evidence set
+- Multiple workflows publish or gate on these files (e.g., `summit-eval.yml`, `agent-trust.yml`, `proof-gate.yml`)
+
+Implication: deterministic output artifacts should conform to existing `report.json` and `metrics.json` expectations.
+
+### 4) “No existing policy system” assumption
+**Status: Invalid (existing policy systems are present)**
+
+Observed policy components include:
+- `src/governance/policyEngine.ts` (OPA-integrated governance policy engine)
+- `src/governance/enforcement.ts` (runtime policy + audit integration)
+- `src/services/PolicyEngine.ts`
+- `src/agents/controlplane/policy/PolicyDecisionPoint.ts` (deny-by-default agent policy layer)
+
+Implication: implementation should extend or reuse existing policy infrastructure; do not introduce duplicate policy engines.
+
+### 5) “No evaluation harness under CI” assumption
+**Status: Invalid (existing eval harnesses are present)**
+
+Observed eval-oriented workflows include:
+- `.github/workflows/summit-eval.yml`
+- `.github/workflows/agent-evals.yml`
+- `.github/workflows/graphrag-eval.yml`
+- `.github/workflows/eval-skills.yml`
+
+Implication: add threshold logic into existing eval lanes where possible.
+
+### 6) “No agent safety gates at runtime” assumption
+**Status: Invalid (runtime gates are present)**
+
+Observed runtime/safety gating components include:
+- `src/agents/controlplane/policy/PolicyDecisionPoint.ts`
+- `src/agent-graph/runtime-guard.ts`
+- `src/context/executeWithTrust.ts`
+- `src/security/llmBoundary.ts`
+
+Implication: proposed MWS should target integration hardening and deterministic evidence output, not first-time runtime gating.
+
+## Must-Not-Touch Inputs from Intake
+- `.github/workflows/ci-core.yml`
+- `src/graphrag/` core retrieval paths
+- `src/api/graphql/` schema contracts
+
+Status: constraints acknowledged for follow-on implementation slicing.
+
+## Recommended Next Slice (Implementation-Ready)
+1. Extend existing agent policy decision path to emit deterministic `policy_decision.json` alongside standard `report.json` / `metrics.json`.
+2. Wire CI assertion to existing eval workflow (`ci-verify` or `summit-eval`) with threshold fail-fast.
+3. Preserve feature flag default OFF for runtime enforcement escalation.
+
+## Commands Used
+- `rg --files -g 'AGENTS.md'`
+- `rg --files .github/workflows src docs | head -n 200`
+- `rg --files .github/workflows`
+- `rg -n "report\.json|metrics\.json|policy_decision\.json" -S src docs .github scripts | head -n 200`
+- `rg -n "policy engine|PolicyEngine|policy" src/agents src/governance src/services | head -n 200`