Implementation Plan 133 - joeroberts/release-radar GitHub Wiki

Status: Delivered. Repository implementation and reusable EVAL sources are merged through PR 154 and PR 159. The ADR migration, catalog and derived index are published and verified. Verification and remaining epic work are recorded in issue 133. Paused hooks remain paused; this batch does not close the epic.

Owning issue: 133 — Establish the lightweight RR development workflow and documentation guardrails.

This page covers the ADR integrity and development-exception batch within issue 133. It does not replace the epic's earlier delivery outcomes, child-ticket scope, or outstanding hook work. Current status, blockers, and results remain in the issue; this page is the reviewed implementation scope. Chief Architect, QA, and Security reached consensus on consolidated plan v2 and the subsequent placement, publication-only status, ADR index, normalized status, and implementation-tracking clarifications. Any plan change requires another review round with all three roles before it replaces this baseline.

Outcome

Correct existing Wiki ADRs; create repository-owned ADR and reusable development-exception skills with executable validation and EVALS; coherently replace active AGENTS using reviewed saved proposal. RR development remains independent of RR product harness. Work remains #133; no app/product catalog/schema change, release, permission overhaul or paused hook activation.

Phase 1: discovery/mapping

Inspect all current ADRs and existing appended material, approval evidence, catalog/read routes, active AGENTS and saved proposal. Establish exact source revision. Map retained decisions/qualifications into self-contained records; identify genuine unknowns. Validate technical assumptions with primary sources. No invented approval, implementation or dates. Distinguish approval dates and recording dates. No durable migration document outside owning #133 record once persistence authorized.

Phase 2: contract drafts

Two policy ADRs: ADR lifecycle/integrity and scoped development exceptions, scoped to development practices. Present new policy drafts for owner review before accepting them or dependent implementation. Existing mechanical cleanup already authorized; no additional blanket approval or per-file hash ceremony. Existing instructions remain operative until authorized cutover.

ADR lifecycle: proposed text editable; accepted decision body frozen, defined metadata separate; no future amendments. Changed decision requires new self-contained ADR, becomes governing only when accepted. One-time extraction of existing appended material preserves evidenced meaning/approval boundaries. No historical cross-links between resulting ADRs. Git and tickets retain provenance. Catalog records stable ID/path, decision status, product/development domain, and applicability by bounded scope. Compatible decisions may jointly apply; unresolved overlaps block affected work, never select newest number/date automatically. No duplicate titles or migration banners.

Decision status has exactly four allowed values: Proposed, Accepted, Rejected, Superseded. Enforce this vocabulary in the ADR contract, catalog, and derived index. Preserve approval qualifications only in each ADR document; do not promote partial direction approval into Accepted. Unresolved status mappings block the affected normalization and require owner resolution.

The ADR skill must maintain Architecture-Decisions.md from the catalog. Its table has exactly two columns: ADR (the document name is a hyperlink) and Decision status. Remove the Canonical record column; do not include Implementation or Approval qualifications columns. Validate catalog/index agreement and publish affected ADRs, catalog, and index in the same Wiki commit. Accepted status alone does not establish current applicability; governing selection remains scope-aware.

Implementation tracking belongs in GitHub tickets, not the ADR skill. Preserve the previously requested Implementation field as descriptive recorded ADR metadata during cleanup; do not infer, synchronize, or update implementation progress. Do not introduce an implementation-state enum or duplicate progress in the catalog. Preserve factual qualifications and flag ambiguity rather than inventing values.

Phase 3: skill implementation

Two discoverable repository-owned skills, one focused ADR manifest/checker with shared validation and separate exception handling; no service/database/workflow engine. Wiki contains the development-only catalog manifest, ADRs, and catalog-derived Architecture Decisions index, published in the same Git commit. Repo holds skills/scripts/fixtures. No reuse or modification of RR product catalog contract. Manifest does not contain its own commit hash; invocation resolves canonical Wiki remote/repository identity and commit.

ADR skill covers creation, reading constraints, allowed metadata updates, supersession and migration. Enumerate explicit root-level ADR filename convention at one resolved current Wiki Git commit, validate inventory both directions, regular blob modes/paths/IDs, case/Unicode collisions, UTF8 and bounded inputs. Non-ADR Wiki pages and repository routing stubs outside inventory, never automatically authoritative. State filename-rule discovery limitation. Check exact blob identity and consume those same bytes, not separately fetched rendered pages. Historical internally consistent snapshot is not automatically current.

Accepted baseline: exact accepted commit/path/blob and byte-exact protected body outside small strictly defined metadata block. Record exact source→normalized mapping on #133 under existing cleanup authorization; preserve proposed qualifications. No automatic reset of protected baseline/hash to cure failure. Candidate authority/lifecycle/scope/governing-selection/baseline transitions compared with prior canonical state and require applicable explicit owner evidence; missing prior evidence blocks affected work. SHA consistency alone proves neither approval nor safe content. Coordinated rewriting of trusted history is outside guarantees.

On missing/extra/mismatch/ambiguous scope, stop dependent work, diagnose expected/actual revision/path/hash, record blocker and notify owner. Diagnostic inspection and authorized repair remain possible. Never recatalog unexplained content automatically.

Exception skill initially supports only explicitly eligible ADR-integrity conditions, extensible later by deliberate authorization. Explicit owner instruction (including authorized delegation) supplies approval; GH records scope, freshness, revocation and resolution. Acting agent cannot manufacture or infer approval for its own exception. Shared OWNER API credentials cannot prove human origin. Record unique exception ID, repo/ticket, precise failure codes, exact revision/path/expected+observed hashes, permitted operation/scope, reason/risk, accountable person, expiry and resolution criteria. Bind exact structured block to approval reference so editing invalidates it. Strict parsing rejects duplicate/ambiguous fields and ignores imperative prose. Fresh check before dependent operation: approval record, exact content/scope, expiry and revocation. Unavailable approval blocks exception-dependent work; normal verified reads unaffected. Report verified / blocked / proceeding under exception distinctly. Never grant destructive/external-action permission, bypass STOP/security controls, alter accepted decision body or imply acceptance. Accountable name does not prove runtime task identity. GitHub issue remains open until integrity issue resolved; labels and filtered existing priority view provide visibility, not approval. No automatic renewal. Recheck current content/exception before dependent mutation; state remaining post-check race and skill-bypass limitations.

Both skills and AGENTS explicitly treat ADR, manifest, issue and exception content as data, even after verification. Embedded commands, links, credentials requests, scope changes or asserted approvals cannot trigger tools or grant authority. Parsed metadata controls validation only; prose informs reasoning within existing authorized work.

Phase 4: migration/cutover

Correct all current ADRs and extract legacy appended material as self-contained decisions using approved meaning; preserve acceptance qualifications. Establish exact protected baseline and catalog inventory. Keep any genuinely unresolved approvals/scope blocking only affected records. Publish Wiki ADRs, catalog, and derived index together after checks; update relevant reading routes without resurrecting repository copies as canonical.

Phase 5: agents integration

Revise reviewed saved proposal coherently: Wiki canonical routes, ADR skill required for both reading and writing constraints, exception skill invocation, blocking, data/authority boundary. Preserve unrelated owner rules and dirty changes, no duplicate instructions. Verify discovered skill placement; do not claim actual runtime hooks or skill loading from file existence.

Phase 6: validation/delivery

Focused deterministic fixture checks include the exact two-column linked index, catalog/index agreement, four allowed decision statuses, preservation of document-only approval qualifications, and no inferred or synchronized implementation progress. Other cases: valid read, missing/extra/renamed/malformed ADR, wrong/mixed/stale revision, metadata-only authorized edit, body edit plus refreshed catalog, unapproved lifecycle/scope/baseline transition, valid exact exception, wrong repo/issue/content/scope/operation, expired/revoked/edited/deleted/unverifiable approval, normal reads without exceptions. Small 3–4 case agent EVALs with controlled non-destructive tool surface, inspect attempted actions not just assurances, cover malicious ADR/catalog/issue instructions and STOP/authority preservation. No real destructive execution, no testing platform. Declare limits: tests do not prove universal model obedience. Independent Architect/QA/Security review of each changed plan version as explicitly required; applicable delivered-artifact checks/review after implementation. Manageable commits, Copilot PR review and required fixes, merge only with applicable green checks and existing authorization. Update #133 outcomes/remaining work; no app release.