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

[Abiorh001]

PR Trust Bundle

Chunk

WS-ENG-008-PLAN — Repository-Native SDLC Assurance Planning

Merge intent: .agent-loop/merge-intents/WS-ENG-008-PLAN.json

Goal

Establish a reviewed, planning-only initiative for machine-enforced contract
scope, scheduled signed-state auditing, adversarial proof, property testing,
mutation evidence, and lossless review-memory indexing.

Human-approved intent

• Intent: ../INTENT.md
• Plan: ../PLAN.md
• Chunk map: ../CHUNK_MAP.md

Signed Start Provenance

• Signed start run: N/A — first-new-initiative planning intake
• Authorized main SHA: bcf1292e1a591e3e84bf8ee212ee7191d80741fa
• Phase: planning intake; no active planning or implementation chunk
• Contract path: reviewed contracts ../chunks/WS-ENG-008-01-*.md through 07
• Signed contract blob SHA: N/A until post-merge explicit start selects chunk 01
• Reviewed planning SHA: 85bd98d6c55b066c9f1a44bc8aa83514911f4ea0

Only independently verified signed automation state is canonical authority.
Planning intake records stopped state and cannot authorize implementation.

What changed

• Added the seven canonical initiative root planning files.
• Added seven sequential L1 implementation contracts.
• Added one schema-v2 PLAN merge intent naming only chunk 01.
• Added the exact required internal review evidence and this trust bundle.

Why it changed

Workstream's loop is healthy, but ordinary scope remains prose-reviewed, signed
state lacks independent scheduled drift detection, and deeper proof mechanisms
need bounded repository-native ownership.

Design chosen

One assurance mechanism per PR, ordered by dependency. Contract enforcement
comes first and must upgrade all later ENG-008 contracts. Scheduled audit is
read-only. Adversarial proof uses existing reviewers. Property and mutation
testing are bounded and reproducible. Review memory is archived losslessly last.

Alternatives rejected

• Immediate global mutation threshold: no calibrated evidence.
• Universal tenth reviewer: duplicates current track ownership.
• Scheduled repair: creates a second state writer.
• Destructive review-log truncation: loses durable evidence.
• Reusing dormant work as authority: violates signed start custody.

Scope control

The PR adds only one new initiative directory and one PLAN merge intent. It
changes no existing file, workflow, application, test, dependency, permission,
coverage threshold, generated state, or product behavior.

Product Behavior

• No Workstream product behavior changed.

Acceptance criteria proof

• Complete intent, discovery, plan, chunk map, status, risks, and decisions.
• Seven bounded contracts with allowed files, prohibitions, measurable proof,
  all required reviewers, human focus, and stop conditions.
• ART/AUTH/REV concurrent state and CON/QUALITY dormant state reconciled.
• Objective scope cutover and successor conversion close self-exemption.
• One merge intent names same-initiative chunk 01 with explicit start true.
• Status claims no active planning or implementation chunk.

Tests/checks run

python3 scripts/update_post_merge_memory.py validate-merge-intent --repository-root . --base-ref origin/main
python3 scripts/test_agent_gates.py
python3 scripts/check_markdown_links.py
python3 scripts/check_stale_workstream_wording.py
git diff --check origin/main...HEAD

Result: all passed; 100 Agent Gate tests and 14 planning Markdown link checks.

Test delta

• No tests, workflows, coverage settings, or application files changed.
• The planning contracts specify future tests but implement none.

CI integrity

• Coverage thresholds unchanged
• Lint/typecheck/test commands unchanged
• No workflow or package-script weakening
• No dependency added
• No unpinned GitHub Action
• Planning intake remains additive and stopped

Reviewer results

Reviewed planning SHA: 85bd98d6c55b066c9f1a44bc8aa83514911f4ea0

Reviewer run IDs: eng008_plan_senior_arch_docs,
eng008_plan_qa_ci_tests, eng008_plan_security_ops_reuse

All nine tracks pass after two bounded repair cycles. See
WS-ENG-008-PLAN-internal-review-evidence.md.

External review

Source	Status	Notes
CodeRabbit	Pending	Review after publication; supplementary only.
GitHub checks	Pending	Exact final PR head must pass.

Remaining risks

• Concurrent active PRs may advance main and require rebase/re-review evidence.
• Implementation tool choices remain bounded decisions in their owning chunks.
• Human approval of this PR establishes planning only, never a signed start.

Follow-up work

After merge and successful Automated Merge Memory, stop. Chunk 01 begins only
after an explicit user instruction and successful signed start on exact main.

Human review focus

• Is contract enforcement first and does it govern contracts 02–07?
• Is scheduled verification structurally read-only?
• Are property/mutation budgets objective and non-weakening?
• Are concurrent initiatives preserved without borrowing their authority?

Human merge ownership

• I can explain what changed.
• I can explain why it changed.
• I know what could break.
• I accept the remaining risks.
• The user explicitly approved this specific PR for merge.

Summary by CodeRabbit

• Documentation
  • Added a comprehensive SDLC assurance initiative plan, including scope, decisions, risks, discovery findings, status, and execution sequencing.
  • Defined seven assurance workstreams covering change validation, drift auditing, adversarial proof, property testing, mutation testing, and lossless review-history indexing.
  • Added planning review evidence, trust documentation, and explicit approval, verification, and stop conditions.
• Governance
  • Established signed, sequential workstream starts with strict review and merge controls.
  • Documented read-only audit boundaries and preservation of existing product behavior and security controls.

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

Repository-native SDLC assurance

Layer / File(s)	Summary
Initiative foundation .agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/{INTENT,DISCOVERY,DECISIONS,RISKS,STATUS,CHUNK_MAP}.md	Adds the initiative intent, discovery record, governance decisions, risk register, planning status, and seven-chunk sequence.
Execution plan and planning evidence .agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/PLAN.md, .agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/reviews/*, .agent-loop/merge-intents/WS-ENG-008-PLAN.json	Defines sequencing, reconciliation, verification, rollout, review requirements, and planning merge metadata.
Scope, audit, and adversarial proof contracts .agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/chunks/WS-ENG-008-0{1,2,3}-*.md	Specifies machine-checkable path scope, read-only signed-state drift auditing, and risk-routed adversarial evidence.
Property and mutation testing contracts .agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/chunks/WS-ENG-008-0{4,5,6}-*.md	Defines bounded loop-memory and authorization property tests and a non-blocking changed-module mutation pilot.
Lossless review-memory contract .agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/chunks/WS-ENG-008-07-*.md	Defines byte-preserving review-history archiving, indexing, digest validation, and deterministic reconstruction.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested reviewers: abiorh-claw

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title is concise and accurately summarizes the planning-only repository-native SDLC assurance work.
Description check	✅ Passed	The description covers the required trust-bundle sections and most template fields, with only minor omissions like explicit allowed-files and review timestamp.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/ws-eng-008-plan-repository-native-assurance

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 9

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
@.agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/chunks/WS-ENG-008-01-machine-checkable-chunk-scope.md:
- Around line 36-54: Replace the recursive initiative glob in the Allowed files
contracts with explicit paths limited to each chunk’s own contract and its
approved evidence/status artifacts. Apply this consistently in
.agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/chunks/WS-ENG-008-01-machine-checkable-chunk-scope.md
lines 36-54, WS-ENG-008-02-scheduled-signed-state-drift-audit.md lines 35-46,
WS-ENG-008-03-risk-routed-adversarial-proof.md lines 35-53,
WS-ENG-008-04-loop-memory-property-invariants.md lines 35-46,
WS-ENG-008-05-authorization-property-invariants.md lines 35-45, and
WS-ENG-008-06-changed-module-mutation-pilot.md lines 35-47; exclude sibling
contracts, unrelated governance files, controls under test, and unrelated
evidence or gates from each allowlist.

In
@.agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/chunks/WS-ENG-008-07-lossless-review-memory-index.md:
- Around line 63-69: Add acceptance criteria requiring a durable pre-migration
reconciliation snapshot that records the current main commit, all open PR heads,
fetch timestamp, root-log digest, and reconciliation result. Specify a
verification command that validates this artifact and its relationship to the
migration, so losslessness and concurrent-writer checks remain auditable without
relying on Git history.
- Around line 35-50: Align the “Allowed files” list with the verification
commands in the WS-ENG-008-07 initiative: add scripts/check_markdown_links.py
and scripts/check_stale_workstream_wording.py, and update the verification flow
to execute scripts/check_stale_artifact_contracts.py for the stale-contract
criterion. Keep the paths exact and ensure every listed checker is invoked.
- Around line 70-77: Update the root REVIEW_LOG.md acceptance criteria and
checker requirements to define a deterministic size contract: specify the
maximum byte limit, UTF-8 encoding, and whether newline bytes are included in
the measurement. Ensure the checker enforces that exact byte limit for the root
index.
- Around line 31-33: Update the contract’s Start phase declaration so
implementation cannot begin before post-merge signed start and completion of
predecessor chunks 04–06. Either explicitly mark execution as blocked pending
those prerequisites or change the phase to a stopped/planning state, ensuring it
matches the stated PR objective.

In
@.agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/DISCOVERY.md:
- Around line 3-5: Update the discovery provenance entry to pin the exact signed
automation/loop-memory state used during discovery, alongside the existing main
commit SHA. Record either the full signed loop-memory tip SHA or its signed
ledger/event identifier so the plan and review evidence remain exactly
replayable.

In @.agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/PLAN.md:
- Around line 19-22: Update the dedicated scoped fenced JSON parser to reject
duplicate object keys during JSON decoding, before scope and exact-key
validation. Preserve the existing validation of canonical repository-relative
patterns, reviewer names, and verification commands, and ensure duplicate keys
fail closed rather than being silently collapsed by json.loads.

In
@.agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/reviews/WS-ENG-008-PLAN-internal-review-evidence.md:
- Around line 51-52: Reword the “canonical terminology reconciliation” bullet to
identify it as an assigned post-merge requirement rather than a completed
planning-PR change. Keep the additive-only scope and
initiative-tree/merge-intent evidence consistent, unless the evidence is updated
to list the actual README.md, docs/glossary.md, and
docs/architecture_lockdown.md changes.

In
@.agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/reviews/WS-ENG-008-PLAN-pr-trust-bundle.md:
- Around line 26-27: Update the contract path provenance field in
WS-ENG-008-PLAN-pr-trust-bundle.md to use a machine-resolvable reference for all
seven contracts, either by listing each exact WS-ENG-008-01 through 07 chunk
path explicitly or by using a precise range glob. Keep the signed contract blob
SHA entry unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: e69eb640-6879-4d72-88df-0292514d3946

📥 Commits

Reviewing files that changed from the base of the PR and between bcf1292 and 985bc87.

📒 Files selected for processing (17)

• .agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/CHUNK_MAP.md
• .agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/DECISIONS.md
• .agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/DISCOVERY.md
• .agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/INTENT.md
• .agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/PLAN.md
• .agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/RISKS.md
• .agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/STATUS.md
• .agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/chunks/WS-ENG-008-01-machine-checkable-chunk-scope.md
• .agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/chunks/WS-ENG-008-02-scheduled-signed-state-drift-audit.md
• .agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/chunks/WS-ENG-008-03-risk-routed-adversarial-proof.md
• .agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/chunks/WS-ENG-008-04-loop-memory-property-invariants.md
• .agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/chunks/WS-ENG-008-05-authorization-property-invariants.md
• .agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/chunks/WS-ENG-008-06-changed-module-mutation-pilot.md
• .agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/chunks/WS-ENG-008-07-lossless-review-memory-index.md
• .agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/reviews/WS-ENG-008-PLAN-internal-review-evidence.md
• .agent-loop/initiatives/WS-ENG-008-repository-native-sdlc-assurance/reviews/WS-ENG-008-PLAN-pr-trust-bundle.md
• .agent-loop/merge-intents/WS-ENG-008-PLAN.json