Skip to content

Remove five documents nothing reads #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vrv-panw merged 1 commit into from
Sep 15, 2026
Merged

Remove five documents nothing reads #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4,222 changes: 0 additions & 4,222 deletions PROSE-INVENTORY.csv
View file
Open in desktop

This file was deleted.

23 changes: 13 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,6 @@ plausible, wrong description is invisible and survives review.
| `webhooks/*.schema.json` | Both | The KB sync contract, in both directions | Both |
| `.spectral.yaml` | Both | Lint rules, including the grounding gate | — |
| `.spectral-baseline.json` | — | Inherited defect counts. May shrink, never grow | — |
| `PROSE-INVENTORY.csv` | — | Every stripped prose field: location, size, digest | Worklist |
| `build-report.txt` | — | Counts, and the gaps that want engineering | — |

The split is the point, and it is a split between *where prose is written* and
Expand All @@ -50,7 +49,8 @@ docs site, and it was not applying the overlay — so the published URL served
prose-free pages and nothing failed. It cost nothing while every description was
empty, and it would have cost the whole gate the day one was written.

The five files under `_project/` are the same idea applied to structure. Each
The four decision files under `_project/` are the same idea applied to
structure. Each
holds a decision that would otherwise be spread across the document — sixty-odd
`servers` blocks, eleven tag groups' worth of operations, 187 page URLs — where
it can be read, reviewed and changed in one place. `scripts/build.py` applies
Expand Down Expand Up @@ -503,11 +503,14 @@ about files that still decide things: does `openapi.yaml` agree with
`tags-map.yaml`? The base is gone; the decisions taken against it are still
enforced.

`PROSE-INVENTORY.csv` records every stripped field by JSON pointer, length and
SHA-256 digest — never the text. It is a worklist for re-grounding, not an
archive to restore from. It is now **frozen**: it could only ever be derived by
diffing against the base, so it describes the strip as it happened and does not
regenerate.
The strip itself was recorded in `PROSE-INVENTORY.csv` — a pointer, length and
SHA-256 digest per field, never the text. It was frozen at the end of Phase 1,
because it could only be derived by diffing against the base, and removed on
2026-09-15: 3,618 of its 4,221 pointers had come to name operations and
components that the drops deleted. The worklist it was meant to be is
`overlays/docs-prose.yaml`, which has one stub per authoring site and is
checked on every build. Recoverable from history if the digests are ever
wanted.

## Known gaps

Expand Down Expand Up @@ -559,9 +562,9 @@ regenerate.
- **The plane split is 39 decided and 82 inherited.** `_project/planes.yaml`
decides which of the four base URLs each path gets, and for 82 paths that call
was read off the base's own per-path server overrides and never independently
verified. It is recorded per path — `inherited` against a named decision —
and `_project/drop-list.md` marks the difference. Getting one wrong publishes
a working endpoint against the wrong host.
verified. It is recorded per path in that file — `inherited` against a named
decision — so the difference is readable there. Getting one wrong publishes a
working endpoint against the wrong host.
- **The recovered Deployments schemas are unexamined.** Deployments was dropped
in Phase 1 on an engineering list and un-dropped in Phase 2 as an admin-plane
capability, which meant recovering six operations from the pre-drop revision.
Expand Down
33 changes: 33 additions & 0 deletions _project/TODO.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -565,6 +565,39 @@ Confirmed working: auth renders as `Authorization: Bearer <token>`.

---

## Repository cleanup — 2026-09-15

Five files removed. Nothing published changed: `openapi.yaml`,
`docs-navigation.json` and `build-report.txt` are byte-identical across the
change, and `check.py`, `build.py --check` and `lint.py` are green either side
of it. All seven scripts under `scripts/` stayed — every one of them is
imported or invoked by CI.

| Removed | Why |
|---|---|
| `PROSE-INVENTORY.csv` | 677 KB, 44% of the tracked repository. Frozen at the end of Phase 1 and **3,618 of its 4,221 pointers dangled** — they named operations and components the drops deleted. It stored digests, never text, so nothing was recoverable from the 603 that resolved |
| `brief.md` | The original handoff. Referenced nowhere; superseded by the README and `PLAN.md` |
| `_project/docs-note.md` | The five docs asks, all completed in Phase 1.5 and recorded there |
| `_project/drop-list.md` | A generated inventory nothing regenerated. It restated `planes.yaml`, and its job — being the tick-list for *choosing* the drops — ended when the choices landed in `drops.yaml` |
| `_project/gen_drop_list.py` | Generated the above |

**The drop list is the one worth a second look.** It was not stale when
removed, but nothing in CI regenerated it, and it had already drifted silently
once — Phase 1 task 7 found it had gone from 23 unclassified paths to 95
without failing. A derived file no gate checks is a file that will eventually
lie. The alternative was to wire it into `build.py --check`; removing it was
chosen because `planes.yaml` already carries the content under a gate.

**Kept, deliberately.** The KB machinery — `scripts/drift.py`,
`scripts/emit_change_event.py`, `webhooks/*.schema.json`, `kb-drift.yml`,
`notify-kb.yml` — is on hold, not cancelled, and is built to stay exercised
while inert. `_project/classification.yaml` is marked historical but is still a
live reference target: `planes.yaml` cites it by name in the `how:` field of 23
paths. `PLAN.md` and `TODO.md` stay whole; a cleanup pass is the wrong place to
decide which reasoning is worth keeping.

---

## Answered — 2026-09-15

| | Question | Answer |
Expand Down
9 changes: 5 additions & 4 deletions _project/classification.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
# Human decisions about which plane a path belongs to.
#
# The default classification in drop-list.md is read off the base author's
# per-path `servers` overrides -- Portkey's opinion, inherited and unverified.
# Anything decided here overrides it and is marked with a tick, so it is always
# visible which calls were made by a person.
# The default classification was read off the base author's per-path `servers`
# overrides -- Portkey's opinion, inherited and unverified. Anything decided
# here overrode it, and `planes.yaml` still cites this file by name in the
# `how:` field of every path it decided, so which calls a person made stays
# visible.
#
# Patterns are fnmatch-style. Note that `*` crosses slashes: /models* matches
# /models/{model} as well as /models, which is exactly the trap below. Two rules
Expand Down
72 changes: 0 additions & 72 deletions _project/docs-note.md
View file
Open in desktop

This file was deleted.

Loading
Loading