Execution Plan: P1 Invariant Encoding

Date: 2026-08-11

Status

Completed

Outcome

A clean consumer installed from this branch receives the complete, generic P1 workflow for discovering accepted invariants and encoding them in repository- native validation, with coherent source, embedded, and installed inventories.

Context

• Project-owner directive in the initiating task: accepted scope and product authority for P1.
• AGENTS.md and docs/WORKFLOW.md: repository-first authority and proof gates.
• docs/ARCHITECTURE.md: generic installed-core and consumer-ownership boundary.
• Decisions 0020, 0026, and 0028: installed knowledge boundary, explicit onboarding, and authoritative invariant encoding.
• scripts/harness-install-files.txt and crates/harness/src/infrastructure/embedded_distribution.rs: canonical and embedded payload owners.

Scope

In scope:

• Compact routing, workflow decision flow, installed invariant pattern, and request-triggered encode-invariant skill.
• Read-only onboarding comparison of documented invariants and checks.
• Payload, release classification, documentation map, tests, and clean install evidence.

Out of scope:

• Consumer architecture, language, linter, hook, CI-provider, merge-policy, or branch-protection prescriptions.
• Installing hooks or mutating external repository settings.
• Push, PR, merge, release publication, or external branch changes.

Approach

1. Extend existing repository guidance and skills without adding a new control plane or enforcement framework.
2. Wire each installed file through the manifest and embedded distribution.
3. Add contract assertions for authority, inventory coherence, release classification, installed content, links, and positive/negative behavior.
4. Validate the skill, focused contracts, a clean branch-candidate install, and the repository premerge gate.

Risks And Recovery

• Risk: entrypoint bloat. Keep the managed block below its existing byte and combined-context budgets.
• Risk: invented consumer policy. Require accepted documentary authority and keep examples implementation-neutral.
• Risk: source/embedded drift. Compare exact inventories and exercise the real installer from a clean temporary consumer.
• Recovery: all changes are Git-local; revert this plan's bounded diff if the acceptance gate cannot be restored.

Progress

• [x] Read repository authority, install path, payload owners, and current tests.
• [x] Implement routing, workflow, pattern, skill, and onboarding enhancement.
• [x] Wire source, embedded, release, documentation, and test inventories.
• [x] Run focused validation and fresh-install acceptance.
• [x] Run required premerge validation and record the result.

Decisions

• 2026-08-11: Use one installed docs/patterns/encoding-invariants.md owner for detailed guidance; keep AGENTS.md as a short route.
• 2026-08-11: Allow $encode-invariant to trigger only on matching user requests. Decisions 0020 and 0026 make onboarding and audit skills explicit-only, not every core skill; installation still invokes no skill.
• 2026-08-11: Keep all writes with Lead because payload source, embedding, and integration tests form one moving acceptance scope; use a Peer read-only.

Validation

• Focused proof: both changed skills passed quick_validate.py; authority, workflow, docs, release classification, embedded-inventory, and installer contracts passed.
• Integration or end-to-end proof: repository-owned Bash install tests built the branch candidate, installed clean temporary consumers, found all P1 artifacts, resolved every installed local Markdown link, and matched all 26 declared and embedded managed paths.
• Independent review: all 23 candidate files reviewed. Accepted findings added per-path release classification and full invariant-method contract coverage; the stronger test exposed and corrected missing release matching for the managed AGENTS block and payload manifest.
• Repository-required checks: scripts/validate-premerge.sh passed on 2026-08-11 after all review corrections.

Result

The branch candidate installs all P1 artifacts through the repository-owned path. Source, embedded, and installed inventories agree; installed links resolve; focused skill and contract checks pass; and the complete premerge gate passes. No hook, CI setting, merge policy, branch protection, push, PR, merge, or release publication was performed.