From 2f297f50ea9067e9a32023f28891f872488f58bb Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Mon, 3 Aug 2026 17:34:43 +0100 Subject: [PATCH 1/2] docs: reconcile current v0.1 repository state --- .../CHUNK_MAP.md | 8 +- .../STATUS.md | 12 ++- ...OCS-001-02-current-state-reconciliation.md | 83 +++++++++++++++++++ .../WS-DOCS-001-02-review-and-trust-bundle.md | 59 +++++++++++++ docs/current_system_data_flow.html | 6 +- docs/historical_planning.md | 18 ++++ docs/roadmap_status.md | 9 +- 7 files changed, 183 insertions(+), 12 deletions(-) create mode 100644 .agent-loop/initiatives/WS-DOCS-001-current-v01-documentation/chunks/WS-DOCS-001-02-current-state-reconciliation.md create mode 100644 .agent-loop/initiatives/WS-DOCS-001-current-v01-documentation/reviews/WS-DOCS-001-02-review-and-trust-bundle.md diff --git a/.agent-loop/initiatives/WS-DOCS-001-current-v01-documentation/CHUNK_MAP.md b/.agent-loop/initiatives/WS-DOCS-001-current-v01-documentation/CHUNK_MAP.md index e38dedebe..c7e2e276a 100644 --- a/.agent-loop/initiatives/WS-DOCS-001-current-v01-documentation/CHUNK_MAP.md +++ b/.agent-loop/initiatives/WS-DOCS-001-current-v01-documentation/CHUNK_MAP.md @@ -2,7 +2,9 @@ | Chunk | Purpose | State | | --- | --- | --- | -| `WS-DOCS-001-01` | Modernize the current v0.1 documentation entry path and archive expired calendar framing | In progress | +| `WS-DOCS-001-01` | Modernize the current v0.1 documentation entry path and archive expired calendar framing | Merged through PR #246 | +| `WS-DOCS-001-02` | Reconcile remaining current-facing timeline wording, historical classification, and documentation initiative state | In progress | -This initiative intentionally uses one documentation-only chunk. Splitting the -entry pages would allow contradictory wording to remain between merges. +Both chunks are documentation-only. The second chunk preserves historical +records verbatim where their old wording is itself evidence; it changes only +current-facing claims, classification, and navigation. diff --git a/.agent-loop/initiatives/WS-DOCS-001-current-v01-documentation/STATUS.md b/.agent-loop/initiatives/WS-DOCS-001-current-v01-documentation/STATUS.md index 093594c28..8f858ee2c 100644 --- a/.agent-loop/initiatives/WS-DOCS-001-current-v01-documentation/STATUS.md +++ b/.agent-loop/initiatives/WS-DOCS-001-current-v01-documentation/STATUS.md @@ -1,7 +1,11 @@ # Status -`WS-DOCS-001-01` is locally complete and ready for pull-request review. +`WS-DOCS-001-01` is merged. It replaced calendar-driven entry guidance with a +capability-based v0.1 README, contribution path, agent guidance, current-status +ledger, and historical-planning index. -The entry-path rewrite is complete locally. Deterministic documentation checks -pass, and all valid internal review findings have been resolved. Merge remains -a human decision after GitHub checks and external review. +`WS-DOCS-001-02` is the bounded current-state reconciliation. It removes the +remaining calendar language from current-facing material, classifies preserved +early planning and review documents as history, and refreshes this initiative's +own merged state. It changes no product behavior, architecture contract, +workflow, CI policy, or implementation initiative. diff --git a/.agent-loop/initiatives/WS-DOCS-001-current-v01-documentation/chunks/WS-DOCS-001-02-current-state-reconciliation.md b/.agent-loop/initiatives/WS-DOCS-001-current-v01-documentation/chunks/WS-DOCS-001-02-current-state-reconciliation.md new file mode 100644 index 000000000..bcedcf0d7 --- /dev/null +++ b/.agent-loop/initiatives/WS-DOCS-001-current-v01-documentation/chunks/WS-DOCS-001-02-current-state-reconciliation.md @@ -0,0 +1,83 @@ +# WS-DOCS-001-02: Current-State Documentation Reconciliation + +## Problem being solved + +The primary v0.1 entry path is current, but a small number of current-facing +documents still use expired calendar language and the documentation +initiative's own status still describes its merged first chunk as local work. +Some preserved early reviews also lack one index that clearly classifies them +as historical evidence. + +## Why this work matters + +Contributors and agents need one unambiguous current entry path. Historical +evidence must remain available without being mistaken for current priority, +implementation state, or contribution authority. + +## Current behavior + +- `README.md`, `CONTRIBUTING.md`, `AGENTS.md`, and `docs/roadmap_status.md` use + the current capability-based v0.1 framing. +- One current architecture diagram still refers to a numbered delivery week. +- Early plans are indexed as historical, but early strategy/review records are + not all reachable from that classification page. +- `WS-DOCS-001-01` is merged but its initiative status says it is locally + complete and awaiting PR review. + +## Target behavior + +- Current-facing documentation contains no delivery-week or rolling-calendar + authority. +- Preserved calendar plans, early specifications, and review records are + explicitly discoverable as history. +- The current capability ledger reflects merged REV/AUTH readiness without + claiming the unimplemented review lifecycle is live. +- The DOCS initiative accurately records its merged and current chunks. + +## Design chosen + +Correct only current-facing prose and indexes. Preserve historical documents +and their original statements instead of rewriting the evidence they contain. + +## Allowed files + +- `docs/current_system_data_flow.html` +- `docs/historical_planning.md` +- `docs/roadmap_status.md` +- `.agent-loop/initiatives/WS-DOCS-001-current-v01-documentation/**` + +## Not allowed changes + +- Backend, frontend, migration, test, CI, or workflow behavior. +- AUTH, ART, REV, CON, QUAL, or XINT implementation records. +- Historical document bodies whose old terminology is part of the record. +- Open pull requests #149, #138, #62, or #249. + +## Acceptance criteria + +1. Current-facing documentation no longer describes v0.1 through numbered + delivery weeks or a 30-day schedule. +2. Historical plans and early review records are clearly classified and linked. +3. The current status ledger distinguishes merged readiness from unimplemented + review/revision behavior. +4. The DOCS initiative no longer reports its merged first chunk as in progress. +5. Stale-wording, Markdown-link, and lightweight documentation gates pass. + +## Risk class and reviewers + +Risk: L2 documentation-only. Required review: docs, senior engineering, QA, +and product/operations. Security review is unnecessary because authority and +runtime security behavior do not change. + +## How this will be proven + +- Repository stale-wording scan. +- Repository Markdown-link check. +- Targeted search for calendar language outside classified historical paths. +- Lightweight Agent Gates tests. +- Internal reviewer results recorded before PR readiness. + +## Human review focus + +Confirm that the capability ledger is accurate, that historical evidence was +preserved, and that no active implementation initiative was re-prioritized. diff --git a/.agent-loop/initiatives/WS-DOCS-001-current-v01-documentation/reviews/WS-DOCS-001-02-review-and-trust-bundle.md b/.agent-loop/initiatives/WS-DOCS-001-current-v01-documentation/reviews/WS-DOCS-001-02-review-and-trust-bundle.md new file mode 100644 index 000000000..d2947a5b4 --- /dev/null +++ b/.agent-loop/initiatives/WS-DOCS-001-current-v01-documentation/reviews/WS-DOCS-001-02-review-and-trust-bundle.md @@ -0,0 +1,59 @@ +# WS-DOCS-001-02 Review And PR Trust Bundle + +## Intent and scope + +Reconcile the remaining current-facing calendar wording, classify preserved +early planning and review material as history, refresh the v0.1 capability +ledger after merged REV/AUTH readiness, and correct the DOCS initiative's own +status. No product code, workflow, CI policy, architecture contract, or other +initiative implementation changes. + +## Files and design + +- `docs/current_system_data_flow.html` describes the current checker outcome + without implying that the unimplemented review queue is live. +- `docs/historical_planning.md` indexes every top-level early `review*.md` + record and preserves those records without rewriting their historical text. +- `docs/roadmap_status.md` records merged REV/AUTH readiness while explicitly + keeping review lifecycle behavior unavailable and under integration. +- The WS-DOCS-001 status, chunk map, and chunk contract record the bounded + reconciliation and the merged disposition of chunk 01. + +## Deterministic evidence + +Passed on the final repaired working tree: + +- `python3 scripts/check_stale_workstream_wording.py` +- `python3 scripts/check_stale_authorization_docs.py` +- `python3 scripts/check_stale_artifact_contracts.py` +- `python3 scripts/check_stale_review_contracts.py` +- `python3 scripts/check_markdown_links.py` +- `PYTHONPATH=. python3 scripts/test_lightweight_agent_gates.py` +- `git diff --check` + +No local `sheets/workstream_roadmap.xlsx` exists in this worktree, so workbook +sheet-count and export-parity checks are not applicable. The roadmap export was +not changed. + +## Internal review + +- Docs: initial FAIL because the historical index covered only four early + reviews; repaired by linking every top-level `docs/review*.md`; final PASS. +- Product/operations: initial FAIL because the data-flow page implied a live + review queue; repaired with exact current checker outcomes and an explicit + availability boundary; final PASS. +- QA: initial staging/evidence finding; the complete bounded diff and contract + were staged and the deterministic checks completed; final PASS. +- Senior engineering: PASS, with the availability wording observation resolved + by the product/operations repair. + +## Risks and human review focus + +Historical bodies deliberately retain their original calendar language because +rewriting audit evidence would erase context. Review that every such document +is reached through the historical index and that the capability ledger does +not overstate live REV behavior. + +## External checks and merge + +GitHub CI, external review, and explicit human merge approval remain required. diff --git a/docs/current_system_data_flow.html b/docs/current_system_data_flow.html index 31aebca69..cd01a5845 100644 --- a/docs/current_system_data_flow.html +++ b/docs/current_system_data_flow.html @@ -557,8 +557,8 @@

Automatic checkers execute

10 -

Current system routes result

-

The checker gate sends passing work to review queue, contributor-fixable failures to revision, and setup defects to internal repair.

+

Current checker outcome

+

The checker gate marks passing work review_pending, contributor-fixable failures needs_revision, and setup defects task_setup_blocked. A live review queue is not implied.

review_pending needs_revision @@ -573,7 +573,7 @@

Current End Of The Flow

review_pending -

All blocking post-submit checker policy requirements pass. The task is ready for the Week 3 human review engine.

+

All blocking post-submit checker policy requirements pass. The task reaches the review-pending boundary; the authorized human-review lifecycle consumes it when that lifecycle is available.

needs_revision diff --git a/docs/historical_planning.md b/docs/historical_planning.md index 458c05055..9acddfacb 100644 --- a/docs/historical_planning.md +++ b/docs/historical_planning.md @@ -27,5 +27,23 @@ and tests on `main`, accepted ADRs, and the canonical subsystem specifications. - [Checker Trial](spec_chunk_10_checker_trial.md) - [Checker Trial Failure Catalog](checker_trial_failure_catalog.md) +## Early Strategy And Review Records + +These documents preserve design criticism, closure decisions, and adversarial +review from the original calendar-planning period. Their recommendations are +historical input, not current delivery commitments or implementation status. + +- [Initial Review Closure](review_closure.md) +- [Architecture Review](review_architecture_review.md) +- [Systems Architecture Review](review_systems_architecture_review.md) +- [Final Architecture Review](review_final_architecture_review.md) +- [Operations Review](review_operations_review.md) +- [Product Strategy Review](review_product_strategy_review.md) +- [Final Product Strategy Review](review_final_product_strategy_review.md) +- [Adversarial Quality Review](review_adversarial_quality_review.md) +- [Final Adversarial Review](review_final_adversarial_review.md) +- [Process Baseline Operations Review](review_process_baseline_operations_review.md) +- [Process Pattern Baseline Review](review_process_pattern_baseline_review.md) + Later canonical specifications and initiative records supersede these files where they describe the same behavior. diff --git a/docs/roadmap_status.md b/docs/roadmap_status.md index 523590c32..a11a2f494 100644 --- a/docs/roadmap_status.md +++ b/docs/roadmap_status.md @@ -57,6 +57,10 @@ remain outside v0.1. and PostgreSQL-backed rate controls. - Project setup plus project create, guide mutation, binding, and read authorization foundations. +- Immutable review/revision policy identities, AUTH-owned policy mutation, + complete planned REV action and fixed-service catalogues, and the typed + fail-closed PREP/read handoff required for hidden REV implementation. These + readiness contracts do not make the review lifecycle available. ### Project, task, submission, and checker foundations @@ -85,8 +89,9 @@ remain outside v0.1. The following areas have merged planning, contracts, or partial foundations, but are not all complete as one production path: -- review-policy persistence and activation across REV and AUTH; -- review queue, reviewer assignment/claim, immutable decisions, and revision +- integration of the merged review/revision policy and authorization readiness + contracts into hidden REV lifecycle behavior; +- hidden review queue, reviewer assignment/claim, immutable decisions, and revision replay on the canonical authorization boundary; - atomic review-to-contribution and conditional compensation integration. From 2f94ca77d729916155798295220a3f9a1e9858f4 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Mon, 3 Aug 2026 18:13:48 +0100 Subject: [PATCH 2/2] docs: address current-state review findings --- ...WS-DOCS-001-02-external-review-response.md | 36 +++++++++++++++++++ .../WS-DOCS-001-02-review-and-trust-bundle.md | 5 ++- docs/current_system_data_flow.html | 4 +-- docs/roadmap_status.md | 3 +- 4 files changed, 44 insertions(+), 4 deletions(-) create mode 100644 .agent-loop/initiatives/WS-DOCS-001-current-v01-documentation/reviews/WS-DOCS-001-02-external-review-response.md diff --git a/.agent-loop/initiatives/WS-DOCS-001-current-v01-documentation/reviews/WS-DOCS-001-02-external-review-response.md b/.agent-loop/initiatives/WS-DOCS-001-current-v01-documentation/reviews/WS-DOCS-001-02-external-review-response.md new file mode 100644 index 000000000..92ff61540 --- /dev/null +++ b/.agent-loop/initiatives/WS-DOCS-001-current-v01-documentation/reviews/WS-DOCS-001-02-external-review-response.md @@ -0,0 +1,36 @@ +# WS-DOCS-001-02 External Review Response + +## Comments addressed + +1. CodeRabbit correctly identified that the data-flow page conflated the + checker outcome `allow_review` with the later task lifecycle state + `review_pending`. The page now names both layers and keeps + `task_setup_blocked` as a routing recommendation rather than a checker + outcome. +2. CodeRabbit correctly requested durable evidence for the merged REV/AUTH + readiness claims. The capability ledger now binds policy identity, policy + mutation activation, catalogue/fixed-service readiness, and the PREP/read + handoff to merged PRs #242, #248, #255, and #257 respectively. + +## Comments deferred + +None. + +## Human decisions needed + +None beyond normal review and explicit merge approval for PR #259. + +## Commands rerun + +- `python3 scripts/check_stale_workstream_wording.py` +- `python3 scripts/check_stale_authorization_docs.py` +- `python3 scripts/check_stale_artifact_contracts.py` +- `python3 scripts/check_stale_review_contracts.py` +- `python3 scripts/check_markdown_links.py` +- `PYTHONPATH=. python3 scripts/test_lightweight_agent_gates.py` +- `git diff --check` + +## Remaining risks + +The named readiness PRs do not make the REV lifecycle available. Both the +capability ledger and data-flow page retain that availability boundary. diff --git a/.agent-loop/initiatives/WS-DOCS-001-current-v01-documentation/reviews/WS-DOCS-001-02-review-and-trust-bundle.md b/.agent-loop/initiatives/WS-DOCS-001-current-v01-documentation/reviews/WS-DOCS-001-02-review-and-trust-bundle.md index d2947a5b4..9c468f186 100644 --- a/.agent-loop/initiatives/WS-DOCS-001-current-v01-documentation/reviews/WS-DOCS-001-02-review-and-trust-bundle.md +++ b/.agent-loop/initiatives/WS-DOCS-001-current-v01-documentation/reviews/WS-DOCS-001-02-review-and-trust-bundle.md @@ -56,4 +56,7 @@ not overstate live REV behavior. ## External checks and merge -GitHub CI, external review, and explicit human merge approval remain required. +CodeRabbit's two valid findings were repaired: the checker outcome is now +separate from the task lifecycle state, and the merged REV/AUTH readiness claim +names PRs #242, #248, #255, and #257 as evidence. GitHub CI must pass again on +the repaired exact head. Explicit human merge approval remains required. diff --git a/docs/current_system_data_flow.html b/docs/current_system_data_flow.html index cd01a5845..385081762 100644 --- a/docs/current_system_data_flow.html +++ b/docs/current_system_data_flow.html @@ -557,8 +557,8 @@

Automatic checkers execute

10 -

Current checker outcome

-

The checker gate marks passing work review_pending, contributor-fixable failures needs_revision, and setup defects task_setup_blocked. A live review queue is not implied.

+

Checker routing and lifecycle boundary

+

The checker reports allow_review for passing work; this can move the task toward review_pending. It reports needs_revision for contributor-fixable failures and recommends task_setup_blocked for locked setup defects. A live review queue is not implied.

review_pending needs_revision diff --git a/docs/roadmap_status.md b/docs/roadmap_status.md index a11a2f494..bcb5e6093 100644 --- a/docs/roadmap_status.md +++ b/docs/roadmap_status.md @@ -60,7 +60,8 @@ remain outside v0.1. - Immutable review/revision policy identities, AUTH-owned policy mutation, complete planned REV action and fixed-service catalogues, and the typed fail-closed PREP/read handoff required for hidden REV implementation. These - readiness contracts do not make the review lifecycle available. + foundations merged through PRs #242, #248, #255, and #257 respectively. + These readiness contracts do not make the review lifecycle available. ### Project, task, submission, and checker foundations