docs(agent-loop): plan repository-native SDLC assurance

.agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/CHUNK_MAP.md

@@ -0,0 +1,15 @@
+# Chunk Map: WS-ENG-008 — Repository-Native SDLC Assurance
+
+| Order | Chunk | Purpose | Risk | Dependency | State |
+|---:|---|---|---:|---|---|
+| 1 | `WS-ENG-008-01` | Enforce versioned machine-checkable chunk scope | L1 | Planning merge and signed start | Proposed |
+| 2 | `WS-ENG-008-02` | Add read-only scheduled signed-state drift audit | L1 | 01 | Proposed |
+| 3 | `WS-ENG-008-03` | Add risk-routed adversarial proof records | L1 | 01 | Proposed |
+| 4 | `WS-ENG-008-04` | Add bounded loop-memory property invariants | L1 | 01–03 | Proposed |
+| 5 | `WS-ENG-008-05` | Add bounded authorization property invariants | L1 | 04 and canonical AUTH reconciliation | Proposed |
+| 6 | `WS-ENG-008-06` | Run a non-blocking changed-module mutation pilot | L1 | 01, 04–05, canonical CI/QUALITY reconciliation | Proposed |
+| 7 | `WS-ENG-008-07` | Migrate root review history to a lossless indexed archive | L1 | Active root-log writers reconciled | Proposed |
+
+Only `WS-ENG-008-01` is named by the planning merge intent. Every later chunk
+must be named by its predecessor's reviewed merge intent and receive a separate
+signed start. No chunk starts automatically.

.agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/DECISIONS.md

@@ -0,0 +1,42 @@
+# Decisions: WS-ENG-008 — Repository-Native SDLC Assurance
+
+## D1 — Preserve the zero-trust loop as the enforcement mechanism
+
+“Repository-Native Human-Agent SDLC” names the broader development model. The
+Codex-native zero-trust engineering loop remains its enforcement mechanism and
+is not renamed away.
+
+## D2 — Enforce future contracts without guessing historical intent
+
+Machine scope applies to every implementation/specification start whose trusted-
+main basis contains the `WS-ENG-008-01` merge intent. Chunk 01 must upgrade its
+already-reviewed ENG-008 successors 02–07 before selecting 02. Chunks already
+signed-active at cutover are the only grandfather set and remain bound to their
+exact start event, contract blob, reviewed evidence, and existing gates.
+
+## D3 — Keep scheduled drift verification read-only
+
+The scheduled job can detect and report but cannot sign, repair, push, dispatch,
+approve, or merge.
+
+## D4 — Route adversarial proof instead of adding a universal reviewer
+
+Risk routing assigns explicit adversarial proof to high-risk work using existing
+review ownership. Evidence records attempts and outcomes, not an empty file.
+
+## D5 — Measure mutation quality before setting a threshold
+
+The pilot is non-blocking and cannot reduce existing coverage gates. A blocking
+mutation policy requires a later reviewed human decision based on hosted data.
+
+## D6 — Reconcile concurrent initiatives at every boundary
+
+Planning uses current signed state, but each implementation start, review,
+publication, and merge repeats current-main and overlap checks. AUTH property
+work and root-log archival have explicit concurrency waits.
+
+## D7 — Archive review memory losslessly
+
+Root review memory becomes an index only after byte-preserving archives and
+link/reconstruction proof exist. Initiative review directories remain detailed
+evidence.

.agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/DISCOVERY.md

@@ -0,0 +1,129 @@
+# Discovery: WS-ENG-008 — Repository-Native SDLC Assurance
+
+Discovery was performed read-only against trusted `main`
+`bcf1292e1a591e3e84bf8ee212ee7191d80741fa` and signed
+`automation/loop-memory` tip
+`8affe98a0b877ba79abf9d23f86013f838985dcf` on 2026-07-24.
+
+Before final planning publication on 2026-07-26, the branch was reconciled to
+trusted `main` `a04fd1a0a623b7150ec40c9934a9982f80a2dce7` and signed
+`automation/loop-memory` tip
+`33edd1a682ea5fe5ea973870f89bdd3a75a63da3`. The historical observations below
+remain discovery provenance; the current signed projection is recorded in the
+reconciliation addendum.
+
+## Current behavior
+
+- `scripts/check_internal_review_evidence.py` discovers changed files, resolves
+  required reviewer tracks, binds reviewed SHA provenance, and restricts
+  post-review changes. It does not parse or enforce contract path scope.
+- `.agent-loop/templates/CHUNK_CONTRACT.md` requires human-readable allowed and
+  forbidden sections without a machine-readable schema.
+- Some historical chunks use one-off shell regexes or reviewed-scope manifests;
+  there is no reusable canonical implementation.
+- `.github/workflows/agent-gates.yml` runs evidence, merge-intent, Markdown,
+  stale-contract, and regression gates. No workflow uses `schedule`.
+- `scripts/update_post_merge_memory.py` and
+  `scripts/check_loop_memory_state.py` already verify signed-state semantics and
+  closed-tree integrity during merge/start workflows.
+- `.codex/agents/` contains senior, QA, security, product/ops, architecture, CI,
+  docs, reuse, and test-delta reviewers. No explicit adversarial proof contract
+  exists.
+- `scripts/agent-gate-requirements.txt` and `backend/pyproject.toml` contain no
+  Hypothesis or mutation-testing dependency.
+- At original discovery, Backend CI fanned out four isolated shards and
+  recombined exact artifacts. Final reconciliation records the replacement
+  four exact-custody semantic lanes. Both designs preserve the 78 percent global
+  coverage floor plus multiple 90 percent protected subsystem floors.
+- `.agent-loop/REVIEW_LOG.md` is 147,017 bytes and 2,846 lines. Detailed review
+  evidence also lives under initiative `reviews/` directories.
+
+## Relevant files and modules
+
+| Area | Existing surfaces | Gap |
+|---|---|---|
+| Contract enforcement | `.agent-loop/templates/CHUNK_CONTRACT.md`, `scripts/check_internal_review_evidence.py`, `scripts/test_agent_gates.py` | No universal typed path delta enforcement. |
+| Signed memory | `scripts/update_post_merge_memory.py`, `scripts/check_loop_memory_state.py`, `.github/workflows/loop-memory*.yml` | No independent read-only schedule. |
+| Reviewer routing | `.agent-loop/policies/routing-policy.md`, `.codex/agents/*.toml`, `.agents/skills/risk-router/` | Adversarial attempts are implicit rather than stable evidence. |
+| Property tests | Loop-memory tests and authorization tests | Extensive adversarial examples, no generated invariant exploration. |
+| Mutation testing | Backend coverage workflow and coverage policy | Coverage measures execution, not fault sensitivity. |
+| Review memory | Root `REVIEW_LOG.md`, initiative review directories | Root narrative grows linearly and duplicates detail. |
+
+## Concurrent initiative reconciliation
+
+| Initiative | Signed state at discovery | Concurrent repository state | ENG-008 rule |
+|---|---|---|---|
+| `WS-ART-001` | `WS-ART-001-03` active | Dedicated clean worktree; no PR yet | Do not touch ART application or artifact-custody surfaces. Reconcile before every ENG-008 PR. |
+| `WS-AUTH-001` | `WS-AUTH-001-10C` active | PR #194 open; local repairs differ from its published head and Backend CI is failing | AUTH property chunk waits for AUTH to merge or stop, then rebases on its canonical result. |
+| `WS-REV-001` | `WS-REV-001-03P` active | PR #195 open and green at discovery | Avoid project/review runtime files and reconcile its merge before later test work. |
+| `WS-CON-001` | stopped at `02A`, next `02B` | Worktree has an unexplained local PDF deletion | No adoption or modification; deletion remains outside ENG-008. |
+| `WS-QUAL-001` | absent from signed state | Two stale local worktrees; no current authority | Treat all QUALITY commits as discovery input only; mutation work starts from current main under ENG-008. |
+| External PRs #62, #138, #149 | no active signed initiative authority | stale, conflicting, or missing current gates | Never merge as ENG-008 authority; inspect only as preserved proposals when relevant. |
+
+### Final current-main reconciliation
+
+| Initiative | Signed state at final reconciliation | ENG-008 boundary |
+|---|---|---|
+| `WS-ART-001` | stopped after `WS-ART-001-PLAN2`; next `WS-ART-001-03A` requires explicit start | No ART authority is borrowed. |
+| `WS-AUTH-001` | stopped after `WS-AUTH-001-11`; next `WS-AUTH-001-11A` requires explicit start | Chunk 05 must start from the then-current canonical AUTH result. |
+| `WS-REV-001` | `WS-REV-001-03P` remains signed-active | Avoid REV runtime and reconcile its result before overlapping work. |
+| `WS-CON-001` | stopped after `WS-CON-001-02A`; next `02B` requires explicit start | Local worktree state remains non-authoritative. |
+| `WS-QUAL-001` | absent from signed state | Dormant patches remain discovery input only. |
+| `WS-ENG-008` | absent from signed history | This additive planning intake may create only stopped PLAN state. |
+
+Current Backend CI uses four exact-custody semantic lanes with one combined
+coverage result. The earlier four-shard topology remains historical discovery
+context only and is not a protected future contract boundary.
+
+## Existing tests and gaps
+
+- Agent Gate tests strongly cover merge intent, evidence, workflow pinning,
+  coverage floors, signed state, and planning intake.
+- Loop-memory tests already contain mutation matrices and replay/collision
+  cases, but generated state-space invariants are not property-tested.
+- Authorization tests cover deny-default and action ownership through examples;
+  generated unknown/cross-resource/lifecycle combinations are not centralized.
+- No test currently proves that every ordinary PR path is permitted by the
+  signed contract's machine-readable scope.
+- No scheduled proof detects later automation-branch tampering between events.
+- Coverage evidence cannot show whether assertions kill plausible behavioral
+  faults.
+
+## Dependencies and integrations
+
+- PyYAML is pinned for Agent Gates, but JSON is preferable for the first scope
+  schema because it avoids YAML coercion and duplicate-key ambiguity.
+- Hypothesis would be a new test dependency in Agent Gates and later Backend.
+- A mutation engine would be a new development/CI dependency and needs a hashed
+  or otherwise reproducible installation path.
+- GitHub Actions scheduling runs workflow code from the default branch; the
+  drift job must use read-only `contents` and `actions` permissions.
+
+## Risks discovered
+
+| Risk | Impact | Required treatment |
+|---|---|---|
+| Glob semantics differ across platforms | Scope bypass or false rejection | Define one closed repository-relative grammar and test traversal, symlink, rename, and case behavior. |
+| Legacy contracts lack schemas | Immediate repository-wide failure | Exact cutover: every post-cutover start requires schema; only work already signed-active at cutover may finish under its exact pre-cutover event and contract blob. |
+| Git permits control and normalization-colliding path bytes | Line/display parsing can conceal a delta | Parse NUL-delimited bytes, reject invalid UTF-8/control/non-NFC names and normalization/casefold collisions. |
+| Scheduled audit becomes a repair path | Unreviewed signed-state mutation | Read-only permissions, no signing key, no publication command, regression-test workflow semantics. |
+| Property suites are nondeterministic | Flaky required CI | Fixed profiles, stored counterexample text in evidence, bounded examples/deadlines, rerunnable seeds. |
+| Mutation score is gamed | False assurance | Report eligible/killed/survived/timeout/excluded counts and classify survivors; do not use “kill one mutant.” |
+| Review archive breaks references | Loss of durable evidence | Lossless byte-preserving archive, link map, root index, and stale-link tests. |
+| Active PR advances main | Stale proof or merge conflict | Rebase/reconcile and rerun exact proof before each PR; signed contracts remain immutable. |
+
+## Unknowns requiring later measured evidence
+
+- Eligible module and runtime budget for the mutation pilot.
+- Stable Hypothesis example/deadline profile under hosted runners.
+- Archive period boundaries that produce useful index sizes without churn.
+- Whether scheduled drift should alert through GitHub only or a later external
+  operations channel; this initiative adds no external notification secret.
+
+## Existing conventions to preserve
+
+- One signed active chunk per initiative; distinct initiatives may run concurrently.
+- One PR and one schema-v2 merge intent per chunk.
+- Exact-current-main signed starts and human-owned specific-PR merge approval.
+- Internal reviewer completion before publication; external checks supplement it.
+- Automated Merge Memory owns the generated branch and never starts successors.

.agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/INTENT.md

@@ -0,0 +1,108 @@
+# Intent: WS-ENG-008 — Repository-Native SDLC Assurance
+
+## Problem being solved
+
+Workstream's repository-native human-agent engineering loop now binds intent,
+signed starts, evidence, review, merge decisions, and generated memory. Its
+remaining assurance gaps are that most chunk scope is still interpreted from
+prose, signed-state integrity is checked only on merge/start rather than on an
+independent schedule, adversarial proof is implicit across reviewer tracks,
+invariant tests are predominantly example-based, mutation quality is not
+measured, and the root review log has grown to about 147 KB.
+
+## Why this work matters
+
+The loop is trustworthy only if authorization, scope, proof quality, and durable
+memory remain independently verifiable as the repository and contributor count
+grow. These controls must become stronger without slowing every change with
+unbounded tests or creating a second authority path.
+
+## Current behavior
+
+- Signed starts and generated merge memory are canonical and initiative-local.
+- Agent Gates bind merge intent and internal-review evidence to reviewed code.
+- Chunk contracts state allowed files and non-goals in Markdown, but there is no
+  universal machine-enforced path contract for ordinary implementation PRs.
+- No scheduled workflow independently audits the signed automation branch.
+- Nine internal reviewer tracks exist; adversarial attempts are not represented
+  by a stable proof schema.
+- Neither Hypothesis nor a mutation-testing engine is installed.
+- Detailed initiative reviews coexist with a 147,017-byte root `REVIEW_LOG.md`.
+
+## Target behavior
+
+- Every implementation/specification start after the `WS-ENG-008-01` cutover
+  selects a strict versioned scope contract. Grandfathering is limited to work
+  already signed-active at cutover and bound to its pre-cutover event and
+  immutable contract blob.
+- A read-only schedule verifies signed-state custody, ancestry, ledger,
+  projections, active contracts, and closed-tree integrity without repairing.
+- High-risk work records attacks attempted, observed denials, findings, and
+  untested surfaces through risk routing.
+- Bounded property tests exercise loop-memory and authorization invariants with
+  deterministic replay evidence.
+- A changed-module mutation pilot measures meaningful survivors before any
+  carefully calibrated blocking policy is proposed.
+- Root review memory becomes a compact index with lossless archives and
+  initiative-owned detailed evidence.
+
+## Design chosen
+
+Deliver one assurance mechanism per reviewed chunk. Ratchet new enforcement
+forward without retroactively rewriting hundreds of historical contracts.
+Reuse the current signed-state verifier, internal evidence gate, risk router,
+reviewer files, Backend aggregation, and initiative review directories.
+
+## Alternatives considered
+
+- A global mutation gate immediately was rejected because runtime, exclusions,
+  and baseline quality are not yet measured.
+- A universal tenth reviewer was rejected because it would duplicate existing
+  security, QA, architecture, and test-delta tracks; adversarial proof will be
+  risk-routed instead.
+- One scheduled job covering all runtime architecture was rejected because
+  signed-memory custody and subsystem runtime reachability have different
+  owners and failure semantics.
+- Truncating `REVIEW_LOG.md` was rejected because review history must remain
+  lossless and linkable.
+
+## Boundaries preserved
+
+- Existing signed starts, start authority, cancellation approval, human merge
+  ownership, merge intent, coverage floors, and automated merge memory remain.
+- ART, AUTH, and REV keep their current initiative-local signed authority.
+- Existing patches and dormant QUALITY work are discovery input only.
+- Scheduled verification is read-only and receives no signing secret or write
+  permission.
+- Property and mutation testing do not change product behavior.
+
+## Expected risks
+
+- A scope schema could reject valid changes or permit path-pattern ambiguity.
+- Scheduled auditing could produce noisy failures or accidentally gain write
+  authority.
+- Property and mutation suites could destabilize or lengthen CI.
+- Adversarial review could become duplicative checkbox evidence.
+- Review-log migration could break historical links or collide with active PRs.
+
+## What must not change
+
+- No bypass for humans, agents, forks, administrators, existing patches, drafts,
+  or emergency work.
+- No automatic start, merge, state repair, or review approval.
+- No weakening of the 78 percent global or protected 90 percent coverage floors.
+- No application behavior, product authorization, payment, or artifact-custody
+  change may be hidden inside this engineering initiative.
+
+## How this will be proven
+
+Each chunk has adversarial fixtures, exact allowed paths, required reviewers,
+bounded runtime expectations, and a null or same-initiative successor. Hosted
+CI remains authoritative. Concurrent active initiatives are reconciled against
+exact current `main` before implementation, review, publication, and merge.
+
+## Human decisions required
+
+- Approve each implementation chunk's exact scope and PR independently.
+- Decide after the mutation pilot whether any score becomes blocking.
+- Approve the lossless review-log archive layout before migration.