diff --git a/docs/repo_assumptions.md b/docs/repo_assumptions.md index bf295aff69c..c149a69cca8 100644 --- a/docs/repo_assumptions.md +++ b/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`