# PLAN Wrkr: Public Scan Tentpole Readiness

Date: 2026-02-23
Source of truth: User-provided recommended items in this thread (public-repo tentpole readiness gaps) + current repo contracts (`product/wrkr.md`, `product/dev_guides.md`).
Scope: Planning only. No implementation in this plan. Focus is execution-ready backlog to ship a repeatable "State of AI Tool Sprawl" public scan/report + PR distribution workflow with deterministic Wrkr contracts.

## Global Decisions (Locked)

- Deterministic pipeline only. No LLM/SLM calls in scan, scoring, reporting, proof, or campaign aggregation paths.
- Offline-first defaults and fail-closed behavior remain unchanged.
- Exit codes and `--json` contracts are API surface and must remain stable unless explicitly versioned.
- Architecture boundaries stay intact: source acquisition, detection, aggregation, risk, report, proof.
- Public headline claims must be backed by deterministic methodology artifacts generated by Wrkr.
- `production_write` headline claims are valid only when `--production-targets` is configured and valid.

## Current Baseline (Observed)

- Strong scenario and acceptance posture exists:
  - Scenario contract gate: `scripts/validate_scenarios.sh`
  - Scenario tests: `internal/scenarios/`
  - AC matrix (AC01-AC21): `internal/acceptance/v1_acceptance_test.go`
- UAT install-path script already covers source build, release archive, and Homebrew path (including local formula).
  - `scripts/test_uat_local.sh`
- `scan` already emits privilege budget + `production_write` status and supports report artifacts.
  - `core/cli/scan.go`
  - `core/aggregate/privilegebudget/budget.go`
- Main gaps blocking tentpole automation:
  - Org listing limited to one page (`per_page=100`) in `core/source/github/connector.go`.
  - Repo/org acquisition metadata does not materialize local repo contents for detector pass in org/repo mode.
  - No built-in multi-run public-scan aggregation artifact for headline numbers.
  - PR distribution exists for `fix --open-pr`, but action `mode=pr` is not wired to publish PR comments.
  - UAT local install-path target exists in Make but is not wired into CI workflow gates.
  - Approval gap classification is not first-class for research reporting (`approved` vs `unapproved` vs `unknown` based on explicit approved lists).
  - Methodology metadata output is incomplete for publication-grade reproducibility (version, duration, repo/file counts, detector/version inventory).
  - Tool inventory output lacks explicit research taxonomy and deterministic confidence scores per detection.
  - Privilege map output needs normalized read/write/admin tier semantics and deterministic critical/high/medium/low risk-tier projection for report tables.
  - Adoption-pattern analysis (org-wide vs team-level vs individual/one-off usage) is not yet modeled as first-class output.
  - Regulatory exposure mapping is not emitted per tool/per regulation article at report-ready granularity.
  - Case-study generation requires anonymized export mode that preserves patterns while removing direct org/repo identifiers.
  - Benchmark section inputs (org size/industry segmentation) are not currently emitted by scan aggregation.
  - Appendix-grade tabular exports (CSV + richer JSON matrices) are not yet available as built-in command outputs.

## Exit Criteria

- Wrkr can run deterministic public sample scans at scale (>500 repos) with pagination-safe org acquisition.
- Repo/org scans can be executed in a way that materializes analyzable content for detectors (or clearly fail-closed with explicit reason).
- Wrkr can generate a single deterministic campaign summary artifact with headline metrics and methodology metadata.
- PR distribution path is complete: relevant PRs receive deterministic comment payloads in `mode=pr`.
- UAT install-path checks (including Homebrew path) are wired into release gating policy.
- Any published claim of "unreviewed production access" is blocked or downgraded when production targets are not configured.
- Report section coverage is end-to-end for the target structure (Headline, Methodology, Inventory, Privilege Map, Approval Gap, Regulatory Exposure, Case Studies, Benchmarks, Recommendations, Appendix).
- Approval ratio outputs are backed by explicit approved-list matching and reproducible classification logic.
- Methodology section fields are emitted directly from machine-readable Wrkr outputs (not manual estimation).
- Tool inventory includes deterministic category and confidence outputs suitable for external citation.
- Regulatory outputs include per-tool, per-control/article gap status suitable for compliance-table rendering.
- Anonymized and segmented exports exist for case studies and benchmark tables without leaking organization identity.
- Appendix tables are exportable in CSV/JSON with deterministic ordering and documented schemas.

## Recommendation Traceability

| Recommendation ID | Recommendation | Planned Stories |
|---|---|---|
| R1 | Add org pagination beyond first 100 repos | E1-S1 |
| R2 | Materialize repo/org content so detectors run for public scans | E1-S2 |
| R3 | Add built-in multi-run aggregation for 500-repo headline artifact | E2-S1, E2-S2 |
| R4 | Complete PR distribution automation in action `mode=pr` | E3-S1, E3-S2 |
| R5 | Wire UAT targets into CI/release gates | E4-S1 |
| R6 | Enforce production-target requirement for production-write headline claims | E2-S3 |
| R7 | Ensure UAT includes Homebrew install path in release readiness | E4-S1, E4-S2 |
| R8 | Add approval status classification (`approved`/`unapproved`/`unknown`) backed by explicit approved lists | E5-S1 |
| R9 | Emit methodology metadata fields required for research credibility and reproducibility | E5-S2 |
| R10 | Add tool taxonomy granularity suitable for inventory breakdown sections | E5-S3 |
| R11 | Add deterministic per-tool detection confidence scoring | E5-S3 |
| R12 | Add normalized permission surface + critical/high/medium/low risk-tier outputs | E5-S4 |
| R13 | Add adoption pattern classification (org-wide/team/individual/one-off) | E5-S5 |
| R14 | Add per-tool regulatory control/article mapping output | E5-S6 |
| R15 | Add anonymized export mode for case-study-ready outputs | E5-S7 |
| R16 | Add segment-level aggregation (industry/size) for benchmark analysis | E5-S8 |
| R17 | Add appendix-grade tabular exports (CSV + JSON matrices) | E5-S9 |

## Test Matrix Wiring

- Fast lane:
  - `make lint-fast`
  - Targeted unit tests for changed packages (`go test ./core/... -count=1` scoped)
- Core CI lane:
  - `make test-fast`
  - `make test-contracts`
  - Source/e2e suites for changed commands (`go test ./internal/e2e/... -count=1` scoped)
- Acceptance lane:
  - `scripts/run_v1_acceptance.sh --mode=main`
  - `scripts/validate_scenarios.sh`
  - `go test ./internal/scenarios -count=1 -tags=scenario`
- Cross-platform lane:
  - Linux/macOS/Windows build and smoke via existing matrix workflow
- Risk lane:
  - `scripts/validate_contracts.sh`
  - `scripts/test_hardening_core.sh`
  - `scripts/test_perf_budgets.sh`
  - `go test ./internal/integration/interop -count=1`
- Merge/release gating rule:
  - P0/P1 stories require all impacted lanes green.
  - Release gate requires UAT install-path pass plus v1 acceptance mandatory pass.
  - Any schema/output contract drift must be intentional and updated in same PR.

## Epic E1: Public Source Acquisition At Scale

Objective: Make org/repo acquisition reliable for large public scans and ensure detector-executable local content exists for analysis.

### Story E1-S1: Implement deterministic GitHub org pagination
Priority: P0
Tasks:
- Extend org listing to iterate deterministic pages until exhausted.
- Preserve stable repo ordering and deterministic failure collection.
- Add clear fail-closed behavior for partial page/API failures.
Repo paths:
- `core/source/github/connector.go`
- `core/source/org/acquire.go`
- `core/source/github/connector_test.go`
- `internal/e2e/source/source_e2e_test.go`
Run commands:
- `go test ./core/source/github -count=1`
- `go test ./core/source/org -count=1`
- `go test ./internal/e2e/source -count=1`
- `wrkr scan --org acme --github-api <api> --json`
Test requirements:
- Unit tests for pagination termination and page stitching.
- Retry-path tests for transient 429/5xx across pages.
- Deterministic ordering test on multi-page response sets.
- Exit-code contract tests for dependency/runtime failures.
Matrix wiring:
- Fast lane: yes
- Core CI lane: yes
- Acceptance lane: yes
- Cross-platform lane: yes
- Risk lane: yes
Acceptance criteria:
- Org scan can collect >100 repos deterministically.
- Multi-page result order is byte-stable for fixed fixtures.
- Transient failures preserve fail-closed semantics and reason clarity.
Dependencies:
- None
Risks:
- GitHub API rate windows and pagination edge handling.

### Story E1-S2: Add repo materialization path for org/repo scans
Priority: P0
Tasks:
- Introduce deterministic acquisition mode that materializes repo content to local workspace for detector execution.
- Define explicit source provenance (`github_repo_materialized` or equivalent) in manifest/output.
- Add cleanup/safety policy for temp materialization directories.
- Keep `--path` behavior unchanged; repo/org modes gain analyzable local roots.
Repo paths:
- `core/cli/scan.go`
- `core/source/github/`
- `core/source/types.go`
- `internal/e2e/source/source_e2e_test.go`
- `docs/commands/scan.md`
Run commands:
- `go test ./core/source/... -count=1`
- `go test ./core/cli -count=1`
- `go test ./internal/e2e/source -count=1`
- `wrkr scan --repo acme/backend --github-api <api> --json`
- `wrkr scan --org acme --github-api <api> --json`
Test requirements:
- Integration tests proving detectors run against materialized local dirs in repo/org mode.
- Fail-closed tests for materialization failure/permission denial.
- Contract tests for stable source_manifest fields and locations.
- Determinism tests for repeated run output stability with fixed fixtures.
Matrix wiring:
- Fast lane: yes
- Core CI lane: yes
- Acceptance lane: yes
- Cross-platform lane: yes
- Risk lane: yes
Acceptance criteria:
- Repo/org scans produce config-level findings without requiring manual pre-clone.
- `source_manifest` clearly indicates materialized source provenance.
- Materialization errors return stable error codes and machine-readable reasons.
Dependencies:
- E1-S1 recommended first for scale validation.
Risks:
- Temp-path cleanup and cross-platform path normalization.

## Epic E2: Campaign Aggregation and Headline Artifact

Objective: Productize a deterministic, reproducible public-scan campaign artifact for media/analyst/GTM reuse.

### Story E2-S1: Add campaign aggregation command and schema
Priority: P0
Tasks:
- Add new CLI command (for example `wrkr campaign aggregate`) that ingests multiple scan JSON/state outputs.
- Compute deterministic headline metrics:
  - repos_scanned
  - tools_detected_total
  - write_capable_tools
  - credential_access_tools
  - production_write_tools (when configured)
- Emit one machine-readable campaign artifact with methodology metadata.
Repo paths:
- `cmd/wrkr/`
- `core/cli/`
- `core/report/`
- `schemas/v1/report/`
- `internal/e2e/`
Run commands:
- `go test ./core/cli -count=1`
- `go test ./core/report -count=1`
- `go test ./internal/e2e/... -count=1`
- `wrkr campaign aggregate --input-glob './.tmp/campaign/*.json' --json`
Test requirements:
- CLI help/usage and exit-code tests.
- Schema validation and compatibility tests for new artifact.
- Deterministic byte-stability tests for fixed input set.
- Error mapping tests for missing/malformed input artifacts.
Matrix wiring:
- Fast lane: yes
- Core CI lane: yes
- Acceptance lane: yes
- Cross-platform lane: yes
- Risk lane: yes
Acceptance criteria:
- One deterministic artifact summarizes campaign-level metrics across N scans.
- Output validates against schema and remains byte-stable for fixed inputs.
Dependencies:
- E1-S1 and E1-S2
Risks:
- Output contract creep without schema discipline.

### Story E2-S2: Add public-report rendering template for tentpole output
Priority: P1
Tasks:
- Add/extend report template for campaign-style public artifact (headline first, methodology second).
- Ensure redaction and public-share safety remain intact.
- Include reproducibility metadata: command set, date range, sample definition, exclusion criteria.
Repo paths:
- `core/report/`
- `core/cli/report.go`
- `docs/commands/report.md`
- `docs/` (new campaign methodology page)
Run commands:
- `go test ./core/report -count=1`
- `go test ./core/cli -run Report -count=1`
- `wrkr report --template public --share-profile public --json`
Test requirements:
- Deterministic markdown/PDF rendering tests.
- Public redaction tests (no sensitive repo identity leakage in public mode).
- Docs consistency and storyline smoke checks.
Matrix wiring:
- Fast lane: yes
- Core CI lane: yes
- Acceptance lane: yes
- Cross-platform lane: no
- Risk lane: yes
Acceptance criteria:
- Public report includes publication-ready headline + transparent method section.
- Rendered outputs are deterministic for fixed state.
Dependencies:
- E2-S1
Risks:
- Marketing language drifting from measurable metrics.

### Story E2-S3: Enforce production-write claim guardrails
Priority: P0
Tasks:
- Add explicit guardrails for campaign/report outputs: if production targets are not configured, prohibit numeric claims of production_write percentage.
- Emit deterministic warning/error modes for strict publication use.
- Document claim policy in command docs.
Repo paths:
- `core/aggregate/privilegebudget/budget.go`
- `core/cli/scan.go`
- `core/report/build.go`
- `docs/commands/scan.md`
- `docs/commands/report.md`
Run commands:
- `go test ./core/aggregate/privilegebudget -count=1`
- `go test ./core/cli -count=1`
- `go test ./core/report -count=1`
- `wrkr scan --path ./scenarios/wrkr/scan-mixed-org/repos --json`
- `wrkr scan --path ./scenarios/wrkr/scan-mixed-org/repos --production-targets ./docs/examples/production-targets.v1.yaml --json`
Test requirements:
- Contract tests for `production_write` configured/not_configured/invalid statuses.
- Fail-closed publication-mode tests when claim prerequisites are missing.
- Reason-code stability tests for machine consumers.
Matrix wiring:
- Fast lane: yes
- Core CI lane: yes
- Acceptance lane: yes
- Cross-platform lane: yes
- Risk lane: yes
Acceptance criteria:
- Public headline pipeline cannot output defensible-looking production-write percentages without configured targets.
- Status/warning/error behavior is deterministic and documented.
Dependencies:
- E2-S1
Risks:
- Backward compatibility for current consumers expecting nullable counts.

## Epic E3: PR Distribution Completion

Objective: Complete deterministic PR distribution so public-scan or scheduled findings can be delivered as PR comments where relevant.

### Story E3-S1: Wire action `mode=pr` to publish deterministic PR comments
Priority: P0
Tasks:
- Implement PR comment publish path in action runtime for relevant changes.
- Reuse deterministic `RunPRMode` payload formatting and threshold logic.
- Ensure idempotent comment update behavior (upsert by fingerprint/marker).
Repo paths:
- `action/entrypoint.sh`
- `core/action/runtime.go`
- `core/github/pr/`
- `internal/e2e/action/`
Run commands:
- `go test ./core/action/... -count=1`
- `go test ./internal/e2e/action -count=1`
- `go test ./core/github/pr -count=1`
Test requirements:
- PR-mode e2e tests for docs-only suppression and relevant-path comment posting.
- Idempotency tests for repeated runs (no comment spam).
- Fail-closed tests for missing/insufficient token permissions.
- Exit-code contract tests for approval-required/runtime-failure boundaries.
Matrix wiring:
- Fast lane: yes
- Core CI lane: yes
- Acceptance lane: yes
- Cross-platform lane: no
- Risk lane: yes
Acceptance criteria:
- In PR mode, relevant changes produce deterministic, idempotent comment updates.
- Non-relevant changes do not produce comments.
Dependencies:
- None
Risks:
- GitHub permission model differences by event type.

### Story E3-S2: Add operator docs for PR distribution and token model
Priority: P1
Tasks:
- Document required permissions, event constraints, and fail-closed behavior.
- Add explicit examples for scheduled vs PR mode usage.
- Add troubleshooting map for common auth failures.
Repo paths:
- `docs/`
- `README.md`
- `action/action.yaml`
Run commands:
- `make test-docs-consistency`
- `make test-docs-storyline`
- `scripts/run_docs_smoke.sh --subset`
Test requirements:
- Docs consistency and CLI parity checks.
- Docs smoke tests for command examples.
Matrix wiring:
- Fast lane: yes
- Core CI lane: no
- Acceptance lane: yes
- Cross-platform lane: no
- Risk lane: no
Acceptance criteria:
- A user can configure PR distribution without guessing token scopes or mode behavior.
Dependencies:
- E3-S1
Risks:
- Doc drift if behavior changes without updates.

## Epic E4: UAT and Release Gate Integration

Objective: Make install-path UAT, including Homebrew path validation, a first-class CI/release gate for launch confidence.

### Story E4-S1: Wire UAT install-path checks into release CI policy
Priority: P0
Tasks:
- Add `make test-release-smoke` and/or `make test-uat-local` into release workflow with policy-based invocation strategy.
- Enforce explicit prereq checks for Homebrew availability and tap token semantics.
- Upload UAT logs/artifacts in release workflow for auditability.
Repo paths:
- `.github/workflows/release.yml`
- `.github/workflows/main.yml` (if adding pre-release dry-run)
- `scripts/test_uat_local.sh`
- `Makefile`
Run commands:
- `make test-release-smoke`
- `scripts/test_uat_local.sh --skip-global-gates`
- `scripts/test_uat_local.sh --release-version vX.Y.Z --brew-formula Clyra-AI/tap/wrkr`
Test requirements:
- CI contract tests confirming new release job steps are present.
- UAT script negative tests (unsupported OS/arch, missing brew, missing args).
- Exit-code contract tests for dependency missing/input errors.
Matrix wiring:
- Fast lane: yes
- Core CI lane: yes
- Acceptance lane: yes
- Cross-platform lane: yes
- Risk lane: yes
Acceptance criteria:
- Release workflow includes deterministic install-path UAT execution.
- Failures are surfaced as blocking with actionable logs.
Dependencies:
- None
Risks:
- Runner environment variability for brew in CI.

### Story E4-S2: Add Homebrew-specific UAT acceptance checks and docs
Priority: P1
Tasks:
- Add acceptance assertions that Homebrew-installed binary passes JSON smoke and docs subset smoke.
- Document release-candidate UAT execution pattern.
Repo paths:
- `internal/acceptance/v1_acceptance_test.go`
- `scripts/test_uat_local.sh`
- `README.md`
Run commands:
- `go test ./internal/acceptance -run '^TestV1AcceptanceMatrix$' -count=1`
- `scripts/test_uat_local.sh --skip-global-gates`
Test requirements:
- Acceptance fixtures for brew path success/failure modes.
- Docs consistency updates for UAT procedure.
Matrix wiring:
- Fast lane: yes
- Core CI lane: yes
- Acceptance lane: yes
- Cross-platform lane: no
- Risk lane: no
Acceptance criteria:
- UAT acceptance explicitly covers Homebrew path readiness.
- Docs reflect exact pre-release invocation steps.
Dependencies:
- E4-S1
Risks:
- Keeping acceptance deterministic across environment differences.

## Epic E5: Research Output Completeness (Sections 2-10)

Objective: Fill remaining research-output gaps so Wrkr can produce every required report section with verifiable, deterministic machine-generated data.

### Story E5-S1: Implement approval status classification and ratio outputs
Priority: P0
Tasks:
- Add deterministic approval classification pipeline: `approved`, `unapproved`, `unknown`.
- Support explicit approved-list inputs (for example manifest/policy list) and deterministic matching rules.
- Emit aggregate approval-gap ratios for campaign/report outputs.
Repo paths:
- `core/cli/scan.go`
- `core/aggregate/inventory/`
- `core/report/build.go`
- `schemas/v1/inventory/inventory.schema.json`
- `schemas/v1/report/report-summary.schema.json`
- `docs/commands/scan.md`
Run commands:
- `go test ./core/aggregate/inventory -count=1`
- `go test ./core/cli -count=1`
- `go test ./core/report -count=1`
- `wrkr scan --path ./scenarios/wrkr/scan-mixed-org/repos --json`
Test requirements:
- Classification logic unit tests for approved/unapproved/unknown edge cases.
- JSON contract/schema tests for new approval fields.
- Deterministic repeat-run tests for ratio outputs.
- Fail-closed tests when approved-list input is invalid.
Matrix wiring:
- Fast lane: yes
- Core CI lane: yes
- Acceptance lane: yes
- Cross-platform lane: yes
- Risk lane: yes
Acceptance criteria:
- Each discovered tool carries deterministic approval status.
- Campaign/report outputs include reproducible approved vs unapproved ratios.
Dependencies:
- E2-S1
Risks:
- Misclassification risk if approved-list contracts are underspecified.

### Story E5-S2: Emit publication-grade methodology metadata
Priority: P0
Tasks:
- Add methodology metadata fields to scan/campaign outputs: wrkr version, scan start/end time, duration, repo count, file count processed.
- Emit detector inventory with deterministic IDs and versions.
- Ensure metadata is directly consumable by report Section 2 without manual reconstruction.
Repo paths:
- `core/cli/scan.go`
- `core/detect/defaults/defaults.go`
- `core/report/types.go`
- `schemas/v1/report/report-summary.schema.json`
- `docs/commands/scan.md`
Run commands:
- `go test ./core/cli -count=1`
- `go test ./core/report -count=1`
- `go test ./core/detect/defaults -count=1`
- `wrkr scan --path ./scenarios/wrkr/scan-mixed-org/repos --json`
Test requirements:
- CLI contract tests for field presence and type stability.
- Deterministic tests ensuring detector ordering/version emission is stable.
- Schema validation and backwards-compatible envelope tests.
Matrix wiring:
- Fast lane: yes
- Core CI lane: yes
- Acceptance lane: yes
- Cross-platform lane: yes
- Risk lane: yes
Acceptance criteria:
- Methodology fields required for report credibility are emitted in machine-readable output.
- No manual metadata interpolation is needed for publication.
Dependencies:
- E2-S1
Risks:
- Version provenance drift if detector/version registry is not centralized.

### Story E5-S3: Add tool taxonomy and deterministic confidence scoring
Priority: P0
Tasks:
- Add canonical taxonomy fields for report inventory categories (assistant, agent/framework, MCP/integration, plugin/extension, model/api integration, custom wrapper).
- Add deterministic confidence scoring/ranking per detection, with documented rubric.
- Expose taxonomy/confidence in scan, inventory, and export outputs.
Repo paths:
- `core/model/`
- `core/detect/`
- `core/aggregate/inventory/`
- `schemas/v1/inventory/inventory.schema.json`
- `docs/commands/scan.md`
Run commands:
- `go test ./core/detect/... -count=1`
- `go test ./core/aggregate/inventory -count=1`
- `go test ./core/cli -count=1`
- `wrkr scan --path ./scenarios/wrkr/scan-mixed-org/repos --json`
Test requirements:
- Detector unit tests for taxonomy mapping consistency.
- Determinism tests for confidence score stability across repeated runs.
- Schema and CLI contract tests for added fields.
Matrix wiring:
- Fast lane: yes
- Core CI lane: yes
- Acceptance lane: yes
- Cross-platform lane: yes
- Risk lane: yes
Acceptance criteria:
- Inventory tables can be generated directly from machine outputs with category and confidence columns.
- Confidence logic is deterministic and documented.
Dependencies:
- E1-S2
Risks:
- Overfitting confidence heuristics without clear rubric boundaries.

### Story E5-S4: Normalize permission surface and emit report risk tiers
Priority: P0
Tasks:
- Normalize permission semantics to report-ready classes (`read`, `write`, `admin`) plus scope targets.
- Emit deterministic report risk tier (`critical`, `high`, `medium`, `low`) based on explicit permission + environment rules.
- Add example/edge-case fixtures for prod-write, credential-store, infra-provisioning, and sandboxed read-only cases.
Repo paths:
- `core/aggregate/privilegebudget/`
- `core/risk/`
- `core/report/build.go`
- `schemas/v1/report/report-summary.schema.json`
- `internal/scenarios/`
Run commands:
- `go test ./core/aggregate/privilegebudget -count=1`
- `go test ./core/risk -count=1`
- `go test ./core/report -count=1`
- `go test ./internal/scenarios -count=1 -tags=scenario`
Test requirements:
- Deterministic tier-classification tests for rule boundary conditions.
- Scenario fixtures covering each severity tier with stable expected outputs.
- Contract tests for new permission/tier fields.
Matrix wiring:
- Fast lane: yes
- Core CI lane: yes
- Acceptance lane: yes
- Cross-platform lane: yes
- Risk lane: yes
Acceptance criteria:
- Privilege and access map section can be generated from deterministic risk-tier outputs.
- Tier logic is explainable and reproducible.
Dependencies:
- E2-S3
Risks:
- Ambiguous mappings between raw permissions and normalized classes.

### Story E5-S5: Add adoption pattern detection (org-wide vs individual)
Priority: P1
Tasks:
- Add adoption pattern classification based on config location/scope (org-level, repo-level/team, individual developer, one-off).
- Emit per-tool adoption pattern and aggregate distribution.
- Document assumptions and false-positive boundaries for publicly scanned repos.
Repo paths:
- `core/detect/`
- `core/aggregate/inventory/`
- `core/report/build.go`
- `internal/scenarios/`
- `docs/commands/scan.md`
Run commands:
- `go test ./core/detect/... -count=1`
- `go test ./core/aggregate/inventory -count=1`
- `go test ./internal/scenarios -count=1 -tags=scenario`
Test requirements:
- Detector/path-scope unit tests for pattern inference.
- Scenario tests with mixed org/repo/dev-scope fixtures.
- JSON contract tests for adoption pattern fields.
Matrix wiring:
- Fast lane: yes
- Core CI lane: yes
- Acceptance lane: yes
- Cross-platform lane: yes
- Risk lane: yes
Acceptance criteria:
- Approval-gap narrative can be quantified with adoption pattern evidence.
- Pattern outputs are deterministic and documented.
Dependencies:
- E1-S2
Risks:
- Scope inference ambiguity on repositories with sparse metadata.

### Story E5-S6: Emit per-tool regulatory exposure matrix
Priority: P0
Tasks:
- Extend compliance mapping to output per-tool, per-regulation/control/article status (covered/gap/unknown).
- Support report-ready mappings for EU AI Act, SOC 2 AI controls, Colorado AI Act, Texas TRAIGA, NIST AI RMF.
- Add deterministic gap-count rollups by regulation and control family.
Repo paths:
- `core/compliance/`
- `core/evidence/`
- `core/report/`
- `schemas/v1/report/report-summary.schema.json`
- `docs/commands/evidence.md`
Run commands:
- `go test ./core/compliance -count=1`
- `go test ./core/evidence -count=1`
- `go test ./core/report -count=1`
- `wrkr evidence --frameworks eu-ai-act,soc2 --state ./.tmp/state.json --json`
Test requirements:
- Mapping logic tests for each supported framework/control family.
- Schema tests for per-tool regulatory matrix output.
- Determinism tests for matrix ordering and gap totals.
Matrix wiring:
- Fast lane: yes
- Core CI lane: yes
- Acceptance lane: yes
- Cross-platform lane: yes
- Risk lane: yes
Acceptance criteria:
- Regulatory section can be generated without manual control-by-control mapping.
- Outputs are citeable and reproducible from command artifacts.
Dependencies:
- E2-S1, E5-S3
Risks:
- Framework version drift causing mapping churn.

### Story E5-S7: Add anonymized export mode for case-study narratives
Priority: P1
Tasks:
- Add deterministic anonymization mode for org/repo identifiers in report/export outputs.
- Preserve technical pattern detail (tool names, access patterns, controls) while removing direct attribution.
- Add stable pseudonym scheme to keep cross-table joins possible without de-anonymization.
Repo paths:
- `core/cli/report.go`
- `core/cli/export.go`
- `core/report/`
- `docs/commands/report.md`
- `docs/commands/export.md`
Run commands:
- `go test ./core/report -count=1`
- `go test ./core/cli -count=1`
- `wrkr report --template public --share-profile public --json`
- `wrkr export --format inventory --json`
Test requirements:
- Redaction tests verifying no raw org/repo leakage in anonymized mode.
- Deterministic pseudonym tests across repeated runs.
- Contract tests for anonymized field semantics.
Matrix wiring:
- Fast lane: yes
- Core CI lane: yes
- Acceptance lane: yes
- Cross-platform lane: no
- Risk lane: yes
Acceptance criteria:
- Case-study source outputs are publication-safe by default when anonymization is enabled.
- Anonymized outputs remain analytically useful and deterministic.
Dependencies:
- E2-S2
Risks:
- Potential over-redaction reducing narrative utility.

### Story E5-S8: Add segment-level aggregation for benchmark comparisons
Priority: P1
Tasks:
- Add optional org metadata tagging/ingestion for segment attributes (industry, size band, scan scope).
- Emit segmented aggregates for headline and benchmark tables.
- Keep segmentation optional and fail-closed when metadata is missing or malformed.
Repo paths:
- `core/cli/scan.go`
- `core/source/github/`
- `core/report/`
- `schemas/v1/report/report-summary.schema.json`
- `docs/commands/scan.md`
Run commands:
- `go test ./core/source/github -count=1`
- `go test ./core/report -count=1`
- `go test ./core/cli -count=1`
- `wrkr campaign aggregate --input-glob './.tmp/campaign/*.json' --json`
Test requirements:
- Unit tests for segment assignment and fallback behavior.
- Contract tests for segmented output structures.
- Determinism tests for segment aggregation ordering.
Matrix wiring:
- Fast lane: yes
- Core CI lane: yes
- Acceptance lane: yes
- Cross-platform lane: yes
- Risk lane: yes
Acceptance criteria:
- Benchmark section inputs are available directly from deterministic outputs.
- Missing segment metadata yields explicit, machine-readable unknown buckets.
Dependencies:
- E2-S1
Risks:
- Public metadata quality variance across organizations.

### Story E5-S9: Add appendix-grade tabular export suite (CSV + JSON)
Priority: P1
Tasks:
- Extend export command with tabular formats for inventory, privilege map, approval gap, and regulatory matrix.
- Add deterministic column ordering and schema/version headers for citation stability.
- Add docs/examples for generating appendix tables directly from CLI.
Repo paths:
- `core/cli/export.go`
- `core/export/`
- `docs/commands/export.md`
- `schemas/v1/`
- `internal/e2e/`
Run commands:
- `go test ./core/export/... -count=1`
- `go test ./core/cli -count=1`
- `go test ./internal/e2e/... -count=1`
- `wrkr export --format inventory --json`
Test requirements:
- CSV formatting and escaping tests.
- Contract tests for format flags, headers, and versioned schema metadata.
- Deterministic byte-stability tests for repeated exports.
Matrix wiring:
- Fast lane: yes
- Core CI lane: yes
- Acceptance lane: yes
- Cross-platform lane: yes
- Risk lane: yes
Acceptance criteria:
- Appendix tables can be generated directly via Wrkr CLI without manual data reshaping.
- Export outputs are deterministic and versioned for external citation.
Dependencies:
- E5-S1, E5-S3, E5-S4, E5-S6
Risks:
- Format surface expansion increasing compatibility maintenance burden.

## Minimum-Now Sequence

1. E1-S1 (pagination)  
2. E1-S2 (repo/org materialization for detector coverage)  
3. E2-S1 (campaign aggregation artifact)  
4. E5-S2 (methodology metadata export)  
5. E5-S3 (taxonomy + deterministic confidence)  
6. E5-S4 (permission normalization + risk tiers)  
7. E5-S1 (approval classification + ratios)  
8. E5-S6 (per-tool regulatory matrix)  
9. E2-S3 (production-write claim guardrails)  
10. E3-S1 (action PR comment wiring)  
11. E4-S1 (UAT into release gate)  
12. E2-S2 + E3-S2 + E4-S2 + E5-S5 + E5-S7 + E5-S8 + E5-S9 (publication package completion)

## Explicit Non-Goals

- No dashboard-first implementation in core backlog.
- No probabilistic ranking or narrative generation via LLM in evidence path.
- No broad IaC semantic expansion in this tentpole scope (Terraform/Kubernetes deep parsers are separate roadmap).
- No changes to proof-chain cryptographic primitives unless directly required by contract defects.

## Definition of Done

- Every recommendation R1-R17 is implemented and traceable to merged stories.
- All impacted test lanes are green with deterministic rerun stability.
- Campaign artifact exists and can reproduce headline numbers from fixed inputs.
- PR distribution in action `mode=pr` is functional, deterministic, and idempotent.
- Release gate includes install-path UAT with Homebrew-path validation.
- Docs are updated for commands, methodology, and claim limitations.
- Report production structure can be populated from Wrkr artifacts for all required sections except explicitly narrative editorial copy.
- `make prepush-full` passes, and release workflow gates pass in CI.
