Repository navigation
docs: hygiene pass after ADR-0041 (PR 1 of REORG-PLAN) - #488
Conversation
- Fix broken links in deploy/knative/README-authbridge.md; keep the out-of-repo docs/research references as plain text with a registry note. - Register the 11 previously unregistered specs in docs/specs/README.md. - Mark P6 and P6.1 implemented in the registry; accept ADR-0034 and ADR-0037 (file Status lines and index). - Add historical/deprecated banners to executive-overview, experiment-results and packages/k8s-sandbox README/SMOKE. - Fix demos README wording and deploy/vm/README.md opening line. - Add docs/REORG-PLAN.md (documentation reorganization plan). Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Paolo Dettori <dettori@us.ibm.com>
ingpaolodettori-dev
left a comment
ingpaolodettori-dev
left a comment
There was a problem hiding this comment.
Summary
Docs-only hygiene pass (PR 1 of the new docs/REORG-PLAN.md). I checked the link fixes, the status flips and the new registry table against the tree at ee68e35. Every new link target exists. Every spec in docs/specs/ now appears in the registry. The statuses in the new "Other specs" table match the spec headers, and ADR edits are limited to the Status line, as the ADR README's immutability rule allows. Nothing blocks merging. The comments below are about the plan document itself: it still contains notes from the drafting session, and it goes partly stale as soon as this PR lands.
Author: pdettori (MEMBER — maintainer)
Areas reviewed: Docs (25 Markdown files)
Agent/IDE config (.claude/.vscode): none
Commits: 1 commit, all signed-off: yes
CI status: passing (all 14 checks green)
| @@ -0,0 +1,484 @@ | |||
| # MOCA documentation reorganization plan | |||
|
|
|||
| > Deliverable: copy this file verbatim to `docs/REORG-PLAN.md` (the only repo file to create). No existing doc is moved, renamed, rewritten or deleted by this task. | |||
There was a problem hiding this comment.
suggestion: Some notes from the drafting session ended up in the committed file. This line ("Deliverable: copy this file verbatim to docs/REORG-PLAN.md (the only repo file to create)…"), line 5 ("the local checkout is on branch spike/sandbox-mcp…") and the whole ## Verification of this task (before copying to docs/REORG-PLAN.md) section at line 479 are instructions for whoever wrote the file, not for readers. Line 479 even refers to copying the file and to unrelated uncommitted changes. Please drop them, or reword lines 3–5 as a short provenance note ("audited against main b009079 on 2026-10-12").
|
|
||
| ## 4. Current-state audit | ||
|
|
||
| ### 4.0 Status of findings after #485/#486 (upstream/main b009079) |
There was a problem hiding this comment.
suggestion: Several items this plan lists as OPEN are fixed by this same PR, so the plan is out of date as soon as it merges. Affected places: §1 "Top remaining problems", the §3.1 table (P6/P6.1 "design (proposed)", ADR-0034/0037 "Proposed"), §3.4 "Contradiction to resolve", and these §4.0 rows: Registry rows, ADR statuses, Broken links, Stale docs, deploy/vm/README.md opening, Demos. The plan already marks what #485/#486 fixed. Could you do the same here, e.g. a note or column saying "FIXED in PR 1 (#488)"? Otherwise someone working on PR 2+ may redo this work.
|
|
||
| | PR | Content | Acceptance criteria | Risks | | ||
| | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | ||
| | 1 | **Docs hygiene, no moves.** Fix the 24 broken links (decide `docs/research/`, Q9; `README-authbridge.md:12`; `SECURITY.md:12`; ADR template); register the 11 specs; fix P6/P6.1 registry rows and the ADR-0034/0037/0040 statuses per Q1/Q7, align the two status vocabularies; banner `executive-overview`, `experiment-results`, `packages/k8s-sandbox/{README,SMOKE}.md`, `deploy/knative/sandbox-inventory/README.md`; fix `docs/demos/README.md` count and `deploy/vm/README.md` opening line; remove stale README items (5.4 items 4-5) | link check script reports 0 broken; every spec in `docs/specs/*.md` appears in the registry; no ADR body rewritten except Status lines (ADR immutability rule) | Editing ADR status lines vs ADR-0041 Revisions precedent: follow the precedent, record in Revisions | |
There was a problem hiding this comment.
nit: The PR 1 row lists some items this PR doesn't do: a banner on deploy/knative/sandbox-inventory/README.md (still unbannered at ee68e35), fixing the ADR-0040 status (the PR body keeps it Proposed on purpose), and the SECURITY.md:12 / ADR-template links. The acceptance criterion is also "link check reports 0 broken", while the PR body accepts 3 false positives. Either add the sandbox-inventory banner or update this row so it matches what shipped.
| runs the same way on Kind and OpenShift; only the enable/run entrypoints differ. | ||
|
|
||
| - Design: [`../specs/2026-07-10-authbridge-egress-control-plane-poc-design.md`](../specs/2026-07-10-authbridge-egress-control-plane-poc-design.md) · [ADR-0025](../adrs/0025-authbridge-deployment-topology.md) | ||
| - Design: [`../specs/2026-07-10-authbridge-egress-control-plane-poc-design.md`](../../docs/specs/2026-07-10-authbridge-egress-control-plane-poc-design.md) · [ADR-0025](../../docs/adrs/0025-authbridge-deployment-topology.md) |
There was a problem hiding this comment.
nit: The link target is fixed, but the visible text still says `../specs/2026-07-10-…`, which is the old broken path. Consider changing the text to `../../docs/specs/2026-07-10-authbridge-egress-control-plane-poc-design.md` (or just the file name) so the text and the target agree.
| | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------- | | ||
| | Multi-protocol model provider (Anthropic + OpenAI-compatible) | [`2026-08-20-multi-protocol-model-provider-design.md`](2026-08-20-multi-protocol-model-provider-design.md) | Accepted | | ||
| | Async prompt dispatch (`kind:"prompt"`) | [`2026-08-25-async-prompt-dispatch-design.md`](2026-08-25-async-prompt-dispatch-design.md) | Proposed | | ||
| | ST4 — Go reference worker | [`2026-08-26-st4-go-reference-worker-design.md`](2026-08-26-st4-go-reference-worker-design.md) | see spec header | |
There was a problem hiding this comment.
nit: "see spec header" sends the reader in a circle: neither 2026-08-26-st4-go-reference-worker-design.md (here) nor 2026-09-18-e11-go-exec-client-design.md (line 262) has a Status line in its header. Consider "not stated" or "—" for both rows.
- Replace drafting notes in docs/REORG-PLAN.md with a provenance line and drop the verification section. - Mark findings fixed by this PR as FIXED in section 4.0, 3.1 and 3.4, and reconcile the PR 1 row with what shipped. - Use 'not stated' for specs without a Status line. - Make the authbridge link text match its target. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Paolo Dettori <dettori@us.ibm.com>
ee68e35 to
9ebad81
Compare
Docs hygiene pass (PR 1 of docs/REORG-PLAN.md)
First step of the documentation reorganization plan added in this PR (
docs/REORG-PLAN.md). Docs only, no file moves, no code changes.Changes
deploy/knative/README-authbridge.md. The 20 links todocs/research/(a directory that lives outside this repo) are now plain text, with a note at the top ofdocs/specs/README.md.docs/specs/README.mdnow lists the 11 specs that were unregistered (statuses copied from each spec header); P6 and P6.1 are marked implemented.docs/adrs/README.md). ADR-0035 and ADR-0040 stay Proposed.docs/executive-overview-leaf-session.mdanddocs/experiment-results.md; ADR-0041 deprecation banner onpackages/k8s-sandbox/README.mdandSMOKE.md.docs/demos/README.mdno longer says "the two above";deploy/vm/README.mdno longer callssetup-vm.sha sibling of the deprecated Knative scripts.docs/REORG-PLAN.md, the full audit, research and phased rollout.Not in this PR
Maturity labels in the README, README slimming, the migration-guide additions (env mapping, cron/async guidance, rollback), docs tooling and the new docs tree. These are PRs 2-7 in the plan. The link checker still flags 3 non-research items that are false positives (README badge URL, GitHub-relative link in
SECURITY.md, ADR template placeholder).Verification
.mdfiles: 0 broken relative links apart from the 3 false positives above.make lintnot run in this worktree (nonode_modules).Assisted-By: Claude (Anthropic AI) noreply@anthropic.com