tech-log-backend/docs/superpowers/plans/2026-07-20-harness-policy-engine.md

Harness Policy Engine Implementation Plan

Spec: docs/superpowers/specs/2026-07-20-harness-policy-engine-design.md

Goal: Replace topology- and platform-specific duplicated harness rules with a registry, strict evidence validators, generated platform variants, and risk-based review policies.

Working policy: human-only commits. Each task leaves changes in the working tree.

Task 1 — Registry, resolver, and Gradle SSOT

Files:

• Add .harness/project/modules.yaml
• Add .harness/lib/module_registry.py
• Add .harness/validators/validate_modules.py
• Add .harness/tests/test_module_registry.py
• Modify src/settings.gradle
• Modify the dependency-verifier section of src/build.gradle

Steps:

• Write failing tests for 19-leaf loading, nested owner resolution, nearest CLAUDE.md, unknown paths, and settings/registry parity.
• Add the registry and stdlib loader/resolver.
• Make Gradle settings and dependency verification consume registry data.
• Run Python tests and ./gradlew projects verifyCleanArchitectureDependencies.

Task 2 — Registry-driven import gate and mutation suite

Files:

• Modify .claude/hooks/ca_import_gate.py
• Modify .claude/hooks/test_ca_import_gate.py
• Add .harness/tests/test_import_gate_mutations.py

Steps:

• Add failing real-path tests for every registered production module.
• Replace flat-path regex/prefix rules with registry owner and role policy.
• Normalize Claude snake_case and Antigravity camelCase tool events.
• Fail closed on malformed in-scope events and marker failures.
• Run all import-gate tests.

Task 3 — Verdict schema, evidence artifacts, and platform adapters

Files:

• Add .harness/schemas/verdict.schema.json
• Add .harness/schemas/evidence.schema.json
• Add .harness/lib/verdict.py
• Add .harness/validators/validate_verdict.py
• Add .harness/validators/validate_evidence.py
• Add .harness/adapters/antigravity_hook.py
• Add .harness/tests/test_verdict.py
• Modify .claude/hooks/ca_verdict_gate.py
• Modify .claude/hooks/test_ca_verdict_gate.py
• Add .agents/plugins/ca-superpowers/hooks.json

Steps:

• Write negative tests for missing required enums, negative counts, Gradle arithmetic, behavior change without red, missing upstream artifacts, malformed input, and revision mismatch.
• Implement strict validation and evidence recording with source/diff hashes.
• Adapt Claude fenced verdicts to the common model.
• Add Antigravity Stop/pre-tool adapter and plugin hook wiring.
• Run validator, adapter, and JSON syntax tests.

Task 4 — Canonical agents and deterministic rendering

Files:

• Add .harness/agents/*.md
• Add .harness/project/platforms.yaml
• Add .harness/generators/render_agents.py
• Add .harness/tests/test_platform_parity.py
• Regenerate .claude/agents/*, .codex/agents/*.toml, .agents/agents/*/agent.json
• Update .agents/plugins/ca-superpowers/README.md and plugin.json
• Update .codex/agents/README.md

Steps:

• Seed canonical sources from the newest human-only Claude policy, then update module discovery and runner validation to use the registry.
• Add generated metadata and stable output ordering.
• Render all variants and add a --check parity mode.
• Assert commit policy, source hashes, tool permissions, and body parity in tests.

Task 5 — Risk/profile policies and guidance drift cleanup

Files:

• Add .harness/manifest.yaml
• Add .harness/core/risk-policy.yaml, .harness/core/evidence-policy.yaml
• Add current architecture/language/build/framework/capability profile files
• Add .harness/validators/resolve_task.py and tests
• Modify AGENTS.md, root CLAUDE.md, clean-architecture rule, workflow skill, advisory-depth rule, reporting-standards rule, and plugin README
• Modify stale module CLAUDE.md files and add missing leaf-module guidance where useful

Steps:

• Add failing task-classification tests for high-risk one-file changes and low-risk multi-file fixture/docs changes.
• Implement profile resolution.
• Replace N!, routine all-quote grep, file-count report split, and unconditional counterargument policies with the design profiles.
• Replace flat module documentation and focused commands with registry-backed nested names.
• Run policy grep assertions and harness tests.

Task 6 — Full review and verification

• Run harness unit/mutation/parity suite.
• Run ./gradlew projects and ./gradlew verifyCleanArchitectureDependencies.
• Run the focused ArchUnit suite.
• Run ./gradlew check.
• Audit the working-tree diff in order: architecture → spec → quality.
• Fix findings and restart the review chain, up to three loops.

Task 7 — LLM Wiki capture

• Read the LLM Wiki authority and branch-note template.
• Update/create the detached-HEAD branch note with implementation decisions, changed files, verification evidence, failures, and open risks.
• Create/link derived error, interview, or blog-topic raw notes only when supported by the completed work; otherwise record an explicit “none” judgment in the branch note.