policy: optimize the agent protocol for strict, executable compliance

[localai-bot]

Scope

Contract-first redesign of the repository agent protocol: one compact CSV rule registry, a smaller AGENTS.md index, fewer active policy files, executable helper/claim/PR/trailer/waiver enforcement, and agent-agnostic prompt contracts.

Accepted design

• docs/superpowers/specs/2026-08-07-internal-policy-optimization-design.md
• preserves purpose-specific STATUS, BENCHMARKS, FEATURES, USAGE, README, and NOW obligations
• keeps the full structured-record conversion and evidence migration in a separate follow-up PR

Current state

Design committed and preflight-green. Implementation has not started; this PR remains draft pending explicit review of the written specification.

Verification

• scripts/agent-preflight.sh --staged --quiet
• scripts/agent-preflight.sh --quiet
• git diff --check

FOLLOWING_AGENTS_PROTOCOL

[localai-bot]

Implementation run checkpoint (blocked, no red head pushed):

• Reviewed-good local commit f8510465 adds the 57-rule policy/waiver registry and passes 21 focused mutation tests.
• It remains unpushed because mandatory preflight is red on the legacy doc-checkpoint classifier, which misclassifies governance parser/checker files as feature checkpoints.
• Prompt semantic enforcement exhausted two attempts: the final review still found missing remediation/severity fields, contradictory-prose bypasses, missing-input bypasses, and surviving legacy phrase pins. Rejected commits were rolled back.
• Purpose-specific document enforcement exhausted two attempts: the final review found an exception-clause inversion (for example, except when state is appended) that stayed green. Rejected commits were rolled back.
• Role/claim, trailer/waiver/path, consolidation, and cutover tasks were skipped because they cannot pass mandatory preflight until the document-classifier task is reviewed green.

PR head remains the accepted design. The next run should resume from the retained worktree metadata, fix the document exception-clause semantic mutation first, then rerun preflight before pushing the reviewed policy registry.

[localai-bot]

Resume-run checkpoint (blocked; rejected commits rolled back, no red head pushed):

• Root cause was confirmed: unrestricted prose plus keyword/negation checks cannot prove policy polarity. The resumed design changed public rules to controlled trigger IDs and a full-string positive action/target grammar.
• Attempt 1 passed 59 focused mutations and preflight, but review found that extra policy rows could reuse reserved public triggers/scopes outside the six parsed IDs.
• Attempt 2 closed the global namespace and passed 64 focused mutations and preflight, but final review found a parser bug: Update docs/STATUS.md.. lets the greedy target absorb a trailing period and bypass reserved-target ownership.
• Both rejected commits were rolled back. Local reviewed-good commit f851046 remains the only implementation commit; it is still unpushed because the legacy document classifier keeps mandatory preflight red.
• Dependent prompt, role/claim, trailer/waiver, consolidation, and cutover tasks were skipped.

Retained run metadata records the exact next red test: reject target punctuation/trailing delimiters by parsing the target token with a restricted path grammar rather than a greedy catch-all.

[localai-bot]

Operator review (design doc only, not landing it autonomously): the audit section is verified substantially CORRECT — the boot-order contradiction (AGENTS.md:3 vs :39), the coordination.md hand-claims vs PR-derived-claims drift, the README-at-checkpoint contradiction, and the trailer gate being a substring match rather than a validated Git trailer all check out against current main, and several enforcement-gap claims (agent-role.py accepting helper mode in the primary checkout; claim-view's 14-day snapshot staleness) match incidents this operator has personally hit. Direction endorsed: executable compliance over prose is exactly where the last two days of guard work (check-surface-coverage, preflight wiring) have been pushing. HOWEVER: this is a protocol-governance redesign and its 'Status: accepted design' line is not something a lane self-declares — acceptance is the human maintainer's call, explicitly. Parking blocker: awaiting maintainer (@mudler) sign-off on the design before the implementation PR proceeds; on acceptance, the status line should cite that sign-off. One design note to address either way: the CSV rule registry must not become a second source of truth for rules that remain stated in prose — the doc-obligation-contract precedent (block asserted equal to checker constants AND present verbatim in the manual) is the pattern that survives here.

[localai-bot]

Policy optimization head e3135720 is pushed and independently reviewed (PASS, no P1/P2). Local full preflight, PR-size, documentation classification, and post-cutover trailer checks are green.

GitHub CI confirms the policy-specific corrections: documentation-checkpoint, commit-protocol-tag, pr-size, Agent role machinery and role discipline, and Claim view, helper queue and PR reviewability all pass.

Two base-tree blockers remain and are intentionally not folded into this policy PR:

• device-leakage: current main contains a hard-coded kCUDA at src/vllm/v1/worker/gpu/runner.cpp:107.
• agent-record final live-state audit: current records mark MODEL-EMBED-llama-llama-for-causal-lm ACTIVE, but GitHub has neither a row/MODEL-EMBED-llama-llama-for-causal-lm branch nor a matching commit on main. Local preflight had been masked by an orphan local-only branch; clean CI correctly reports it ABANDONED.

The PR remains unmerged pending those base-state repairs and an approving GitHub review.