From 5ba45b3baa19bb1afedeff199ac951513d757e97 Mon Sep 17 00:00:00 2001 From: James Ross Date: Fri, 12 Jun 2026 23:57:01 -0700 Subject: [PATCH 1/5] docs: add release goalpost roadmap --- ROADMAP.md | 112 +++-- WORKFLOW.md | 2 + docs/DOCS_CHECKLIST.md | 21 +- docs/MARKDOWN_SURFACE.md | 16 +- .../bounded-residency.md | 441 +++++++++++++++++ docs/design/README.md | 1 + docs/goalposts/README.md | 28 ++ .../v6.0.1/release-truth-closeout.md | 120 +++++ docs/goalposts/v6.1.0/bounded-residency.md | 147 ++++++ docs/goalposts/v6.2.0/operator-tui.md | 109 +++++ .../v6.3.0/agent-automation-parity.md | 106 +++++ .../v6.4.0/browser-edge-read-path.md | 109 +++++ .../v7.0.0/protocol-audit-response.md | 102 ++++ docs/method/process.md | 22 + docs/templates/design-doc.md | 445 ++++++++++++++++++ docs/templates/goalpost.md | 115 +++++ test/unit/docs/planning-surfaces.test.js | 32 +- 17 files changed, 1883 insertions(+), 45 deletions(-) create mode 100644 docs/design/0045-v6-1-bounded-residency/bounded-residency.md create mode 100644 docs/goalposts/README.md create mode 100644 docs/goalposts/v6.0.1/release-truth-closeout.md create mode 100644 docs/goalposts/v6.1.0/bounded-residency.md create mode 100644 docs/goalposts/v6.2.0/operator-tui.md create mode 100644 docs/goalposts/v6.3.0/agent-automation-parity.md create mode 100644 docs/goalposts/v6.4.0/browser-edge-read-path.md create mode 100644 docs/goalposts/v7.0.0/protocol-audit-response.md create mode 100644 docs/templates/design-doc.md create mode 100644 docs/templates/goalpost.md diff --git a/ROADMAP.md b/ROADMAP.md index 786dc46f..1a13fbed 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,50 +1,96 @@ # ROADMAP -This file is sequence context, not active planning truth. +`ROADMAP.md` is the release-line index for upcoming `git-cas` work. -Fresh planning now follows the METHOD: +Active implementation still follows the METHOD loop in +[docs/method/process.md](./docs/method/process.md): goalposts are planned here, +pulled into numbered design cycles, proven with tests and witnesses, and shipped +through one pull request per goalpost. -- [WORKFLOW.md](./WORKFLOW.md) -- [docs/method/process.md](./docs/method/process.md) -- [docs/method/backlog/README.md](./docs/method/backlog/README.md) -- [docs/design/README.md](./docs/design/README.md) -- [docs/method/retro/README.md](./docs/method/retro/README.md) +## Reading Order -## Current Reality +1. Start here for release sequencing. +2. Open the release goalpost docs under [docs/goalposts/](./docs/goalposts/). +3. Use [docs/design/](./docs/design/README.md) for cycle-level contracts and + proof plans. +4. Use [docs/method/backlog/](./docs/method/backlog/README.md) for uncommitted + debt and ideas that have not yet become release goalposts. + +## Current State - **Last tagged release:** `v6.0.0` (`2026-05-09`) -- **Current release line:** `v6.x` maintenance on `main` +- **Current branch:** `main` +- **Current release line:** `v6.x` - **Supported runtimes:** Node.js 22.x, Bun, Deno -- **Human surface reality:** the human CLI and TUI are substantial and already - ahead of some older planning docs. -- **Agent surface reality:** a first-class `git cas agent` contract now exists - for shipped Relay flows, but breadth and portability are still incomplete. -- **Planning reality:** fresh work is now chosen from METHOD backlog lanes, not - milestone fiction. -- **Release posture:** npm and GitHub Releases are the active v6.0.x - publication surfaces. JSR publication is deferred until the upstream - `jsr`/Deno dry-run blocker is fixed. +- **Publication surfaces:** npm and GitHub Releases are active; JSR publication + remains deferred until the upstream dry-run blocker is healthy. +- **Planning posture:** `asap/` and `up-next/` are empty. The next product work + is selected from active debt, release truth, and v6.x operator goals. + +## Release Train + +| Release | Theme | Required goalposts | Status | +| --- | --- | --- | --- | +| `v6.0.1` | Patch closeout and planning truth | [Release Truth Closeout](./docs/goalposts/v6.0.1/release-truth-closeout.md) | scaffolded | +| `v6.1.0` | Bounded residency and scale hardening | [Bounded Residency](./docs/goalposts/v6.1.0/bounded-residency.md) | scaffolded | +| `v6.2.0` | Operator TUI consolidation | [Operator TUI](./docs/goalposts/v6.2.0/operator-tui.md) | planned | +| `v6.3.0` | Agent automation parity | [Agent Automation Parity](./docs/goalposts/v6.3.0/agent-automation-parity.md) | planned | +| `v6.4.0` | Browser and edge read-path exploration | [Browser/Edge Read Path](./docs/goalposts/v6.4.0/browser-edge-read-path.md) | planned | +| `v7.0.0` | Protocol break only if audit requires it | [Protocol Audit Response](./docs/goalposts/v7.0.0/protocol-audit-response.md) | provisional | + +## Next Release: `v6.1.0` + +`v6.1.0` should make the core bounded under large vault and large blob +conditions. The target is not a new user-visible feature; it is a stronger +residency contract for the storage surfaces that already exist. + +Goalpost: + +- [Bounded Residency](./docs/goalposts/v6.1.0/bounded-residency.md) + +Design: + +- [0045-v6-1-bounded-residency](./docs/design/0045-v6-1-bounded-residency/bounded-residency.md) + +Required proof: + +- large-vault slug resolution does not materialize the entire vault tree +- vault listing uses the streaming tree path when the adapter provides it +- metadata-sized blob reads remain guarded +- domain data reads prefer `readBlobStream()` for unbounded payloads +- docs and release evidence describe the bounded-residency contract honestly + +## Goalpost Rules -## Current Queue Snapshot +- A goalpost is a release-scale feature or invariant. +- Goalposts are subdivided into turn-sized slices. +- One pull request should carry one goalpost. +- Each slice needs an expected proof: test, fixture, witness, schema, runtime + behavior, docs update, or issue update. +- Goalposts do not replace design cycles. A design cycle is how a goalpost + becomes implementable work. +- Goalposts may start with `not opened yet` issue fields. They should be linked + to GitHub issues before implementation begins. -See the live backlog for exact lane placement: +## Templates -- [TUI — v6.x TUI Modernization](./docs/method/backlog/v6.x-tui/TUI_store-wizard.md) -- [Vault Tree Memory Loading](./docs/method/backlog/bad-code/vault-tree-memory-loading.md) -- [TR — GitPersistenceAdapter Full Materialization](./docs/method/backlog/bad-code/TR_persistence-adapter-materialization.md) +- [Goalpost template](./docs/templates/goalpost.md) +- [Design doc template](./docs/templates/design-doc.md) -## How To Read This File +## Release Gates -Use this file for: +Every release still follows [docs/method/release.md](./docs/method/release.md). +The default local release evidence command is: -- broad sequencing context -- release-line context -- historical orientation +```bash +npm run release:verify -- --skip-jsr +``` -Do not use it as the active backlog. +Use `--skip-jsr` only while the documented upstream JSR/Deno blocker remains +outside this repo. When the dry-run is healthy, full release verification should +include JSR again. -For shipped history, use: +## Not A Roadmap Item -- [CHANGELOG.md](./CHANGELOG.md) -- [docs/design/README.md](./docs/design/README.md) -- [docs/archive/BACKLOG/README.md](./docs/archive/BACKLOG/README.md) +`v7.0.0` is not a general cleanup bucket. It becomes real only if protocol, +storage, migration, or public API evidence requires a breaking change. diff --git a/WORKFLOW.md b/WORKFLOW.md index 43517690..f4cede70 100644 --- a/WORKFLOW.md +++ b/WORKFLOW.md @@ -7,6 +7,8 @@ Fresh work now follows the METHOD in Current planning truth lives in: +- [ROADMAP.md](./ROADMAP.md) +- [docs/goalposts/](./docs/goalposts/README.md) - [docs/method/backlog/](./docs/method/backlog/README.md) - [docs/method/legends/](./docs/method/legends/README.md) - [docs/design/](./docs/design/README.md) diff --git a/docs/DOCS_CHECKLIST.md b/docs/DOCS_CHECKLIST.md index 1d551d51..362a4b87 100644 --- a/docs/DOCS_CHECKLIST.md +++ b/docs/DOCS_CHECKLIST.md @@ -21,8 +21,8 @@ truth and discoverability failures that keep surfacing late in review. Check that adjacent top-level docs can find each other where a maintainer or reviewer would reasonably expect a link. - Planning index hygiene: - If a backlog card, cycle doc, or legend state changed, update the affected - indexes in the same change. + If a roadmap entry, goalpost, backlog card, cycle doc, or legend state + changed, update the affected indexes in the same change. - Empty-state wording: If an index or legend now has an empty list, use the documented house style `- none currently` instead of inventing a new phrase. @@ -43,7 +43,9 @@ changes: - [docs/API.md](./API.md) - [docs/THREAT_MODEL.md](./THREAT_MODEL.md) - [ADVANCED_GUIDE.md](../ADVANCED_GUIDE.md) -- planning indexes under [`docs/method/backlog/`](./method/backlog/README.md), +- planning indexes under [`ROADMAP.md`](../ROADMAP.md), + [`docs/goalposts/`](./goalposts/README.md), + [`docs/method/backlog/`](./method/backlog/README.md), [`docs/design/`](./design/README.md), [`docs/archive/BACKLOG/`](./archive/BACKLOG/README.md), and [`docs/method/legends/`](./method/legends/README.md) @@ -63,14 +65,16 @@ At minimum, confirm the following before review: - summary docs link canonical truth instead of becoming a second narrative - security-sensitive docs route to [SECURITY.md](../SECURITY.md) and [docs/THREAT_MODEL.md](./THREAT_MODEL.md) where those boundaries matter -- planning indexes and legends point to the current backlog, design, retro, and - archive surfaces they describe +- planning indexes and legends point to the current roadmap, goalpost, backlog, + design, retro, and archive surfaces they describe - no touched doc loses an important discoverability link that existed before ## Planning Index Review Run this extra pass whenever a branch changes: +- `ROADMAP.md` +- `docs/goalposts/README.md` - `docs/method/backlog/README.md` - `docs/design/README.md` - `docs/method/legends/README.md` @@ -101,7 +105,9 @@ This checklist is most useful when a change touches files like: - [docs/API.md](./API.md) - [docs/THREAT_MODEL.md](./THREAT_MODEL.md) - [ADVANCED_GUIDE.md](../ADVANCED_GUIDE.md) -- planning indexes under [`docs/method/backlog/`](./method/backlog/README.md), +- planning indexes under [`ROADMAP.md`](../ROADMAP.md), + [`docs/goalposts/`](./goalposts/README.md), + [`docs/method/backlog/`](./method/backlog/README.md), [`docs/design/`](./design/README.md), [`docs/archive/BACKLOG/`](./archive/BACKLOG/README.md), and [`docs/method/legends/`](./method/legends/README.md) @@ -118,5 +124,6 @@ Before a doc-heavy branch is ready for review: - the changed docs point at the right canonical truth - the pre-PR doc cross-link audit passed for the touched surfaces - public and internal boundaries are not blurred -- planning indexes match the files they describe +- planning indexes match the release, goalpost, backlog, and design files they + describe - empty-state wording does not introduce a new style accidentally diff --git a/docs/MARKDOWN_SURFACE.md b/docs/MARKDOWN_SURFACE.md index 88df1fd7..3119659f 100644 --- a/docs/MARKDOWN_SURFACE.md +++ b/docs/MARKDOWN_SURFACE.md @@ -38,8 +38,9 @@ local-only surfaces. work, now as a root signpost into `docs/method/`; belongs at the repo root. - [ARCHITECTURE.md](../ARCHITECTURE.md): `KEEP` — canonical high-level architecture map; still useful as a root-level reference. -- [ROADMAP.md](../ROADMAP.md): `KEEP`, `MERGE` — a slim sequence-context - signpost is useful at the repo root, but it should stay derivative. +- [ROADMAP.md](../ROADMAP.md): `KEEP` — versioned release index and goalpost + routing surface; belongs at the repo root because it is the maintainer's + shortest path from current state to planned releases. - [STATUS.md](../STATUS.md): `KEEP`, `MERGE` — compact snapshot value is real, but it should stay derivative and slim. - [GRAVEYARD.md](../GRAVEYARD.md): `KEEP`, `MOVE` — still useful historical @@ -71,6 +72,12 @@ local-only surfaces. - [docs/method/process.md](./method/process.md): `KEEP` — canonical planning and delivery process for fresh work. +- [docs/goalposts/README.md](./goalposts/README.md): `KEEP` — release + goalpost index between `ROADMAP.md` and numbered design cycles. +- [docs/templates/goalpost.md](./templates/goalpost.md): `KEEP` — reusable + release-goalpost skeleton for fresh planning. +- [docs/templates/design-doc.md](./templates/design-doc.md): `KEEP` — + reusable METHOD cycle design skeleton for fresh planning. - [docs/method/release.md](./method/release.md): `KEEP` — canonical release process for fresh work. - [docs/method/backlog/README.md](./method/backlog/README.md): `KEEP` — @@ -234,5 +241,6 @@ If the repo wants to act on this audit, the highest-value next changes are: 2. decide whether [CLAUDE.md](../CLAUDE.md) should leave tracked root entirely 3. collapse [STATUS.md](../STATUS.md) into other canonical surfaces and remove the duplicate snapshot doc -4. shrink and relocate [ROADMAP.md](../ROADMAP.md) once its remaining migration - value is absorbed elsewhere +4. keep [ROADMAP.md](../ROADMAP.md), [docs/goalposts/](./goalposts/README.md), + and [docs/design/](./design/README.md) synchronized as the release planning + stack evolves diff --git a/docs/design/0045-v6-1-bounded-residency/bounded-residency.md b/docs/design/0045-v6-1-bounded-residency/bounded-residency.md new file mode 100644 index 00000000..502b444d --- /dev/null +++ b/docs/design/0045-v6-1-bounded-residency/bounded-residency.md @@ -0,0 +1,441 @@ +--- +title: "PERF-0045 - Bounded Residency" +cycle: "0045" +task_id: "bounded-residency" +legend: "PERF" +release_home: "v6.1.0" +goalpost: "docs/goalposts/v6.1.0/bounded-residency.md" +issue: "not opened yet" +status: "draft" +base_commit: "662fcc7661114715670c0eb48e78bcce47cae43c" +owners: + - "@git-stunts" +sponsors: + human: "James" + agent: "Codex" +blocking_issues: [] +supersedes: + - "docs/method/backlog/bad-code/vault-tree-memory-loading.md" + - "docs/method/backlog/bad-code/TR_persistence-adapter-materialization.md" +superseded_by: null +created: "2026-06-13" +updated: "2026-06-13" +--- + +# PERF-0045 - Bounded Residency + +## Linked Issue + +- `not opened yet` + +## Linked Goalpost + +- [v6.1.0 Bounded Residency](../../goalposts/v6.1.0/bounded-residency.md) + +## Design Type + +This design is primarily: + +- [x] Runtime/API +- [x] Storage/substrate +- [ ] Migration/release +- [ ] CLI/operator +- [x] Docs/public guidance +- [ ] TUI/visual surface +- [x] Test/tooling + +## Decision Summary + +`v6.1.0` will finish the bounded-residency contract for Git-backed reads. Single +vault entry lookup should use targeted tree reads when available, vault listing +should stay streaming when the adapter supports iteration, and unbounded payload +reads should use `readBlobStream()` rather than `readBlob()` materialization. + +## Sponsored Human + +A maintainer with a large vault wants lookup and list operations to have clear +residency bounds so that `git-cas` remains usable in constrained runtimes, +without having to split vaults or avoid the vault surface. + +## Sponsored Agent + +An agent needs inspectable tests and errors for residency boundaries so it can +choose safe restore and vault operations, without inferring memory behavior from +private adapter implementation details. + +## Hill + +By the end of this cycle, a reviewer can run focused tests that prove targeted +vault lookup, streaming vault list, and stream-first payload reads through the +public persistence contracts, and the release docs describe that behavior +without overstating custom adapter guarantees. + +## Current Truth + +- `docs/method/backlog/bad-code/vault-tree-memory-loading.md` says + `VaultService.#readCachedVaultTree` and dependencies read and parse an entire + Git tree into a slug map. +- `docs/method/backlog/bad-code/TR_persistence-adapter-materialization.md` says + `GitPersistenceAdapter.readBlob` materialization creates O(N) residency + pressure. +- `src/infrastructure/adapters/GitPersistenceAdapter.js` exposes + `readBlobStream()`, `readTreeEntry()`, and `iterateTree()`, and guards + `readBlob()` with a default 10 MB limit. +- `src/domain/services/VaultPersistence.js` already prefers `readTreeEntry()` + in `readEntry()` and exposes `iterateEntries()` over `iterateTree()` when + available. +- `src/domain/services/VaultService.js` still contains cached whole-tree paths, + which means the existing primitives are not yet a complete product contract. +- `src/domain/services/ChunkRepository.js` already requires + `readBlobStream()` for hard-limited buffered restore modes, but the release + needs a complete proof pass across the relevant domain reads. + +## Problem + +The repo has streaming and targeted primitives, but the release contract is not +yet coherent. Some paths can still make a large-vault operation resident before +doing single-entry work, and some docs still describe materialization debt in a +way that no longer matches the partial guard already present in the adapter. + +## Scope + +This cycle includes: + +- RED tests for single vault lookup avoiding `readTree()` when `readTreeEntry()` + is available. +- RED tests for vault list using `iterateTree()` when available. +- RED tests or regression coverage for payload reads preferring + `readBlobStream()` when payload size is unbounded. +- Implementation changes inside `VaultService`, `VaultPersistence`, + `ChunkRepository`, `ManifestRepository`, or adapters as needed. +- Documentation updates to the goalpost, backlog cards, `STATUS.md`, + `CHANGELOG.md`, and release evidence. + +## Non-Goals + +This cycle does not include: + +- changing the vault tree format +- adding pagination to the public API unless targeted tests prove streaming + iteration is insufficient +- browser or edge adapters +- new encryption modes +- changing the package's public storage format +- removing all custom adapter fallback behavior + +## Runtime / API Contract + +The target contract is: + +- `GitPersistencePort.readTreeEntry(treeOid, treePath)` is the preferred + single-entry tree read when implemented by an adapter. +- `GitPersistencePort.iterateTree(treeOid)` is the preferred list scan when + implemented by an adapter. +- `GitPersistencePort.readBlob(oid, maxBytes?)` is for metadata-sized reads and + must stay guarded. +- `GitPersistencePort.readBlobStream(oid)` is the required path for unbounded + payload reads. +- Hard-limited modes that cannot verify their bound through streaming must fail + with an explicit capability error instead of silently materializing. + +No public storage format change is planned. + +## User Experience / Product Shape + +Not applicable as a rendered workflow. The user-visible contract is operational: +large vaults and large payloads should fail less often due to memory residency, +and errors should explain missing adapter capabilities when a safe path is not +available. + +## Data / State Model + +| State | Source of truth | Derived state | Invalid states | Reset behavior | Serialization | Determinism assumptions | +| --- | --- | --- | --- | --- | --- | --- | +| Vault tree | Git tree at `refs/cas/vault` | slug-to-manifest mapping | missing metadata, malformed privacy index, invalid tree entries | reread from current ref | Git tree entries | tree OID fixes content | +| Blob content | Git blob OID | chunk or manifest bytes | blob exceeds guarded metadata read limit | reread stream from OID | Git blob bytes | OID fixes bytes | + +## Architecture / Anti-SLUDGE Posture + +| Concern | Decision | +| --- | --- | +| Domain changes | Keep use-case orchestration in `VaultService`; move substrate-specific lookup decisions into `VaultPersistence` when possible. | +| Port changes | Prefer existing `readTreeEntry`, `iterateTree`, and `readBlobStream`; add port surface only if tests prove a missing contract. | +| Adapter changes | Keep Git CLI implementation inside `GitPersistenceAdapter`. | +| Boundary validation | Guard metadata reads and capability errors at port/domain boundaries. | +| Runtime-backed nouns introduced | None planned. | +| Expected failure representation | `CasError` with existing error codes where possible. | +| Banned shortcuts avoided | Do not solve scale by raising heap limits or documenting "avoid large vaults". | + +## Cost / Residency Posture + +| Surface | Current cost | Target cost | Limit/budget | Failure mode | +| --- | --- | --- | --- | --- | +| Single vault entry lookup | may materialize full tree through cached map | targeted one-entry read when supported | O(1) tree entry result plus metadata reads | fallback documented when adapter lacks support | +| Vault list | streaming primitive exists, but cache paths can force residency | iterator-first list path | O(entry) streaming processing | malformed entry raises `CasError` | +| Metadata blob read | bounded by adapter default in Git adapter | explicitly metadata-sized and guarded | default 10 MB unless caller lowers it | `RESTORE_TOO_LARGE` or domain equivalent | +| Payload blob read | stream support exists | stream-first for unbounded data | chunk stream, not full blob buffer | explicit capability error if safe stream absent | + +## Git Substrate Impact + +| Substrate area | Impact | +| --- | --- | +| refs | Read `refs/cas/vault`; no ref format change. | +| commits | No commit format change. | +| trees/blobs | Prefer targeted tree entry and streaming tree/blob reads. | +| object ids | No object ID behavior change. | +| tag/release behavior | `v6.1.0` release evidence should include bounded-residency proof. | +| migration compatibility | No migration expected. | + +## Compatibility / Migration Posture + +| Concern | Decision | +| --- | --- | +| Public API compatibility | Preserve existing public API unless tests force a narrow addition. | +| Package export changes | None planned. | +| Storage/read compatibility | Existing vaults and manifests remain readable. | +| Legacy behavior retained | Adapter fallbacks stay where they are safe and documented. | +| Deprecation behavior | None planned. | +| Migration path | Not applicable. | +| Release note impact | Changelog should call this scale hardening, not a format change. | + +## Error Contract + +| Failure | Error/result | Caller recovery | Test | +| --- | --- | --- | --- | +| Metadata blob exceeds guard | `CasError` with size details | use stream path or inspect corrupt metadata | adapter readBlob test | +| Adapter lacks stream for hard-limited restore | explicit capability error | implement `readBlobStream()` | restore guard test | +| Targeted tree lookup unsupported | documented fallback | adapter may implement `readTreeEntry()` | vault persistence fallback test | +| Malformed tree entry | `CasError` from parsing boundary | repair Git tree or vault state | tree parser test | + +## Security / Trust / Redaction Posture + +- trust boundary: Git object database and configured persistence adapter +- authority or capability checked: adapter methods and vault encryption keys +- secret-bearing values: vault passphrases, encryption keys, and privacy index + keys remain outside logs and docs +- redaction behavior: no new secret output +- log/report behavior: any witness must use synthetic fixture slugs and OIDs +- abuse or replay concern: no new write authority or replay surface + +## Lower Modes + +The lower mode is deterministic test and witness output: + +- spy tests proving `readTree()` is not called on targeted lookup +- iterator tests proving list reads consume `iterateTree()` +- restore tests proving stream reads are selected +- release witness summarizing focused and full validation commands + +## Accessibility Posture + +This is not rendered UI work. Accessibility is preserved through linear docs, +plain error text, and machine-readable error metadata. No meaning should depend +on color, layout, or terminal cursor behavior. + +## User-Facing Text / Directionality + +Visible text changes should be limited to docs, changelog, and any new or +clarified error message. Text is English, left-to-right, and should have a +machine-readable equivalent in `CasError` metadata where runtime errors change. + +## Agent Inspectability / Explainability Posture + +Agents can inspect the result through: + +- stable test names +- `CasError` codes and metadata +- command transcripts in `docs/design/0045-v6-1-bounded-residency/witness/` +- goalpost closeout checkboxes +- changelog entries that name the actual bounded surfaces + +## Linked Invariants + +- [I-001 - Determinism, Trust, And Explicit Surfaces](../../invariants/I-001-determinism-trust-and-explicit-surfaces.md) +- Tests Are the Spec +- Runtime Truth Wins +- Hexagonal Architecture +- Docs Are Evidence, Not Proof + +## Design Alternatives Considered + +### Option A: Only update docs + +Pros: + +- quick +- acknowledges that some primitives already exist + +Cons: + +- does not prove `VaultService` uses the primitives safely +- leaves active debt unresolved +- risks release notes overstating behavior + +### Option B: Add a new paginated vault API first + +Pros: + +- gives operators explicit paging controls +- can be useful later for TUI and agent surfaces + +Cons: + +- public API work before proving internal residency +- may create API churn when existing `iterateTree()` is enough + +### Option C: Finish the existing bounded primitives + +Pros: + +- uses already-established port boundaries +- keeps public API stable +- maps directly to current active debt + +Cons: + +- custom adapters still need honest fallback handling +- some domain paths may still need careful audit + +## Decision + +Choose Option C. Finish the existing bounded primitives and prove them through +unit, integration, and release evidence before adding new public paging +surfaces. + +## Proof Surface + +The implementation must be proven through: + +- actual surface under test: vault service/persistence, Git persistence adapter, + CAS restore/read paths +- first RED test: single vault entry lookup with `readTreeEntry()` available + must fail if `readTree()` is called +- required witness command: focused tests plus `npm test` +- non-acceptable proof: docs-only assertions or heap-limit anecdotes + +## Implementation Slices + +- Add targeted vault lookup tests. +- Add streaming vault list tests. +- Add or tighten `readBlob()`/`readBlobStream()` residency tests. +- Implement the bounded read behavior. +- Update docs, changelog, goalpost, and witness evidence. + +Each slice should be independently reviewable and should close with a concrete +test or witness. + +## Tests To Write First + +Behavior tests required: + +- [ ] Vault lookup does not call `readTree()` when `readTreeEntry()` can answer + the requested slug. +- [ ] Vault list consumes `iterateTree()` when supported. +- [ ] Metadata blob reads are guarded by size. +- [ ] Payload restore paths prefer `readBlobStream()` and do not fall back to + unbounded `readBlob()` in hard-limited modes. +- [ ] Fallback behavior is covered for custom adapters that lack targeted tree + reads. + +Documentation/process tests, only if relevant: + +- [ ] Goalpost and roadmap links point to real files. +- [ ] Backlog cards are updated or dispositioned after implementation. + +Rule: documentation tests cannot be the only proof for implementation work. + +## Acceptance Criteria + +The work is done when: + +- [ ] Behavior tests prove targeted vault lookup. +- [ ] Behavior tests prove streaming vault listing. +- [ ] Runtime tests prove the blob read contract. +- [ ] Errors are explicit when safe streaming support is missing. +- [ ] Docs, changelog, and release notes are updated. +- [ ] Goalpost closeout is updated. +- [ ] CI and local validation are green. + +## Validation Plan + +Commands expected before PR: + +```bash +npx vitest run test/unit/vault +npx vitest run test/unit/infrastructure/adapters/GitPersistenceAdapter.readBlob.test.js +npx vitest run test/unit/domain/services/CasService.readBlobStream.test.js +npx eslint . +npm test +npm run release:verify -- --skip-jsr +``` + +## Playback / Witness + +Create `docs/design/0045-v6-1-bounded-residency/witness/verification.md` during +implementation. It should include: + +- focused test commands and outputs +- full unit-suite output +- release verifier output if run +- answers to whether each proof story passed + +## Risks + +Known risks: + +- Some existing tests may rely on whole-tree cache behavior. +- Custom persistence adapters may not implement targeted reads or streaming + reads. +- Metadata reads need small-buffer ergonomics while payload reads need strict + stream-first behavior. + +Mitigations: + +- Preserve safe fallbacks and test them. +- Keep public API changes out unless necessary. +- Document capability requirements precisely. + +## Follow-On Debt + +Create backlog files or GitHub issues for: + +- public paginated vault APIs, if tests prove operator need +- browser/edge read-path adapter work +- custom adapter conformance tests beyond the current fixture suite + +## Tracker Disposition + +| Issue | Role | Expected disposition | +| --- | --- | --- | +| `docs/method/backlog/bad-code/vault-tree-memory-loading.md` | primary input | close or mark resolved when tests and implementation land | +| `docs/method/backlog/bad-code/TR_persistence-adapter-materialization.md` | primary input | close or rewrite to remaining custom-adapter risk | +| `not opened yet` | umbrella issue | open before implementation PR | + +## Done Does Not Mean + +When this lands, it does not prove: + +- browser or edge runtime support +- public pagination API ergonomics +- memory bounds inside every third-party custom adapter +- formal performance benchmarking + +## Retrospective + +Fill this in after implementation. + +What changed from the design: + +- `not implemented yet` + +What the tests proved: + +- `not implemented yet` + +What remains open: + +- `not implemented yet` + +PR: + +- `not opened yet` diff --git a/docs/design/README.md b/docs/design/README.md index fab5b8fe..9fcaedde 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -36,6 +36,7 @@ process in [docs/method/process.md](../method/process.md). - [0042-store-write-failure-surface — store-write-failure-surface](./0042-store-write-failure-surface/store-write-failure-surface.md) - [0043-vault-retry-abstraction — vault-retry-abstraction](./0043-vault-retry-abstraction/vault-retry-abstraction.md) - [0044-casservice-decomposition-plan — casservice-decomposition-plan](./0044-casservice-decomposition-plan/casservice-decomposition-plan.md) +- [0045-v6-1-bounded-residency — bounded-residency](./0045-v6-1-bounded-residency/bounded-residency.md) ## Landed METHOD Cycles diff --git a/docs/goalposts/README.md b/docs/goalposts/README.md new file mode 100644 index 00000000..74674f1c --- /dev/null +++ b/docs/goalposts/README.md @@ -0,0 +1,28 @@ +# Goalposts + +Goalposts are release-scale commitments. They sit between +[ROADMAP.md](../../ROADMAP.md) and numbered METHOD cycles under +[docs/design/](../design/README.md). + +Use goalposts when a release needs more structure than a single backlog card: + +- name the release outcome +- divide it into turn-sized slices +- name the proof expected from each slice +- keep one pull request scoped to one goalpost + +## Upcoming Goalposts + +| Release | Goalpost | Status | +| --- | --- | --- | +| `v6.0.1` | [Release Truth Closeout](./v6.0.1/release-truth-closeout.md) | scaffolded | +| `v6.1.0` | [Bounded Residency](./v6.1.0/bounded-residency.md) | scaffolded | +| `v6.2.0` | [Operator TUI](./v6.2.0/operator-tui.md) | planned | +| `v6.3.0` | [Agent Automation Parity](./v6.3.0/agent-automation-parity.md) | planned | +| `v6.4.0` | [Browser/Edge Read Path](./v6.4.0/browser-edge-read-path.md) | planned | +| `v7.0.0` | [Protocol Audit Response](./v7.0.0/protocol-audit-response.md) | provisional | + +## Template + +New goalposts should start from +[docs/templates/goalpost.md](../templates/goalpost.md). diff --git a/docs/goalposts/v6.0.1/release-truth-closeout.md b/docs/goalposts/v6.0.1/release-truth-closeout.md new file mode 100644 index 00000000..956f905d --- /dev/null +++ b/docs/goalposts/v6.0.1/release-truth-closeout.md @@ -0,0 +1,120 @@ +# v6.0.1 Release Truth Closeout + +## Identity + +| Field | Value | +| --- | --- | +| Goalpost id | `v6.0.1-gp-release-truth-closeout` | +| Release home | `v6.0.1` | +| Umbrella issue | `not opened yet` | +| Goalpost doc | `docs/goalposts/v6.0.1/release-truth-closeout.md` | +| Design cycle | `not active yet` | +| Slice budget | `3` | +| Status | `scaffolded` | +| Sponsor human | `James` | +| Sponsor agent | `Codex` | + +## Outcome + +The `v6.0.1` patch release can be tagged or intentionally abandoned from a +truthful state: release docs, backlog lanes, changelog, and verification +evidence all agree with what is on `main`. + +## Current Truth + +- [STATUS.md](../../../STATUS.md) describes `v6.0.1` as a patch candidate on + `main` and records `npm run release:verify -- --skip-jsr` passing 12/12 steps + with 5,383 observed tests. +- [ROADMAP.md](../../../ROADMAP.md) now treats release planning as goalpost + driven rather than milestone fiction. +- [docs/method/backlog/README.md](../../method/backlog/README.md) has empty + `asap/` and `up-next/` lanes. +- Some older TUI backlog cards still describe pre-ship states and need a truth + pass before they become `v6.2.0` goalpost work. + +## Scope + +- Decide whether `v6.0.1` should ship as a patch release or be folded into + `v6.1.0`. +- Reconcile `STATUS.md`, `CHANGELOG.md`, and release evidence. +- Reclassify stale backlog entries that already shipped, became obsolete, or + need a new goalpost. + +## Out Of Scope + +- New runtime behavior. +- Large-vault scale fixes. +- TUI feature work. +- JSR publication unless the upstream dry-run blocker has cleared. + +## Proof Stories + +```text +A maintainer needs one truthful patch-release state +so that the next tag or non-tag decision is auditable, +without relying on scattered memory of previous release runs. +``` + +| Story issue | Actor | Need | Reason | Slice budget | +| --- | --- | --- | --- | ---: | +| `not opened yet` | maintainer | release truth reconciliation | avoid tagging stale evidence | 1 | +| `not opened yet` | maintainer | backlog truth pass | prevent old TUI cards from masquerading as active work | 1 | +| `not opened yet` | agent | deterministic release-state checks | inspect release readiness without reading prose manually | 1 | + +## Slice Budget + +| Slice | Status | Description | Expected proof | +| ---: | --- | --- | --- | +| 1 | open | Reconcile patch release docs and changelog state. | docs test or release-state witness | +| 2 | open | Audit stale backlog cards and reclassify them. | backlog index check | +| 3 | open | Record tag/no-tag decision for `v6.0.1`. | release witness or closeout note | + +## Acceptance Criteria + +- [ ] The patch release decision is explicit. +- [ ] `STATUS.md`, `CHANGELOG.md`, `ROADMAP.md`, and backlog indexes agree. +- [ ] Stale TUI cards are either rewritten, moved, or carried forward with + current truth. +- [ ] Local docs tests and release-state checks pass. + +## Deterministic Evidence + +| Claim | Canonical fixture or input | Witness | Replay command | Expected deterministic result | +| --- | --- | --- | --- | --- | +| Release docs agree | active release docs | docs test output | `npx vitest run test/unit/docs` | no stale release claims | +| Backlog index agrees | lane files | planning surface test | `npx vitest run test/unit/docs/planning-surfaces.test.js` | lane links match files | + +## Substrate / Residency Geometry + +| Reading claim | Basis | Aperture | Law/projection | Support obligations | Witness posture | +| --- | --- | --- | --- | --- | --- | +| Release truth is doc-backed | `main` docs | active release docs only | parse documented release state | docs tests cover stale claims | committed witness or test output | + +## Validation Plan + +```bash +npx vitest run test/unit/docs +npx eslint . +npm test +``` + +## Release Gate Impact + +This goalpost decides whether `v6.0.1` is cut from the current patch candidate +or folded into `v6.1.0`. It should not change package behavior. + +## Residual Risks + +| Risk | Rationale | Owner | Follow-up issue | +| --- | --- | --- | --- | +| JSR remains deferred | The blocker is upstream of this repo. | maintainer | `not opened yet` | + +## Closeout + +- [ ] Slices complete or honestly dispositioned. +- [ ] Proof matrix replayed. +- [ ] Goalpost issue updated. +- [ ] Child proof-story issues closed, superseded, or carried forward. +- [ ] Pull request merged for this goalpost. +- [ ] Release evidence updated when release-relevant. +- [ ] Retrospective or closeout note written. diff --git a/docs/goalposts/v6.1.0/bounded-residency.md b/docs/goalposts/v6.1.0/bounded-residency.md new file mode 100644 index 00000000..9aa2527d --- /dev/null +++ b/docs/goalposts/v6.1.0/bounded-residency.md @@ -0,0 +1,147 @@ +# v6.1.0 Bounded Residency + +## Identity + +| Field | Value | +| --- | --- | +| Goalpost id | `v6.1.0-gp-bounded-residency` | +| Release home | `v6.1.0` | +| Umbrella issue | `not opened yet` | +| Goalpost doc | `docs/goalposts/v6.1.0/bounded-residency.md` | +| Design cycle | `docs/design/0045-v6-1-bounded-residency/bounded-residency.md` | +| Slice budget | `5` | +| Status | `scaffolded` | +| Sponsor human | `James` | +| Sponsor agent | `Codex` | + +## Outcome + +Large vault and large blob operations are bounded by API contract instead of by +hope. `git-cas` can resolve single vault entries, list vault entries, and read +payload data through paths that do not accidentally materialize unbounded Git +trees or blobs. + +## Current Truth + +- [docs/method/backlog/bad-code/vault-tree-memory-loading.md](../../method/backlog/bad-code/vault-tree-memory-loading.md) + names full vault tree loading as active debt. +- [docs/method/backlog/bad-code/TR_persistence-adapter-materialization.md](../../method/backlog/bad-code/TR_persistence-adapter-materialization.md) + names `GitPersistenceAdapter.readBlob()` materialization pressure as active + debt. +- [src/infrastructure/adapters/GitPersistenceAdapter.js](../../../src/infrastructure/adapters/GitPersistenceAdapter.js) + already provides `readBlobStream()`, a default `readBlob()` safety limit, and + tree iteration helpers. +- [src/domain/services/VaultPersistence.js](../../../src/domain/services/VaultPersistence.js) + already contains direct tree-entry and streaming tree iteration boundaries. +- [src/domain/services/VaultService.js](../../../src/domain/services/VaultService.js) + still has cached vault tree paths that can turn single-entry work into + whole-tree residency. + +## Scope + +- Make single vault-entry resolution use targeted tree entry reads when + supported. +- Keep vault listing streaming when `iterateTree()` is available. +- Define the remaining supported role for `readBlob()` as metadata-sized, + guarded reads. +- Prefer `readBlobStream()` for unbounded payload data. +- Add tests and witnesses that prove the residency contract. + +## Out Of Scope + +- Changing the vault on-disk tree format. +- Browser or edge adapters. +- New encryption schemes. +- TUI presentation changes. +- Removing compatibility fallback behavior for custom adapters in this + goalpost unless tests prove it is unsafe. + +## Proof Stories + +```text +A maintainer needs single-entry vault lookup to avoid whole-tree residency +so that large vaults remain usable in constrained runtimes, +without relying on every vault operation being a list operation. +``` + +| Story issue | Actor | Need | Reason | Slice budget | +| --- | --- | --- | --- | ---: | +| `not opened yet` | maintainer | targeted vault entry lookup | avoid O(number of vault entries) reads for one slug | 1 | +| `not opened yet` | operator | streaming vault list | inspect large vaults without forcing a full resident map first | 1 | +| `not opened yet` | agent | explicit residency errors | distinguish bounded metadata reads from payload stream reads | 1 | +| `not opened yet` | maintainer | fallback compatibility tests | keep custom adapters honest while preserving old behavior where safe | 1 | +| `not opened yet` | release owner | release evidence | tag `v6.1.0` with replayable scale proof | 1 | + +## Slice Budget + +| Slice | Status | Description | Expected proof | +| ---: | --- | --- | --- | +| 1 | open | Add RED tests for targeted vault slug lookup. | unit test | +| 2 | open | Add RED tests for streaming vault list and fallback behavior. | unit test | +| 3 | open | Finish `readBlob()`/`readBlobStream()` residency contract tests. | unit and integration tests | +| 4 | open | Implement bounded vault and blob read behavior. | runtime behavior | +| 5 | open | Update docs, changelog, and release witness. | doc update and witness | + +## Acceptance Criteria + +- [ ] Single-slug vault lookup does not call `readTree()` when + `readTreeEntry()` is available. +- [ ] Vault list streams via `iterateTree()` when supported. +- [ ] `readBlob()` has a documented metadata-sized safety role. +- [ ] Unbounded payload restore paths use `readBlobStream()` or fail with an + explicit capability error. +- [ ] `npx eslint .` passes. +- [ ] `npm test` passes. +- [ ] `npm run release:verify -- --skip-jsr` passes before release. + +## Deterministic Evidence + +| Claim | Canonical fixture or input | Witness | Replay command | Expected deterministic result | +| --- | --- | --- | --- | --- | +| Targeted lookup avoids full tree | mocked persistence with `readTreeEntry` spy | unit test | `npx vitest run test/unit/vault` | `readTree()` not called | +| Streaming list uses iterator | mocked persistence with `iterateTree` generator | unit test | `npx vitest run test/unit/vault` | entries yielded without full read | +| Payload reads prefer stream | CAS restore fixture | unit test | `npx vitest run test/unit/domain/services/CasService.readBlobStream.test.js` | `readBlobStream()` used | +| Release readiness | full repo | release verifier | `npm run release:verify -- --skip-jsr` | all non-JSR steps pass | + +## Substrate / Residency Geometry + +| Reading claim | Basis | Aperture | Law/projection | Support obligations | Witness posture | +| --- | --- | --- | --- | --- | --- | +| Single vault entry lookup is bounded | `refs/cas/vault` tree OID | one encoded slug path | `ls-tree -- ` when available | fallback behavior documented | spy test proves no `readTree()` | +| Vault list is streaming-capable | `refs/cas/vault` tree OID | one tree entry at a time | async iterator projection | iterator fallback covered | generator test proves incremental path | +| Payload reads are stream-first | manifest chunk OIDs | chunk stream | `readBlobStream()` over blob content | capability error for hard-limited modes | restore tests assert stream use | + +## Validation Plan + +```bash +npx vitest run test/unit/vault +npx vitest run test/unit/infrastructure/adapters/GitPersistenceAdapter.readBlob.test.js +npx vitest run test/unit/domain/services/CasService.readBlobStream.test.js +npx eslint . +npm test +npm run release:verify -- --skip-jsr +``` + +## Release Gate Impact + +`v6.1.0` should ship with a changelog entry that describes bounded residency as +a scale hardening release. No storage migration is expected. Public API changes +should be avoided unless the design cycle proves a compatibility break is +required. + +## Residual Risks + +| Risk | Rationale | Owner | Follow-up issue | +| --- | --- | --- | --- | +| Custom adapters may still materialize internally | The port cannot inspect third-party implementation details. | maintainer | `not opened yet` | +| Git CLI output is still the storage transport | This goalpost bounds how output is consumed, not how Git produces it. | maintainer | `not opened yet` | + +## Closeout + +- [ ] Slices complete or honestly dispositioned. +- [ ] Proof matrix replayed. +- [ ] Goalpost issue updated. +- [ ] Child proof-story issues closed, superseded, or carried forward. +- [ ] Pull request merged for this goalpost. +- [ ] Release evidence updated when release-relevant. +- [ ] Retrospective or closeout note written. diff --git a/docs/goalposts/v6.2.0/operator-tui.md b/docs/goalposts/v6.2.0/operator-tui.md new file mode 100644 index 00000000..a26023a2 --- /dev/null +++ b/docs/goalposts/v6.2.0/operator-tui.md @@ -0,0 +1,109 @@ +# v6.2.0 Operator TUI + +## Identity + +| Field | Value | +| --- | --- | +| Goalpost id | `v6.2.0-gp-operator-tui` | +| Release home | `v6.2.0` | +| Umbrella issue | `not opened yet` | +| Goalpost doc | `docs/goalposts/v6.2.0/operator-tui.md` | +| Design cycle | `not active yet` | +| Slice budget | `6` | +| Status | `planned` | +| Sponsor human | `James` | +| Sponsor agent | `Codex` | + +## Outcome + +The TUI becomes a coherent operator cockpit: navigation, status, help, +diagnostics, store flow, and detail inspection lower cleanly to keyboard and +agent-readable evidence. + +## Current Truth + +- [BEARING.md](../../../BEARING.md) names TUI modernization as an open tension. +- [docs/method/backlog/v6.x-tui/](../../method/backlog/v6.x-tui/) contains the + v6.x TUI lane. +- [docs/method/backlog/bad-code/TUI_store-wizard-execution-gap.md](../../method/backlog/bad-code/TUI_store-wizard-execution-gap.md) + is marked resolved in the backlog index, so the v6.x TUI lane needs a truth + pass before implementation begins. + +## Scope + +- Reconcile the v6.x TUI lane against shipped behavior. +- Prioritize operator workflows over decorative components. +- Add lower-mode evidence for TUI behavior where possible. +- Keep TUI work behind design cycles with playback questions. + +## Out Of Scope + +- New storage protocol behavior. +- Browser UI. +- Replacing the CLI with the TUI. + +## Proof Stories + +| Story issue | Actor | Need | Reason | Slice budget | +| --- | --- | --- | --- | ---: | +| `not opened yet` | operator | discoverable help and status | use the cockpit without leaving the workflow | 1 | +| `not opened yet` | operator | dependable store/restore diagnostics | trust long-lived operations | 2 | +| `not opened yet` | agent | lower-mode TUI witness | verify behavior without scraping pixels | 1 | +| `not opened yet` | maintainer | stale TUI lane cleanup | avoid rebuilding shipped work | 2 | + +## Slice Budget + +| Slice | Status | Description | Expected proof | +| ---: | --- | --- | --- | +| 1 | open | Audit and rewrite the v6.x TUI lane. | doc update | +| 2 | open | Prioritize help/status/toast/pager/detail behavior. | design cycle | +| 3 | open | Add lower-mode witnesses for key TUI flows. | witness | +| 4 | open | Implement the first operator workflow improvement. | TUI test | +| 5 | open | Implement diagnostic or health cockpit improvement. | TUI/CLI test | +| 6 | open | Release evidence and closeout. | release witness | + +## Acceptance Criteria + +- [ ] Stale TUI cards are corrected before work starts. +- [ ] New TUI work has keyboard, lower-mode, and accessibility posture. +- [ ] Operator-visible behavior is tested through actual TUI or command + surfaces. + +## Deterministic Evidence + +| Claim | Canonical fixture or input | Witness | Replay command | Expected deterministic result | +| --- | --- | --- | --- | --- | +| TUI lane reflects shipped truth | v6.x TUI backlog | docs test or review witness | `npx vitest run test/unit/docs` | no stale active claims | + +## Substrate / Residency Geometry + +| Reading claim | Basis | Aperture | Law/projection | Support obligations | Witness posture | +| --- | --- | --- | --- | --- | --- | +| Not applicable | no storage read claim | n/a | n/a | n/a | n/a | + +## Validation Plan + +```bash +npx eslint . +npm test +``` + +## Release Gate Impact + +This is a minor release because it changes operator-facing workflows. It should +not require storage migration. + +## Residual Risks + +| Risk | Rationale | Owner | Follow-up issue | +| --- | --- | --- | --- | +| TUI tests can drift toward snapshot theater | Rendered behavior needs lower-mode witnesses and state assertions. | maintainer | `not opened yet` | + +## Closeout + +- [ ] Slices complete or honestly dispositioned. +- [ ] Proof matrix replayed. +- [ ] Goalpost issue updated. +- [ ] Pull request merged for this goalpost. +- [ ] Release evidence updated when release-relevant. +- [ ] Retrospective or closeout note written. diff --git a/docs/goalposts/v6.3.0/agent-automation-parity.md b/docs/goalposts/v6.3.0/agent-automation-parity.md new file mode 100644 index 00000000..5434f252 --- /dev/null +++ b/docs/goalposts/v6.3.0/agent-automation-parity.md @@ -0,0 +1,106 @@ +# v6.3.0 Agent Automation Parity + +## Identity + +| Field | Value | +| --- | --- | +| Goalpost id | `v6.3.0-gp-agent-automation-parity` | +| Release home | `v6.3.0` | +| Umbrella issue | `not opened yet` | +| Goalpost doc | `docs/goalposts/v6.3.0/agent-automation-parity.md` | +| Design cycle | `not active yet` | +| Slice budget | `5` | +| Status | `planned` | +| Sponsor human | `James` | +| Sponsor agent | `Codex` | + +## Outcome + +The `git cas agent` surface is stable enough for automated operators to use +without mirroring human CLI parsing, TUI state, or private implementation +details. + +## Current Truth + +- [STATUS.md](../../../STATUS.md) says the machine-facing `git cas agent` + surface exists, but parity and portability are still partial. +- [docs/design/](../../design/README.md) contains landed Relay and agent CLI + design history. + +## Scope + +- Inventory the agent command contract against the human CLI. +- Stabilize JSON result shapes and error contracts where drift exists. +- Add examples and lower-mode witnesses for automation flows. +- Keep credential behavior aligned with human command behavior. + +## Out Of Scope + +- New storage formats. +- TUI-only workflows. +- Remote daemon protocol work unless a design proves it is required. + +## Proof Stories + +| Story issue | Actor | Need | Reason | Slice budget | +| --- | --- | --- | --- | ---: | +| `not opened yet` | agent | stable JSON command results | automate without scraping prose | 2 | +| `not opened yet` | operator | matching credential behavior | avoid human/agent surprise | 1 | +| `not opened yet` | maintainer | conformance examples | prevent docs/API drift | 1 | +| `not opened yet` | release owner | release witness | prove parity before tag | 1 | + +## Slice Budget + +| Slice | Status | Description | Expected proof | +| ---: | --- | --- | --- | +| 1 | open | Agent/human command inventory. | witness | +| 2 | open | JSON and error contract hardening. | CLI tests | +| 3 | open | Credential parity tests. | integration tests | +| 4 | open | Automation examples. | docs tests | +| 5 | open | Release evidence. | witness | + +## Acceptance Criteria + +- [ ] Agent command outputs have documented JSON contracts. +- [ ] Error behavior is machine-readable. +- [ ] Credential resolution is aligned with human CLI behavior. +- [ ] Public examples are covered by tests or witnesses. + +## Deterministic Evidence + +| Claim | Canonical fixture or input | Witness | Replay command | Expected deterministic result | +| --- | --- | --- | --- | --- | +| Agent JSON is stable | fixture repo and command inputs | command transcript | `git cas agent ... --json` | schema-compatible JSON | + +## Substrate / Residency Geometry + +| Reading claim | Basis | Aperture | Law/projection | Support obligations | Witness posture | +| --- | --- | --- | --- | --- | --- | +| Agent reads match public commands | fixture repo refs | command-level aperture | documented command output | JSON schema or fixture | command witness | + +## Validation Plan + +```bash +npx eslint . +npm test +npm run release:verify -- --skip-jsr +``` + +## Release Gate Impact + +This is a minor release because it strengthens public machine-facing behavior. + +## Residual Risks + +| Risk | Rationale | Owner | Follow-up issue | +| --- | --- | --- | --- | +| Agent parity can expand without bound | The design cycle must choose a bounded command set. | maintainer | `not opened yet` | + +## Closeout + +- [ ] Slices complete or honestly dispositioned. +- [ ] Proof matrix replayed. +- [ ] Goalpost issue updated. +- [ ] Pull request merged for this goalpost. +- [ ] Release evidence updated when release-relevant. +- [ ] Retrospective or closeout note written. diff --git a/docs/goalposts/v6.4.0/browser-edge-read-path.md b/docs/goalposts/v6.4.0/browser-edge-read-path.md new file mode 100644 index 00000000..e4cb800d --- /dev/null +++ b/docs/goalposts/v6.4.0/browser-edge-read-path.md @@ -0,0 +1,109 @@ +# v6.4.0 Browser/Edge Read Path + +## Identity + +| Field | Value | +| --- | --- | +| Goalpost id | `v6.4.0-gp-browser-edge-read-path` | +| Release home | `v6.4.0` | +| Umbrella issue | `not opened yet` | +| Goalpost doc | `docs/goalposts/v6.4.0/browser-edge-read-path.md` | +| Design cycle | `not active yet` | +| Slice budget | `6` | +| Status | `planned` | +| Sponsor human | `James` | +| Sponsor agent | `Codex` | + +## Outcome + +`git-cas` has a credible read-only browser or edge path for listing and +restoring existing content without shelling out to the Git CLI. + +## Current Truth + +- [BEARING.md](../../../BEARING.md) names browser/edge persistence as an open + tension. +- The current Git persistence path depends on the Git CLI through + `@git-stunts/plumbing`. +- The domain architecture already uses ports for persistence, crypto, and + compression boundaries. + +## Scope + +- Design a read-only persistence adapter boundary for browser or edge + environments. +- Prove restore/list for a fixture repository if a practical adapter is chosen. +- Keep write-path ref updates out of the first browser/edge release. + +## Out Of Scope + +- Browser write support. +- Hosted synchronization service. +- Replacing the Git CLI path for Node/Bun/Deno. +- Storage format changes. + +## Proof Stories + +| Story issue | Actor | Need | Reason | Slice budget | +| --- | --- | --- | --- | ---: | +| `not opened yet` | browser user | read-only restore | inspect stored content without a local Git CLI | 2 | +| `not opened yet` | agent | adapter capability facts | detect browser-safe surfaces | 1 | +| `not opened yet` | maintainer | no write-path promise | avoid unsupported ref mutation claims | 1 | +| `not opened yet` | release owner | fixture evidence | prove the read path is real | 2 | + +## Slice Budget + +| Slice | Status | Description | Expected proof | +| ---: | --- | --- | --- | +| 1 | open | Adapter design and capability contract. | design cycle | +| 2 | open | Fixture repository read model. | fixture | +| 3 | open | Browser/edge compression posture. | runtime test | +| 4 | open | Restore/list proof. | integration test | +| 5 | open | Docs and examples. | docs test | +| 6 | open | Release evidence. | witness | + +## Acceptance Criteria + +- [ ] The first browser/edge contract is explicitly read-only. +- [ ] The adapter does not require the Git CLI. +- [ ] Capability detection is machine-readable. +- [ ] Docs do not imply write-path support. + +## Deterministic Evidence + +| Claim | Canonical fixture or input | Witness | Replay command | Expected deterministic result | +| --- | --- | --- | --- | --- | +| Read-only adapter can restore fixture content | fixture object graph | runtime witness | `not selected yet` | restored bytes match fixture | + +## Substrate / Residency Geometry + +| Reading claim | Basis | Aperture | Law/projection | Support obligations | Witness posture | +| --- | --- | --- | --- | --- | --- | +| Browser reads Git objects without CLI | fixture object ids | object fetch aperture | adapter maps OID to bytes | integrity check | fixture witness | + +## Validation Plan + +```bash +npx eslint . +npm test +``` + +## Release Gate Impact + +This is a minor release only if a real read path lands. A design-only outcome +should remain unreleased or fold into another release. + +## Residual Risks + +| Risk | Rationale | Owner | Follow-up issue | +| --- | --- | --- | --- | +| Edge runtime APIs differ | The first adapter may support only one browser/edge shape. | maintainer | `not opened yet` | + +## Closeout + +- [ ] Slices complete or honestly dispositioned. +- [ ] Proof matrix replayed. +- [ ] Goalpost issue updated. +- [ ] Pull request merged for this goalpost. +- [ ] Release evidence updated when release-relevant. +- [ ] Retrospective or closeout note written. diff --git a/docs/goalposts/v7.0.0/protocol-audit-response.md b/docs/goalposts/v7.0.0/protocol-audit-response.md new file mode 100644 index 00000000..5431c554 --- /dev/null +++ b/docs/goalposts/v7.0.0/protocol-audit-response.md @@ -0,0 +1,102 @@ +# v7.0.0 Protocol Audit Response + +## Identity + +| Field | Value | +| --- | --- | +| Goalpost id | `v7.0.0-gp-protocol-audit-response` | +| Release home | `v7.0.0` | +| Umbrella issue | `not opened yet` | +| Goalpost doc | `docs/goalposts/v7.0.0/protocol-audit-response.md` | +| Design cycle | `not active yet` | +| Slice budget | `unknown` | +| Status | `planned` | +| Sponsor human | `James` | +| Sponsor agent | `Codex` | + +## Outcome + +`v7.0.0` exists only if audit, protocol, storage, migration, or public API +evidence requires a breaking change. Otherwise the work remains in `v6.x`. + +## Current Truth + +- [BEARING.md](../../../BEARING.md) names formal crypto audit as an open + tension. +- `v6.0.0` simplified encryption schemes and added migration tooling. +- No third-party audit result is currently recorded in the repo. + +## Scope + +- Record audit findings when they exist. +- Design migration paths for any required storage or protocol break. +- Make breaking changes only with explicit evidence and release notes. + +## Out Of Scope + +- Aesthetic refactors. +- Renaming public APIs without a protocol or safety reason. +- Breaking stored content compatibility for cleanup convenience. + +## Proof Stories + +| Story issue | Actor | Need | Reason | Slice budget | +| --- | --- | --- | --- | ---: | +| `not opened yet` | security reviewer | explicit protocol response | map audit findings to release behavior | unknown | +| `not opened yet` | operator | migration path | keep existing stores recoverable | unknown | +| `not opened yet` | maintainer | no gratuitous major release | preserve trust in semver | unknown | + +## Slice Budget + +| Slice | Status | Description | Expected proof | +| ---: | --- | --- | --- | +| 1 | blocked | Obtain or record audit findings. | audit artifact | +| 2 | blocked | Classify findings by semver impact. | design doc | +| 3 | blocked | Design migration and compatibility posture. | migration tests | + +## Acceptance Criteria + +- [ ] A breaking change is tied to concrete audit or protocol evidence. +- [ ] Migration behavior is tested before release. +- [ ] `UPGRADING.md`, `CHANGELOG.md`, and release evidence are updated. + +## Deterministic Evidence + +| Claim | Canonical fixture or input | Witness | Replay command | Expected deterministic result | +| --- | --- | --- | --- | --- | +| Breaking change is justified | audit finding | release design | `not applicable yet` | explicit finding-to-change trace | + +## Substrate / Residency Geometry + +| Reading claim | Basis | Aperture | Law/projection | Support obligations | Witness posture | +| --- | --- | --- | --- | --- | --- | +| Migration preserves recoverability | legacy fixtures | migration read aperture | old object graph to new manifest/protocol | fixture coverage | migration witness | + +## Validation Plan + +```bash +npx eslint . +npm test +npm run release:verify +``` + +## Release Gate Impact + +This is a major release only if the release evidence proves a breaking change is +necessary. Otherwise this goalpost should be superseded by `v6.x` audit +hardening work. + +## Residual Risks + +| Risk | Rationale | Owner | Follow-up issue | +| --- | --- | --- | --- | +| Audit scope is unknown | No audit artifact exists yet. | maintainer | `not opened yet` | + +## Closeout + +- [ ] Slices complete or honestly dispositioned. +- [ ] Proof matrix replayed. +- [ ] Goalpost issue updated. +- [ ] Pull request merged for this goalpost. +- [ ] Release evidence updated when release-relevant. +- [ ] Retrospective or closeout note written. diff --git a/docs/method/process.md b/docs/method/process.md index 0df6f40b..31777f9b 100644 --- a/docs/method/process.md +++ b/docs/method/process.md @@ -33,6 +33,7 @@ Fresh planning now uses: ```text docs/ + goalposts/ method/ backlog/ inbox/ @@ -58,6 +59,27 @@ Repo-specific notes: - Legacy planning compatibility surfaces remain in `docs/BACKLOG/` and `docs/legends/`, but they are no longer the source of truth for fresh work. +## Roadmap And Goalposts + +[ROADMAP.md](../../ROADMAP.md) lists upcoming versioned releases. A release is +made of goalposts, and a goalpost is a release-scale feature, invariant, or +evidence packet that must be met before that release can honestly ship. + +Goalpost docs live in [docs/goalposts/](../goalposts/README.md). They do not +replace backlog items or design cycles: + +- backlog files capture raw debt and ideas +- goalposts choose which work belongs to a versioned release +- design cycles make one goalpost implementable and testable +- pull requests should normally carry one goalpost + +Goalposts are subdivided into slices. A slice should be small enough to finish +in one focused turn and should name its expected proof. + +Use [docs/templates/goalpost.md](../templates/goalpost.md) for new goalposts and +[docs/templates/design-doc.md](../templates/design-doc.md) for new cycle +designs. + ## Backlog Backlog items are Markdown files. The directory lane is the priority. diff --git a/docs/templates/design-doc.md b/docs/templates/design-doc.md new file mode 100644 index 00000000..b2660df9 --- /dev/null +++ b/docs/templates/design-doc.md @@ -0,0 +1,445 @@ +# Design Doc Template + +This is the standard shape for new `git-cas` METHOD cycle design docs. + +Design docs define intent, contracts, non-goals, and proof plans. They do not +prove implementation. For implementation work, at least one required test must +exercise the actual software surface: package API, runtime behavior, Git-backed +persistence behavior, migration behavior, CLI command behavior, TUI behavior, +schema validation, public docs examples, machine-readable witness output, +CI/tooling behavior, or release behavior. + +Documentation assertions, inventory tests, and docs guards are allowed as +evidence-ledger checks. They cannot be the only acceptance proof for product, +runtime, storage, protocol, migration, CLI, TUI, release, or rendered work. + +## Frontmatter + +Use this frontmatter for new cycle design docs: + +```yaml +--- +title: "- - " +cycle: "" +task_id: "" +legend: "" +release_home: "vX.Y.Z|none" +goalpost: "docs/goalposts/vX.Y.Z/.md|none" +issue: "https://github.com/git-stunts/git-cas/issues/|not opened yet" +status: "draft|active|landed|superseded" +base_commit: "" +owners: + - "@git-stunts" +sponsors: + human: "James" + agent: "Codex" +blocking_issues: [] +supersedes: [] +superseded_by: null +created: "YYYY-MM-DD" +updated: "YYYY-MM-DD" +--- +``` + +Status meanings: + +- `draft`: not yet committed as active work. +- `active`: pulled into a cycle; sponsors own the hill. +- `landed`: implementation and witness evidence merged or otherwise complete. +- `superseded`: replaced by another design; `superseded_by` points at it. + +## Required Sections + +Every new cycle design doc must include these sections: + +- Linked Issue +- Linked Goalpost +- Design Type +- Decision Summary +- Sponsored Human +- Sponsored Agent +- Hill +- Current Truth +- Problem +- Scope +- Non-Goals +- Runtime / API Contract and/or User Experience / Product Shape +- Accessibility Posture +- Agent Inspectability / Explainability Posture +- Linked Invariants +- Design Alternatives Considered +- Decision +- Proof Surface +- Implementation Slices +- Tests To Write First +- Acceptance Criteria +- Validation Plan +- Playback / Witness +- Risks +- Follow-On Debt +- Tracker Disposition +- Done Does Not Mean +- Retrospective + +## Conditional Sections + +Include these sections when the design touches the named concern: + +| Section | Required when | +| --- | --- | +| Data / State Model | State persists, mutates, derives, or crosses a boundary. | +| Architecture / Anti-SLUDGE Posture | Code changes. | +| Cost / Residency Posture | Public APIs, reads, writes, content, vaults, manifests, or large-object behavior change. | +| Determinism / Replay / Causality | Migration, release evidence, object identity, manifests, vault history, or deterministic witnesses change. | +| Git Substrate Impact | Refs, commits, trees, blobs, object ids, tags, storage, migration, or release behavior change. | +| Compatibility / Migration Posture | Public API, package export, storage format, docs, release, or legacy behavior changes. | +| Error Contract | Runtime, API, CLI, migration, TUI, or operator behavior changes. | +| Security / Trust / Redaction Posture | Authority, logs, reports, trust, secrets, encryption, keys, or signatures change. | +| Lower Modes | The result is user-visible or agent-visible. | +| User-Facing Text / Directionality | Visible CLI, TUI, docs, report, or error text changes. | +| UI Mockups | TUI, visual, docs-app, or interactive visual surfaces change. | + +`git-cas` does not currently have localization support. Design docs must not +invent localization process, locale catalogs, or translation-completeness gates. +When visible text changes, the design still names the strings, accessibility +implications, machine-readable equivalent output, and directionality +assumptions. + +## Evidence Rules + +Current Truth is factual, not aspirational. Strong claims must cite concrete +evidence: + +- source files +- tests +- commands +- public APIs +- current docs +- GitHub issues or pull requests +- committed witness artifacts +- CI run URLs, when CI evidence matters + +Local command results may support a design, but they are not durable release +evidence unless captured in a committed witness, retro, CI run, or other +inspectable artifact. + +## Template + +Copy this skeleton when opening a new cycle design: + +````markdown +--- +title: "- - " +cycle: "" +task_id: "" +legend: "" +release_home: "vX.Y.Z|none" +goalpost: "docs/goalposts/vX.Y.Z/.md|none" +issue: "https://github.com/git-stunts/git-cas/issues/|not opened yet" +status: "draft|active|landed|superseded" +base_commit: "" +owners: + - "@git-stunts" +sponsors: + human: "James" + agent: "Codex" +blocking_issues: [] +supersedes: [] +superseded_by: null +created: "YYYY-MM-DD" +updated: "YYYY-MM-DD" +--- + +# - - + +## Linked Issue + +- `not opened yet` + +## Linked Goalpost + +- `docs/goalposts/vX.Y.Z/.md` + +## Design Type + +This design is primarily: + +- [ ] Runtime/API +- [ ] Storage/substrate +- [ ] Migration/release +- [ ] CLI/operator +- [ ] Docs/public guidance +- [ ] TUI/visual surface +- [ ] Test/tooling + +## Decision Summary + +One short paragraph describing the decision this document is making. Say what +will exist, what it will do, and what boundary it owns. + +## Sponsored Human + +A wants so that , without having to +. + +## Sponsored Agent + +An agent needs so it can , +without inferring . + +## Hill + +By the end of this cycle, can through +, and the repo proves it with . + +## Current Truth + +Describe what exists today. Include concrete anchors: files, commands, exported +APIs, current docs, current failure mode, relevant issues or PRs, and known test +coverage. + +## Problem + +State the actual problem. + +## Scope + +This cycle includes: + +- ... + +## Non-Goals + +This cycle does not include: + +- ... + +## Runtime / API Contract + +Name the software contract. Include only the relevant subsections: + +- exported functions/types +- command intents +- schema input/output +- facts emitted +- state transitions +- layout/focus/input boundaries +- error behavior +- compatibility aliases or migration behavior + +## User Experience / Product Shape + +Required for CLI, TUI, docs, visual, or public onboarding work. For non-rendered +runtime work, say "Not applicable" and explain which runtime or operator +surface is the user-visible contract. + +## Data / State Model + +Required when state persists, mutates, derives, or crosses a boundary. + +| State | Source of truth | Derived state | Invalid states | Reset behavior | Serialization | Determinism assumptions | +| --- | --- | --- | --- | --- | --- | --- | +| | | | | | | | + +## Architecture / Anti-SLUDGE Posture + +Required when code changes. + +| Concern | Decision | +| --- | --- | +| Domain changes | | +| Port changes | | +| Adapter changes | | +| Boundary validation | | +| Runtime-backed nouns introduced | | +| Expected failure representation | | +| Banned shortcuts avoided | | + +## Cost / Residency Posture + +Required when public APIs, reads, writes, content, vaults, manifests, or +large-object behavior change. + +| Surface | Current cost | Target cost | Limit/budget | Failure mode | +| --- | --- | --- | --- | --- | +| | bounded/streaming/cursor/transitional/diagnostic/legacy | | | | + +## Git Substrate Impact + +Required when refs, commits, trees, blobs, object ids, tags, storage, +migration, or release behavior change. + +| Substrate area | Impact | +| --- | --- | +| refs | | +| commits | | +| trees/blobs | | +| object ids | | +| tag/release behavior | | +| migration compatibility | | + +## Compatibility / Migration Posture + +Required when public API, package exports, storage format, docs, release, or +legacy behavior changes. + +| Concern | Decision | +| --- | --- | +| Public API compatibility | | +| Package export changes | | +| Storage/read compatibility | | +| Legacy behavior retained | | +| Deprecation behavior | | +| Migration path | | +| Release note impact | | + +## Error Contract + +Required when runtime, API, CLI, migration, TUI, or operator behavior changes. + +| Failure | Error/result | Caller recovery | Test | +| --- | --- | --- | --- | +| | | | | + +## Security / Trust / Redaction Posture + +Required when authority, logs, reports, trust, secrets, encryption, keys, or +signatures change. + +- trust boundary: +- authority or capability checked: +- secret-bearing values: +- redaction behavior: +- log/report behavior: +- abuse or replay concern: + +## Lower Modes + +Required when the result is user-visible or agent-visible. + +## Accessibility Posture + +State how accessibility is preserved. For non-rendered runtime work, describe +the linear reading model for docs, CLI output, reports, errors, or witness +artifacts. + +## User-Facing Text / Directionality + +Required only when this design adds or changes visible CLI, TUI, docs, report, +or error text. + +## Agent Inspectability / Explainability Posture + +Describe how an agent can inspect the result without scraping pixels or prose. + +## Linked Invariants + +List repo invariants this work must preserve. + +## Design Alternatives Considered + +### Option A: + +Pros: + +- ... + +Cons: + +- ... + +## Decision + +State the chosen option and why. + +## Proof Surface + +The implementation must be proven through: + +- actual surface under test: +- first RED test: +- required witness command: +- non-acceptable proof: + +## Implementation Slices + +- +- +- + +## Tests To Write First + +Behavior tests required: + +- [ ] +- [ ] +- [ ] +- [ ] + +Rule: documentation tests cannot be the only proof for implementation work. + +## Acceptance Criteria + +The work is done when: + +- [ ] Behavior test proves +- [ ] Runtime API, rendered output, command output, or witness proves + +- [ ] Lower modes are covered, if relevant +- [ ] Docs, changelog, or release notes are updated, if behavior or direction + changed +- [ ] Issue and PR are linked correctly +- [ ] CI and local validation are green + +## Validation Plan + +Commands expected before PR: + +```bash +npx eslint . +npm test +npm run release:verify -- --skip-jsr +``` + +Trim commands that do not apply. Add focused tests and package-specific commands +when needed. + +## Playback / Witness + +Describe what a reviewer can run or inspect. + +## Risks + +Known risks: + +- ... + +Mitigations: + +- ... + +## Follow-On Debt + +Create GitHub issues or backlog files for anything deferred. Do not hide future +work in prose. + +## Tracker Disposition + +| Issue | Role | Expected disposition | +| --- | --- | --- | +| not opened yet | primary / blocks / blocked-by / follow-on | close / update / leave open / create follow-up | + +## Done Does Not Mean + +When this lands, it does not prove: + +- ... + +## Retrospective + +Fill this in after implementation. + +PR: + +- `not opened yet` +```` diff --git a/docs/templates/goalpost.md b/docs/templates/goalpost.md new file mode 100644 index 00000000..7fb56480 --- /dev/null +++ b/docs/templates/goalpost.md @@ -0,0 +1,115 @@ +# Goalpost Template + +Copy this skeleton when creating a `git-cas` release goalpost. + +Goalposts sit between the release roadmap and METHOD design cycles. They name a +release-scale outcome, divide it into turn-sized slices, and point to the proof +that must exist before a pull request can land. One pull request should carry +one goalpost. + +````markdown +# + +## Identity + +| Field | Value | +| --- | --- | +| Goalpost id | `` | +| Release home | `vX.Y.Z` | +| Umbrella issue | `https://github.com/git-stunts/git-cas/issues/` or `not opened yet` | +| Goalpost doc | `` | +| Design cycle | `` or `not active yet` | +| Slice budget | `` | +| Status | `planned|scaffolded|active|review-ready|landed|superseded` | +| Sponsor human | `` | +| Sponsor agent | `` | + +## Outcome + +State the release-scale outcome this goalpost unlocks. + +## Current Truth + +Cite current repo-visible facts. Strong claims need source, test, command, +issue, pull request, generated artifact, witness, release note, or CI evidence. + +## Scope + +- `` + +## Out Of Scope + +- `` + +## Proof Stories + +Use the proof-story form: + +```text +A needs +so that , +without relying on . +``` + +| Story issue | Actor | Need | Reason | Slice budget | +| --- | --- | --- | --- | ---: | +| `not opened yet` | `` | `` | `` | `` | + +## Slice Budget + +| Slice | Status | Description | Expected proof | +| ---: | --- | --- | --- | +| 1 | open | `` | `` | + +## Acceptance Criteria + +- [ ] `` + +## Deterministic Evidence + +| Claim | Canonical fixture or input | Witness | Replay command | Expected deterministic result | +| --- | --- | --- | --- | --- | +| `` | `` | `` | `` | `` | + +## Substrate / Residency Geometry + +Name the Git substrate basis, aperture, materialization law, projection, support +obligations, budget posture, residual posture, and witness posture for any claim +about refs, commits, trees, blobs, manifests, vaults, or large-content reads. + +| Reading claim | Basis | Aperture | Law/projection | Support obligations | Witness posture | +| --- | --- | --- | --- | --- | --- | +| `` | `` | `` | `` | `` | `` | + +## Validation Plan + +```bash +npx eslint . +npm test +npm run release:verify -- --skip-jsr +``` + +Trim commands that do not apply. Add focused tests, fixtures, Docker runtime +commands, or witness replay commands when needed. + +## Release Gate Impact + +Describe how this goalpost affects the target release gate, release evidence +packet, changelog, docs, package surface, migration posture, or runtime matrix. + +## Residual Risks + +| Risk | Rationale | Owner | Follow-up issue | +| --- | --- | --- | --- | +| `None` | `No accepted residual risks.` | `n/a` | `n/a` | + +## Closeout + +- [ ] Slices complete or honestly dispositioned. +- [ ] Proof matrix replayed. +- [ ] Goalpost issue updated. +- [ ] Child proof-story issues closed, superseded, or carried forward. +- [ ] Pull request merged for this goalpost. +- [ ] Release evidence updated when release-relevant. +- [ ] Retrospective or closeout note written. +```` diff --git a/test/unit/docs/planning-surfaces.test.js b/test/unit/docs/planning-surfaces.test.js index e7c4fd48..3be41c73 100644 --- a/test/unit/docs/planning-surfaces.test.js +++ b/test/unit/docs/planning-surfaces.test.js @@ -1,5 +1,5 @@ import { describe, it, expect } from 'vitest'; -import { readFileSync, readdirSync } from 'node:fs'; +import { existsSync, readFileSync, readdirSync } from 'node:fs'; import path from 'node:path'; const repoRoot = process.cwd(); @@ -26,6 +26,23 @@ function markdownLinks(markdown) { return [...markdown.matchAll(/\[[^\]]+\]\(([^)]+)\)/g)].map((match) => match[1]); } +function localMarkdownLinks(markdown) { + return markdownLinks(markdown) + .filter((link) => !link.startsWith('http')) + .filter((link) => !link.startsWith('#')); +} + +function assertLocalMarkdownLinksExist(file) { + const directory = path.dirname(file); + const missing = localMarkdownLinks(read(file)) + .map((link) => link.split('#')[0]) + .filter(Boolean) + .map((link) => path.normalize(path.join(directory, link))) + .filter((target) => !existsSync(path.join(repoRoot, target))); + + expect(missing).toEqual([]); +} + function statusLine(markdown) { return markdown.match(/^-\s+\*\*Status\*\*:\s*(.+)$/mu)?.[1] ?? ''; } @@ -116,4 +133,17 @@ describe('planning surfaces', () => { // eslint-disable-line max-lines-per-funct } } }); + + it('keeps roadmap goalpost links pointed at real planning docs', () => { + const files = [ + 'ROADMAP.md', + 'WORKFLOW.md', + 'docs/goalposts/README.md', + 'docs/method/process.md', + ]; + + for (const file of files) { + assertLocalMarkdownLinksExist(file); + } + }); }); From 108103969895828f56d8c5dafed428fcaf219049 Mon Sep 17 00:00:00 2001 From: James Ross Date: Sat, 13 Jun 2026 00:46:26 -0700 Subject: [PATCH 2/5] docs: make github issues canonical tracker --- .github/ISSUE_TEMPLATE/bug.yml | 49 +++++ .github/ISSUE_TEMPLATE/config.yml | 5 + .github/ISSUE_TEMPLATE/debt.yml | 40 +++++ .github/ISSUE_TEMPLATE/goalpost.yml | 85 +++++++++ .github/ISSUE_TEMPLATE/idea.yml | 27 +++ .github/ISSUE_TEMPLATE/slice.yml | 55 ++++++ .github/pull_request_template.md | 21 +++ BEARING.md | 26 ++- CHANGELOG.md | 13 ++ CONTRIBUTING.md | 39 ++-- GUIDE.md | 2 +- METHOD.md | 63 ++----- ROADMAP.md | 121 +++++-------- STATUS.md | 17 +- WORKFLOW.md | 9 +- docs/BACKLOG/README.md | 11 +- docs/DOCS_CHECKLIST.md | 21 +-- docs/MARKDOWN_SURFACE.md | 18 +- docs/archive/README.md | 6 +- .../BAD-CODE-001_casservice-god-object.md | 0 .../DOC_api-plumbing-constructor-drift.md | 0 .../bad-code/DOC_examples-uint8array-drift.md | 0 .../bad-code/DOC_threat-model-scheme-drift.md | 0 .../bad-code/RL_agent-cli-module-size.md | 0 .../RL_credential-resolution-duplication.md | 0 .../SEC_chunk-constructor-property-leak.md | 0 .../bad-code/SEC_concurrency-upper-bound.md | 0 .../bad-code/SEC_encode-slug-control-chars.md | 0 .../bad-code/SEC_framebytes-upper-bound.md | 0 .../bad-code/SEC_inline-passphrase-flags.md | 0 .../bad-code/SEC_kdf-salt-min-length.md | 0 .../bad-code/SEC_recipient-timing-oracle.md | 0 .../bad-code/SEC_schema-hex-validation.md | 0 .../bad-code/SEC_scrypt-memory-budget.md | 0 .../bad-code/SEC_store-source-validation.md | 0 .../bad-code/SEC_submanifest-array-limit.md | 0 .../SEC_submanifest-chunkcount-integrity.md | 0 .../SEC_submanifest-chunks-unvalidated.md | 0 .../SEC_vault-nonce-exhaustion-cap.md | 0 .../SEC_vault-passphrase-verifier-gap.md | 0 .../TR_casservice-decomposition-pressure.md | 0 .../bad-code/TR_cryptoport-node-import.md | 0 .../bad-code/TR_dead-decompress-method.md | 0 .../TR_domain-imports-infrastructure.md | 0 .../TR_persistence-adapter-materialization.md | 0 .../bad-code/TR_platform-dependency-leaks.md | 2 +- .../bad-code/TR_schema-node-buffer-import.md | 0 .../bad-code/TR_vault-retry-jitter.md | 0 .../TUI_store-wizard-execution-gap.md | 0 .../bad-code/vault-tree-memory-loading.md | 0 .../backlog-pre-issues}/cool-ideas/.gitkeep | 0 .../cool-ideas/DX_open-cas-helper.md | 0 .../cool-ideas/DX_slug-tree-path-helper.md | 0 .../cool-ideas/OPS_release-doc-drift-guard.md | 0 .../cool-ideas/SEC_aes-gcm-aad-binding.md | 0 .../cool-ideas/SEC_fastcdc-dual-mask.md | 0 .../cool-ideas/SEC_manifest-integrity-hash.md | 0 .../cool-ideas/TR_adaptive-frame-sizing.md | 0 .../TR_browser-compression-adapter.md | 0 .../cool-ideas/TR_content-aware-chunking.md | 0 .../cool-ideas/TR_convergent-encryption.md | 0 .../TR_dedupe-efficiency-telemetry.md | 0 .../cool-ideas/TR_dual-encryption-modes.md | 0 .../cool-ideas/TR_manifest-diffing.md | 0 .../cool-ideas/TR_manifest-signing.md | 2 +- .../cool-ideas/TR_parallel-chunk-restore.md | 0 .../cool-ideas/TR_streaming-decryption.md | 2 +- .../cool-ideas/TR_structured-json-logging.md | 0 .../cool-ideas/TR_vault-privacy-mode.md | 2 +- .../cool-ideas/TUI_cli-adaptive-table.md | 0 .../cool-ideas/TUI_operation-feed-drawer.md | 0 .../TUI_os-keychain-auto-discovery.md | 0 .../cool-ideas/TUI_segmented-manifest-view.md | 0 .../cool-ideas/TUI_title-screen-stats.md | 0 .../cool-ideas/atomic-multi-store.md | 0 .../cool-ideas/merkle-tree-explorer-tui.md | 0 .../cool-ideas/selective-asset-replication.md | 0 .../cool-ideas/streaming-cli-stdin.md | 0 ...DEA-001_streaming-convergent-encryption.md | 0 .../POL-001_string-sludge-manifest-view.md | 0 .../POL-002_string-sludge-vault-report.md | 0 .../POL-003_string-sludge-encryption-card.md | 0 ...004_boundary-violation-history-timeline.md | 0 .../POL-005_raw-ansi-progress.md | 0 .../POL-006_magic-numbers-rhythm.md | 0 .../POL-007_view-state-leakage.md | 0 .../v6.0.0-polish/POL-008_manual-clipping.md | 0 .../POL-009_transition-shaders.md | 0 .../POL-010_heatmap-grid-math.md | 0 .../POL-011_wizard-string-geometry.md | 0 .../v6.0.0-polish/POL-012_asset-card-block.md | 0 .../POL-013_merkle-explorer-block.md | 0 .../POL-014_health-dashboard-block.md | 0 .../v6.0.0-polish/POL-015_wizard-block.md | 0 .../POL-016_operation-feed-block.md | 0 .../v6.0.0-polish/POL-017_heatmap-block.md | 0 .../v6.0.0/REL_audit-blocker-burn-down.md | 0 .../v6.0.0/REL_breaking-changes-doc.md | 0 .../v6.0.0/REL_docs-accuracy-audit.md | 0 .../v6.0.0/REL_migration-script.md | 0 .../v6.0.0/REL_signpost-rewrite.md | 0 .../v6.0.0/REL_version-bump.md | 0 .../v6.x-tui/TUI_accordion-detail-pane.md | 0 .../v6.x-tui/TUI_animated-transitions.md | 0 .../v6.x-tui/TUI_badge-components.md | 0 .../v6.x-tui/TUI_box-surface-migration.md | 0 .../v6.x-tui/TUI_framed-app-shell.md | 0 .../v6.x-tui/TUI_fullscreen-detail-view.md | 0 .../v6.x-tui/TUI_help-overlay.md | 0 .../v6.x-tui/TUI_layout-primitives.md | 0 .../v6.x-tui/TUI_merkle-dag-viewer.md | 0 .../TUI_orphaned-chunk-health-check.md | 0 .../v6.x-tui/TUI_pager-scrollable-content.md | 0 .../v6.x-tui/TUI_status-bar.md | 0 .../v6.x-tui/TUI_store-wizard.md | 0 .../v6.x-tui/TUI_toast-notifications.md | 0 .../goalposts-pre-issues}/README.md | 10 +- .../v6.0.1/release-truth-closeout.md | 6 +- .../v6.1.0/bounded-residency.md | 10 +- .../v6.2.0/operator-tui.md | 6 +- .../v6.3.0/agent-automation-parity.md | 4 +- .../v6.4.0/browser-edge-read-path.md | 2 +- .../v7.0.0/protocol-audit-response.md | 2 +- docs/audit/2026-05-04_ship-readiness.md | 2 +- .../bounded-residency.md | 50 ++++-- docs/legends/RL-relay.md | 4 +- docs/legends/TR-truth.md | 8 +- docs/method/backlog/README.md | 167 ++---------------- docs/method/legends/RL_relay.md | 4 +- docs/method/legends/TR_truth.md | 10 +- docs/method/process.md | 108 +++++------ .../enforce-store-backpressure.md | 2 +- .../add-read-blob-stream.md | 2 +- .../use-read-blob-stream-in-restore.md | 2 +- docs/templates/design-doc.md | 33 ++-- docs/templates/goalpost.md | 115 ------------ .../docs/casservice-decomposition.test.js | 4 +- test/unit/docs/markdown-links.test.js | 4 +- test/unit/docs/planning-surfaces.test.js | 90 ++++------ test/unit/docs/release-state.test.js | 2 +- 140 files changed, 650 insertions(+), 633 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/debt.yml create mode 100644 .github/ISSUE_TEMPLATE/goalpost.yml create mode 100644 .github/ISSUE_TEMPLATE/idea.yml create mode 100644 .github/ISSUE_TEMPLATE/slice.yml create mode 100644 .github/pull_request_template.md rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/BAD-CODE-001_casservice-god-object.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/DOC_api-plumbing-constructor-drift.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/DOC_examples-uint8array-drift.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/DOC_threat-model-scheme-drift.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/RL_agent-cli-module-size.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/RL_credential-resolution-duplication.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/SEC_chunk-constructor-property-leak.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/SEC_concurrency-upper-bound.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/SEC_encode-slug-control-chars.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/SEC_framebytes-upper-bound.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/SEC_inline-passphrase-flags.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/SEC_kdf-salt-min-length.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/SEC_recipient-timing-oracle.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/SEC_schema-hex-validation.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/SEC_scrypt-memory-budget.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/SEC_store-source-validation.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/SEC_submanifest-array-limit.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/SEC_submanifest-chunkcount-integrity.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/SEC_submanifest-chunks-unvalidated.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/SEC_vault-nonce-exhaustion-cap.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/SEC_vault-passphrase-verifier-gap.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/TR_casservice-decomposition-pressure.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/TR_cryptoport-node-import.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/TR_dead-decompress-method.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/TR_domain-imports-infrastructure.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/TR_persistence-adapter-materialization.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/TR_platform-dependency-leaks.md (96%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/TR_schema-node-buffer-import.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/TR_vault-retry-jitter.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/TUI_store-wizard-execution-gap.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/bad-code/vault-tree-memory-loading.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/.gitkeep (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/DX_open-cas-helper.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/DX_slug-tree-path-helper.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/OPS_release-doc-drift-guard.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/SEC_aes-gcm-aad-binding.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/SEC_fastcdc-dual-mask.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/SEC_manifest-integrity-hash.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/TR_adaptive-frame-sizing.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/TR_browser-compression-adapter.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/TR_content-aware-chunking.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/TR_convergent-encryption.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/TR_dedupe-efficiency-telemetry.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/TR_dual-encryption-modes.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/TR_manifest-diffing.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/TR_manifest-signing.md (96%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/TR_parallel-chunk-restore.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/TR_streaming-decryption.md (95%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/TR_structured-json-logging.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/TR_vault-privacy-mode.md (96%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/TUI_cli-adaptive-table.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/TUI_operation-feed-drawer.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/TUI_os-keychain-auto-discovery.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/TUI_segmented-manifest-view.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/TUI_title-screen-stats.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/atomic-multi-store.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/merkle-tree-explorer-tui.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/selective-asset-replication.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/cool-ideas/streaming-cli-stdin.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/ideas/IDEA-001_streaming-convergent-encryption.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.0.0-polish/POL-001_string-sludge-manifest-view.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.0.0-polish/POL-002_string-sludge-vault-report.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.0.0-polish/POL-003_string-sludge-encryption-card.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.0.0-polish/POL-004_boundary-violation-history-timeline.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.0.0-polish/POL-005_raw-ansi-progress.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.0.0-polish/POL-006_magic-numbers-rhythm.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.0.0-polish/POL-007_view-state-leakage.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.0.0-polish/POL-008_manual-clipping.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.0.0-polish/POL-009_transition-shaders.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.0.0-polish/POL-010_heatmap-grid-math.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.0.0-polish/POL-011_wizard-string-geometry.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.0.0-polish/POL-012_asset-card-block.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.0.0-polish/POL-013_merkle-explorer-block.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.0.0-polish/POL-014_health-dashboard-block.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.0.0-polish/POL-015_wizard-block.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.0.0-polish/POL-016_operation-feed-block.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.0.0-polish/POL-017_heatmap-block.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.0.0/REL_audit-blocker-burn-down.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.0.0/REL_breaking-changes-doc.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.0.0/REL_docs-accuracy-audit.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.0.0/REL_migration-script.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.0.0/REL_signpost-rewrite.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.0.0/REL_version-bump.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.x-tui/TUI_accordion-detail-pane.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.x-tui/TUI_animated-transitions.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.x-tui/TUI_badge-components.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.x-tui/TUI_box-surface-migration.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.x-tui/TUI_framed-app-shell.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.x-tui/TUI_fullscreen-detail-view.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.x-tui/TUI_help-overlay.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.x-tui/TUI_layout-primitives.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.x-tui/TUI_merkle-dag-viewer.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.x-tui/TUI_orphaned-chunk-health-check.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.x-tui/TUI_pager-scrollable-content.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.x-tui/TUI_status-bar.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.x-tui/TUI_store-wizard.md (100%) rename docs/{method/backlog => archive/backlog-pre-issues}/v6.x-tui/TUI_toast-notifications.md (100%) rename docs/{goalposts => archive/goalposts-pre-issues}/README.md (75%) rename docs/{goalposts => archive/goalposts-pre-issues}/v6.0.1/release-truth-closeout.md (94%) rename docs/{goalposts => archive/goalposts-pre-issues}/v6.1.0/bounded-residency.md (92%) rename docs/{goalposts => archive/goalposts-pre-issues}/v6.2.0/operator-tui.md (91%) rename docs/{goalposts => archive/goalposts-pre-issues}/v6.3.0/agent-automation-parity.md (95%) rename docs/{goalposts => archive/goalposts-pre-issues}/v6.4.0/browser-edge-read-path.md (97%) rename docs/{goalposts => archive/goalposts-pre-issues}/v7.0.0/protocol-audit-response.md (97%) delete mode 100644 docs/templates/goalpost.md diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml new file mode 100644 index 00000000..d4cb0aa8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -0,0 +1,49 @@ +name: Bug +description: Runtime, CLI, docs, release, or workflow behavior that is wrong. +title: "bug: " +labels: + - type:bug +body: + - type: textarea + id: current + attributes: + label: Current behavior + description: What happens now? + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + description: What should happen instead? + validations: + required: true + - type: textarea + id: evidence + attributes: + label: Evidence + description: Commands, files, logs, tests, screenshots, or examples. + value: | + - + validations: + required: true + - type: dropdown + id: area + attributes: + label: Area + options: + - storage + - vault + - tui + - agent + - docs + - security + - runtime + - release + validations: + required: true + - type: input + id: milestone + attributes: + label: Suggested milestone + placeholder: v6.1.0 diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..c20c6921 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: true +contact_links: + - name: Security vulnerability + url: mailto:james@flyingrobots.dev + about: Do not open public issues for suspected vulnerabilities. diff --git a/.github/ISSUE_TEMPLATE/debt.yml b/.github/ISSUE_TEMPLATE/debt.yml new file mode 100644 index 00000000..c8fd3893 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/debt.yml @@ -0,0 +1,40 @@ +name: Debt +description: Working behavior that needs cleanup, scale hardening, or clearer boundaries. +title: "debt: " +labels: + - type:debt +body: + - type: textarea + id: problem + attributes: + label: Problem + description: What works today but bothers us? + validations: + required: true + - type: textarea + id: risk + attributes: + label: Risk + description: What failure mode, maintenance cost, or operator cost does this create? + validations: + required: true + - type: textarea + id: proposed-shape + attributes: + label: Proposed shape + description: What direction should a future design explore? + validations: + required: true + - type: textarea + id: proof + attributes: + label: Proof needed + value: | + - + validations: + required: true + - type: input + id: design + attributes: + label: Design doc, if known + placeholder: docs/design/NNNN-slug/slug.md diff --git a/.github/ISSUE_TEMPLATE/goalpost.yml b/.github/ISSUE_TEMPLATE/goalpost.yml new file mode 100644 index 00000000..724680c5 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/goalpost.yml @@ -0,0 +1,85 @@ +name: Goalpost +description: Release-scale feature, invariant, or evidence packet. +title: "vX.Y.Z: " +labels: + - type:goalpost +body: + - type: markdown + attributes: + value: | + Goalposts are tracked in GitHub Issues. Design docs and witnesses may + live in the repo, but this issue owns work state. + - type: input + id: release + attributes: + label: Release milestone + description: Target version milestone, for example v6.1.0. + placeholder: v6.1.0 + validations: + required: true + - type: textarea + id: outcome + attributes: + label: Outcome + description: State the release-scale outcome this goalpost unlocks. + validations: + required: true + - type: textarea + id: current-truth + attributes: + label: Current truth + description: Cite repo-visible facts, commands, docs, tests, PRs, or issues. + validations: + required: true + - type: textarea + id: scope + attributes: + label: Scope + description: What is included? + value: | + - + validations: + required: true + - type: textarea + id: out-of-scope + attributes: + label: Out of scope + description: What is explicitly excluded? + value: | + - + validations: + required: true + - type: textarea + id: slices + attributes: + label: Slices + description: Link child issues or list turn-sized slices until child issues exist. + value: | + - [ ] Slice 1: + - [ ] Slice 2: + validations: + required: true + - type: input + id: design + attributes: + label: Design doc + description: Link the repo design doc, or write "needed". + placeholder: docs/design/NNNN-slug/slug.md + validations: + required: true + - type: textarea + id: proof + attributes: + label: Required proof + description: Tests, fixtures, witnesses, schemas, commands, or release evidence required before closeout. + value: | + - + validations: + required: true + - type: textarea + id: release-impact + attributes: + label: Release gate impact + description: Changelog, docs, package surface, migration posture, or release evidence impact. + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/idea.yml b/.github/ISSUE_TEMPLATE/idea.yml new file mode 100644 index 00000000..bd2c8204 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/idea.yml @@ -0,0 +1,27 @@ +name: Idea +description: Raw opportunity that is not yet committed work. +title: "idea: " +labels: + - type:idea +body: + - type: textarea + id: opportunity + attributes: + label: Opportunity + description: What could become valuable? + validations: + required: true + - type: textarea + id: why-not-now + attributes: + label: Why not now? + description: What blocks this from becoming tracked work? + validations: + required: true + - type: textarea + id: promotion + attributes: + label: Promotion criteria + description: What would make this ready for a goalpost, slice, bug, or debt issue? + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/slice.yml b/.github/ISSUE_TEMPLATE/slice.yml new file mode 100644 index 00000000..8aacf81e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/slice.yml @@ -0,0 +1,55 @@ +name: Slice +description: Turn-sized work under a goalpost. +title: ": " +labels: + - type:slice +body: + - type: input + id: parent + attributes: + label: Parent goalpost + description: Link the parent goalpost issue. + placeholder: "#123" + validations: + required: true + - type: textarea + id: work + attributes: + label: Smallest testable work + description: Define one focused unit of work. + validations: + required: true + - type: textarea + id: red-test + attributes: + label: RED test + description: Name the first failing test or witness this slice should create. + validations: + required: true + - type: textarea + id: expected-proof + attributes: + label: Expected proof + description: What proves this slice is done? + value: | + - + validations: + required: true + - type: textarea + id: validation + attributes: + label: Validation command + value: | + ```bash + npx eslint . + npm test + ``` + validations: + required: true + - type: textarea + id: closeout + attributes: + label: Closeout condition + description: What must be true before this issue closes? + validations: + required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..0e3d4803 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,21 @@ +## Linked Issue + +- Closes # + +## Design / Proof + +- Design doc: +- Witness or focused proof: + +## Validation + +```bash +npx eslint . +npm test +``` + +## Release Impact + +- [ ] Changelog updated, if release behavior changed. +- [ ] Public docs updated, if user-facing behavior changed. +- [ ] Issue labels/milestone reflect final disposition. diff --git a/BEARING.md b/BEARING.md index 0c2ef329..a2cf688c 100644 --- a/BEARING.md +++ b/BEARING.md @@ -111,20 +111,32 @@ These were the active tensions from the previous bearing. All resolved. ## Next Horizon -With v6.0.0 shipped, these are candidate directions — not commitments. +With v6.0.0 shipped, active work is tracked in GitHub Issues and Milestones. +Repo docs hold design and evidence records, not the active queue. -- **TUI modernization.** Keep dashboard and wizard actions sharing executable +The next selected design record is +[0045-v6-1-bounded-residency](./docs/design/0045-v6-1-bounded-residency/bounded-residency.md). +It targets large-vault and large-blob residency hardening for +[#38](https://github.com/git-stunts/git-cas/issues/38) in the +[`v6.1.0` milestone](https://github.com/git-stunts/git-cas/milestone/2). + +The broader horizon remains: + +- **TUI modernization.** Track + [#39](https://github.com/git-stunts/git-cas/issues/39). Keep dashboard and + wizard actions sharing executable option-building truth while improving operator ergonomics around long-lived store, restore, vault, and diagnostics workflows. -- **Browser/edge persistence adapter.** A `FetchPersistenceAdapter` or +- **Browser/edge persistence adapter.** Track + [#41](https://github.com/git-stunts/git-cas/issues/41). A + `FetchPersistenceAdapter` or `IsomorphicGitAdapter` could enable browser-side restore (read path) without the `git` CLI. Write path is harder — it needs ref updates and tree creation. -- **Formal crypto audit.** Engage a third-party security firm to review the +- **Formal crypto audit.** Track + [#42](https://github.com/git-stunts/git-cas/issues/42). Engage a third-party + security firm to review the framing protocol, AAD binding, convergent key derivation, KDF policy enforcement, and key derivation paths. -- **Performance optimization.** Profiling large-asset store/restore paths, - particularly CDC chunking throughput, convergent encryption overhead, and - PrefetchWindow tuning. The benchmarks baseline exists in `ADVANCED_GUIDE.md`. - **Adaptive frame sizing.** Investigate dynamic `frameBytes` selection based on payload characteristics to reduce per-frame overhead for small assets while maintaining streaming properties for large ones. diff --git a/CHANGELOG.md b/CHANGELOG.md index e6408008..89e9be8b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added + +- **GitHub tracker templates** — added issue forms for goalposts, slices, bugs, + debt, and ideas, plus a pull request template that links issues, design proof, + validation, and release impact. + +### Changed + +- **GitHub Issues as canonical tracker** — release milestones, goalposts, slices, + and follow-on work now live in GitHub Issues and Milestones. Repo Markdown + carries design docs, witnesses, release history, public docs, and archived + planning source material, but does not own the active queue. + ## [6.0.1] — 2026-05-09 ### Added diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0389b2fe..f85ff7bf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -90,9 +90,15 @@ The working source of truth is: - [WORKFLOW.md](./WORKFLOW.md) - [docs/method/process.md](./docs/method/process.md) -Fresh planning work now lives in: +Fresh tracking now lives in GitHub Issues and Milestones. If work is actionable, +it must be an issue. Repo Markdown may explain design, evidence, release notes, +or historical context, but it does not own active work state. -- backlog lanes under [`docs/method/backlog/`](./docs/method/backlog/README.md) +Fresh planning records now live in: + +- GitHub milestones for versioned releases +- GitHub `type:goalpost` issues for release-scale outcomes +- GitHub `type:slice` issues or sub-issues for turn-sized work - legends under [`docs/method/legends/`](./docs/method/legends/README.md) - numbered cycle directories under [`docs/design/`](./docs/design/README.md) - retros under `docs/method/retro//` @@ -110,9 +116,9 @@ Every cycle must name: - non-goals Fresh work should be grounded in human or agent value, not backend vanity. If -the playback question is unclear, the work belongs in a METHOD backlog lane, -usually [`docs/method/backlog/inbox/`](./docs/method/backlog/README.md), not in -an active cycle doc. +the playback question is unclear, open an `idea` issue or leave the work +untracked until it can be stated clearly. Do not add new repo-local backlog +cards. Before opening a doc-heavy pull request, run the short maintainer pass in [docs/DOCS_CHECKLIST.md](./docs/DOCS_CHECKLIST.md). @@ -127,6 +133,7 @@ that checklist pass. New planning work uses: +- GitHub Issues and Milestones - [`docs/method/backlog/`](./docs/method/backlog/README.md) - [`docs/method/legends/`](./docs/method/legends/README.md) - [`docs/method/retro/`](./docs/method/retro/README.md) @@ -135,8 +142,11 @@ New planning work uses: - [`docs/invariants/`](./docs/invariants/) - [`test/cycles/`](./test/cycles/) -Legacy compatibility planning surfaces remain in [`docs/BACKLOG/`](./docs/BACKLOG/README.md) -and [`docs/legends/`](./docs/legends/README.md), but fresh planning should not +The retired repo-local backlog remains as a signpost in +[`docs/method/backlog/`](./docs/method/backlog/README.md), and historical cards +live under `docs/archive/`. Legacy compatibility planning surfaces remain in +[`docs/BACKLOG/`](./docs/BACKLOG/README.md) and +[`docs/legends/`](./docs/legends/README.md), but fresh tracking should not start there. ## Build Order @@ -156,13 +166,13 @@ Do not treat implementation details as the primary unit of correctness. Each cycle should follow the same explicit loop: -1. design docs first -2. tests as spec second -3. implementation third -4. human and agent playback witness -5. pull request and merge -6. retrospective after merge -7. update `docs/method/backlog/` with debt, follow-on work, and cool ideas +1. open or select the canonical GitHub Issue +2. write or revise design docs +3. tests as spec +4. implementation +5. human and agent playback witness +6. pull request and merge +7. create GitHub follow-up issues for debt, follow-on work, and ideas 8. update the root [CHANGELOG.md](./CHANGELOG.md) 9. rewrite the root README when reality changed materially @@ -323,6 +333,7 @@ Before making non-trivial changes, read: - [docs/method/process.md](./docs/method/process.md) - [STATUS.md](./STATUS.md) - [ROADMAP.md](./ROADMAP.md) +- GitHub Issues and Milestones for current work state - [docs/method/legends/README.md](./docs/method/legends/README.md) - [docs/invariants/README.md](./docs/invariants/README.md) - [docs/method/backlog/README.md](./docs/method/backlog/README.md) diff --git a/GUIDE.md b/GUIDE.md index 9199f9d9..cca293d4 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -37,7 +37,7 @@ Machine-facing agent CLI for structured CI/CD or agentic workflows. ### 4. Contributing -- Read `METHOD.md` and `BEARING.md` for project process. +- Read `WORKFLOW.md`, `docs/method/process.md`, and `BEARING.md` for project process. - See [Architecture](#architecture) for orientation. --- diff --git a/METHOD.md b/METHOD.md index bf5b06b8..e8fbddb7 100644 --- a/METHOD.md +++ b/METHOD.md @@ -1,58 +1,15 @@ # METHOD -The `git-cas` work doctrine: A backlog, a loop, and honest bookkeeping. +The canonical METHOD now lives in +[docs/method/process.md](./docs/method/process.md). -## Principles +Short version: -- **The agent and the human sit at the same table.** Both matter. Both are named in every design. -- **Git is the substrate, not the product.** We use Git's object database for its engineering properties, not as a user-facing constraint. -- **The filesystem is the coordination layer.** For meta-work (this repo), directories are priorities; filenames are identities; moves are decisions. -- **Tests are the executable spec.** Design names the problem; tests prove the answer. -- **Zero tolerance for failing tests.** Pre-existing failures are not acceptable on any supported runtime. +- GitHub Issues and Milestones are the source of truth for actionable work. +- Repo Markdown is for design, evidence, public docs, release history, and + historical context. +- If work is only in Markdown, it is not tracked work. +- Design cycles live under [docs/design/](./docs/design/README.md). +- Release history lives in [CHANGELOG.md](./CHANGELOG.md). -## Structure - -| Signpost | Role | -| :--- | :--- | -| **`README.md`** | Public front door and project identity. | -| **`GUIDE.md`** | Orientation and productive-fast path. | -| **`BEARING.md`** | Current direction and active tensions. | -| **`VISION.md`** | Core tenets and the CAS mission. | -| **`ARCHITECTURE.md`** | Authoritative system map and layer model. | -| **`AGENTS.md`** | Context recovery protocol for AI and humans. | -| **`METHOD.md`** | Repo work doctrine (this document). | - -## Backlog Lanes - -| Lane | Purpose | -| :--- | :--- | -| **`asap/`** | Imminent work; pull into the next cycle. | -| **`up-next/`** | Queued after `asap/`. | -| **`cool-ideas/`** | Uncommitted experiments. | -| **`bad-code/`** | Technical debt that must be addressed. | -| **`inbox/`** | Raw ideas. | - -## The Cycle Loop - -```mermaid -stateDiagram-v2 - direction LR - [*] --> Pull: asap/ - Pull --> Branch: cycle/ - Branch --> Red: failing tests - Red --> Green: passing tests - Green --> Retro: findings/debt - Retro --> Ship: PR to main - Ship --> [*] -``` - -1. **Pull**: Move an item from `asap/` to `docs/design/`. -2. **Branch**: Create `cycle/`. -3. **Red**: Write failing tests based on the design's playback questions. -4. **Green**: Implement the solution until tests pass. -5. **Retro**: Document findings and follow-on debt in the cycle doc. -6. **Ship**: Open a PR to `main`. Update `BEARING.md` and `CHANGELOG.md` after merge. - -## Naming Convention -Backlog and cycle files follow: `_.md` -Example: `TR_streaming-encrypted-restore.md` +Use [WORKFLOW.md](./WORKFLOW.md) as the root signpost. diff --git a/ROADMAP.md b/ROADMAP.md index 1a13fbed..2d11e84f 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,96 +1,71 @@ # ROADMAP -`ROADMAP.md` is the release-line index for upcoming `git-cas` work. +`ROADMAP.md` is a signpost into the GitHub tracker. -Active implementation still follows the METHOD loop in -[docs/method/process.md](./docs/method/process.md): goalposts are planned here, -pulled into numbered design cycles, proven with tests and witnesses, and shipped -through one pull request per goalpost. +GitHub Issues and Milestones are the source of truth for work that needs to get +done. This file does not track status, priority, blockers, or completion. It +only explains the release-tracking model and names the intended milestone +sequence so humans and agents know where to look. -## Reading Order +## Canonical Tracker -1. Start here for release sequencing. -2. Open the release goalpost docs under [docs/goalposts/](./docs/goalposts/). -3. Use [docs/design/](./docs/design/README.md) for cycle-level contracts and - proof plans. -4. Use [docs/method/backlog/](./docs/method/backlog/README.md) for uncommitted - debt and ideas that have not yet become release goalposts. +Active work lives in GitHub: -## Current State +- Milestones own versioned releases: `v6.0.1`, `v6.1.0`, `v6.2.0`, and so on. +- `type:goalpost` issues own release-scale outcomes. +- `type:slice` issues or sub-issues own turn-sized proof work. +- Issue labels and milestone state own active, blocked, review, carried-forward, + and done status. -- **Last tagged release:** `v6.0.0` (`2026-05-09`) -- **Current branch:** `main` -- **Current release line:** `v6.x` -- **Supported runtimes:** Node.js 22.x, Bun, Deno -- **Publication surfaces:** npm and GitHub Releases are active; JSR publication - remains deferred until the upstream dry-run blocker is healthy. -- **Planning posture:** `asap/` and `up-next/` are empty. The next product work - is selected from active debt, release truth, and v6.x operator goals. +Repo docs are supporting records: -## Release Train +- [docs/design/](./docs/design/README.md) holds design contracts and proof plans. +- Design docs link back to the canonical GitHub issue. +- [CHANGELOG.md](./CHANGELOG.md) records shipped release history. +- Archived backlog and goalpost files are historical source material only. -| Release | Theme | Required goalposts | Status | -| --- | --- | --- | --- | -| `v6.0.1` | Patch closeout and planning truth | [Release Truth Closeout](./docs/goalposts/v6.0.1/release-truth-closeout.md) | scaffolded | -| `v6.1.0` | Bounded residency and scale hardening | [Bounded Residency](./docs/goalposts/v6.1.0/bounded-residency.md) | scaffolded | -| `v6.2.0` | Operator TUI consolidation | [Operator TUI](./docs/goalposts/v6.2.0/operator-tui.md) | planned | -| `v6.3.0` | Agent automation parity | [Agent Automation Parity](./docs/goalposts/v6.3.0/agent-automation-parity.md) | planned | -| `v6.4.0` | Browser and edge read-path exploration | [Browser/Edge Read Path](./docs/goalposts/v6.4.0/browser-edge-read-path.md) | planned | -| `v7.0.0` | Protocol break only if audit requires it | [Protocol Audit Response](./docs/goalposts/v7.0.0/protocol-audit-response.md) | provisional | +## Current Intended Release Train -## Next Release: `v6.1.0` +The milestones below should exist in GitHub. If this table and GitHub disagree, +GitHub wins and this file should be corrected. -`v6.1.0` should make the core bounded under large vault and large blob -conditions. The target is not a new user-visible feature; it is a stronger -residency contract for the storage surfaces that already exist. +| Milestone | Theme | Tracker | +| --- | --- | --- | +| [`v6.0.1`](https://github.com/git-stunts/git-cas/milestone/1) | Patch closeout and planning truth | [#37](https://github.com/git-stunts/git-cas/issues/37) | +| [`v6.1.0`](https://github.com/git-stunts/git-cas/milestone/2) | Bounded residency and scale hardening | [#38](https://github.com/git-stunts/git-cas/issues/38) | +| [`v6.2.0`](https://github.com/git-stunts/git-cas/milestone/3) | Operator TUI consolidation | [#39](https://github.com/git-stunts/git-cas/issues/39) | +| [`v6.3.0`](https://github.com/git-stunts/git-cas/milestone/4) | Agent automation parity | [#40](https://github.com/git-stunts/git-cas/issues/40) | +| [`v6.4.0`](https://github.com/git-stunts/git-cas/milestone/5) | Browser and edge read-path exploration | [#41](https://github.com/git-stunts/git-cas/issues/41) | +| [`v7.0.0`](https://github.com/git-stunts/git-cas/milestone/6) | Protocol break only if audit requires it | [#42](https://github.com/git-stunts/git-cas/issues/42), only when justified | -Goalpost: +## Next Release Design -- [Bounded Residency](./docs/goalposts/v6.1.0/bounded-residency.md) - -Design: +The next selected design record is: - [0045-v6-1-bounded-residency](./docs/design/0045-v6-1-bounded-residency/bounded-residency.md) -Required proof: - -- large-vault slug resolution does not materialize the entire vault tree -- vault listing uses the streaming tree path when the adapter provides it -- metadata-sized blob reads remain guarded -- domain data reads prefer `readBlobStream()` for unbounded payloads -- docs and release evidence describe the bounded-residency contract honestly - -## Goalpost Rules - -- A goalpost is a release-scale feature or invariant. -- Goalposts are subdivided into turn-sized slices. -- One pull request should carry one goalpost. -- Each slice needs an expected proof: test, fixture, witness, schema, runtime - behavior, docs update, or issue update. -- Goalposts do not replace design cycles. A design cycle is how a goalpost - becomes implementable work. -- Goalposts may start with `not opened yet` issue fields. They should be linked - to GitHub issues before implementation begins. - -## Templates +Its GitHub goalpost issue, +[#38](https://github.com/git-stunts/git-cas/issues/38), is the canonical +tracker. The design doc is the durable contract; the issue is the work item. -- [Goalpost template](./docs/templates/goalpost.md) -- [Design doc template](./docs/templates/design-doc.md) +Initial `v6.1.0` slice issues: -## Release Gates +- [#43 Targeted vault lookup](https://github.com/git-stunts/git-cas/issues/43) +- [#44 Streaming vault list](https://github.com/git-stunts/git-cas/issues/44) +- [#45 Blob read residency contract](https://github.com/git-stunts/git-cas/issues/45) +- [#46 Docs and release evidence](https://github.com/git-stunts/git-cas/issues/46) -Every release still follows [docs/method/release.md](./docs/method/release.md). -The default local release evidence command is: +## Rule -```bash -npm run release:verify -- --skip-jsr -``` +If it is actionable work, it must be a GitHub Issue. If it only appears in a +Markdown file, it is not tracked work. -Use `--skip-jsr` only while the documented upstream JSR/Deno blocker remains -outside this repo. When the dry-run is healthy, full release verification should -include JSR again. +Markdown may still preserve: -## Not A Roadmap Item +- design decisions +- evidence and witness records +- release notes +- public documentation +- archived planning source material -`v7.0.0` is not a general cleanup bucket. It becomes real only if protocol, -storage, migration, or public API evidence requires a breaking change. +Markdown must not be the active queue. diff --git a/STATUS.md b/STATUS.md index dc3ab1b0..0a98a114 100644 --- a/STATUS.md +++ b/STATUS.md @@ -6,7 +6,7 @@ **Playback truth:** `main` **Runtimes:** Node.js 22.x, Bun, Deno **Current planning method:** [WORKFLOW.md](./WORKFLOW.md) -**Live backlog:** [docs/method/backlog/README.md](./docs/method/backlog/README.md) +**Live tracker:** [GitHub Issues](https://github.com/git-stunts/git-cas/issues) and [Milestones](https://github.com/git-stunts/git-cas/milestones) --- @@ -73,15 +73,22 @@ - Web Crypto whole-object decrypt paths are now explicitly bounded by `maxDecryptionBufferSize` instead of collecting ciphertext without a guard. `framed` remains the actual cross-runtime streaming-encrypted mode. -- Fresh work is now organized through METHOD backlog lanes and numbered cycle - directories. +- Fresh work is now tracked through GitHub Issues and Milestones. Repo Markdown + carries design docs, witnesses, public docs, release history, and archived + planning source material. - TUI modernization is queued for the v6.x line after v6.0.0, not as a v6.0.0 tag blocker. ## Active Queue Snapshot -- [Vault Tree Memory Loading](./docs/method/backlog/bad-code/vault-tree-memory-loading.md) -- [TR — GitPersistenceAdapter Full Materialization](./docs/method/backlog/bad-code/TR_persistence-adapter-materialization.md) +- GitHub Issues are canonical. If this section and GitHub disagree, GitHub + wins and this section should be corrected. +- Current selected release goalpost: + [#38 v6.1.0: Bounded Residency](https://github.com/git-stunts/git-cas/issues/38) + under the + [`v6.1.0` milestone](https://github.com/git-stunts/git-cas/milestone/2). +- The next local design record is + [0045-v6-1-bounded-residency](./docs/design/0045-v6-1-bounded-residency/bounded-residency.md). ## Read Next diff --git a/WORKFLOW.md b/WORKFLOW.md index f4cede70..d1fd72b8 100644 --- a/WORKFLOW.md +++ b/WORKFLOW.md @@ -5,11 +5,11 @@ This file is the root signpost for how `git-cas` plans and ships work. Fresh work now follows the METHOD in [docs/method/process.md](./docs/method/process.md). -Current planning truth lives in: +Work tracking truth lives in GitHub Issues and Milestones. + +Repo planning and evidence docs live in: - [ROADMAP.md](./ROADMAP.md) -- [docs/goalposts/](./docs/goalposts/README.md) -- [docs/method/backlog/](./docs/method/backlog/README.md) - [docs/method/legends/](./docs/method/legends/README.md) - [docs/design/](./docs/design/README.md) - [docs/method/release.md](./docs/method/release.md) @@ -23,3 +23,6 @@ Legacy compatibility surfaces remain for historical links and older cycle docs: If a METHOD surface and a legacy compatibility surface disagree, the METHOD surface wins and the legacy surface should be corrected or retired. + +If a repo doc and GitHub Issues disagree about actionable work, GitHub Issues +win. diff --git a/docs/BACKLOG/README.md b/docs/BACKLOG/README.md index f71fabe4..4d112c46 100644 --- a/docs/BACKLOG/README.md +++ b/docs/BACKLOG/README.md @@ -2,16 +2,19 @@ This directory is retained so pre-METHOD links keep working. -Fresh backlog truth now lives in [docs/method/backlog/](../method/backlog/README.md). +Fresh work-tracking truth now lives in GitHub Issues and Milestones. If work is +actionable, it must be represented by a GitHub Issue. -Use that directory for: +Use GitHub for: - inbox capture - lane priority - current pull decisions - new backlog items -Historical planning cards still live in -[docs/archive/BACKLOG/](../archive/BACKLOG/README.md). +Repo-local backlog signposts now live in +[docs/method/backlog/](../method/backlog/README.md). Historical planning cards +live in [docs/archive/BACKLOG/](../archive/BACKLOG/README.md) and +[docs/archive/backlog-pre-issues/](../archive/backlog-pre-issues/). This legacy directory intentionally no longer carries live backlog cards. diff --git a/docs/DOCS_CHECKLIST.md b/docs/DOCS_CHECKLIST.md index 362a4b87..4ee529ba 100644 --- a/docs/DOCS_CHECKLIST.md +++ b/docs/DOCS_CHECKLIST.md @@ -21,7 +21,7 @@ truth and discoverability failures that keep surfacing late in review. Check that adjacent top-level docs can find each other where a maintainer or reviewer would reasonably expect a link. - Planning index hygiene: - If a roadmap entry, goalpost, backlog card, cycle doc, or legend state + If a roadmap entry, GitHub issue, milestone, cycle doc, or legend state changed, update the affected indexes in the same change. - Empty-state wording: If an index or legend now has an empty list, use the documented house style @@ -43,8 +43,7 @@ changes: - [docs/API.md](./API.md) - [docs/THREAT_MODEL.md](./THREAT_MODEL.md) - [ADVANCED_GUIDE.md](../ADVANCED_GUIDE.md) -- planning indexes under [`ROADMAP.md`](../ROADMAP.md), - [`docs/goalposts/`](./goalposts/README.md), +- planning signposts under [`ROADMAP.md`](../ROADMAP.md), [`docs/method/backlog/`](./method/backlog/README.md), [`docs/design/`](./design/README.md), [`docs/archive/BACKLOG/`](./archive/BACKLOG/README.md), and @@ -65,7 +64,7 @@ At minimum, confirm the following before review: - summary docs link canonical truth instead of becoming a second narrative - security-sensitive docs route to [SECURITY.md](../SECURITY.md) and [docs/THREAT_MODEL.md](./THREAT_MODEL.md) where those boundaries matter -- planning indexes and legends point to the current roadmap, goalpost, backlog, +- planning signposts and legends point to the current GitHub tracker, roadmap, design, retro, and archive surfaces they describe - no touched doc loses an important discoverability link that existed before @@ -74,22 +73,21 @@ At minimum, confirm the following before review: Run this extra pass whenever a branch changes: - `ROADMAP.md` -- `docs/goalposts/README.md` - `docs/method/backlog/README.md` - `docs/design/README.md` - `docs/method/legends/README.md` - `docs/archive/BACKLOG/README.md` - a legend's current-cycle summary -- a backlog card's lifecycle state +- a GitHub issue or milestone's lifecycle state - a legacy planning compatibility signpost Confirm all of the following before review: -- live backlog entries are still pending, in cycle, or carrying unresolved +- live GitHub issues are still pending, in cycle, or carrying unresolved follow-on work - active cycle directories are represented in `docs/design/` - archived backlog history reflects moved or retired backlog cards -- legend summaries agree with the current backlog and design surfaces +- legend summaries agree with the current GitHub tracker and design surfaces - legacy compatibility surfaces still point at the active METHOD truth - empty-state wording does not introduce a new house style accidentally @@ -105,8 +103,7 @@ This checklist is most useful when a change touches files like: - [docs/API.md](./API.md) - [docs/THREAT_MODEL.md](./THREAT_MODEL.md) - [ADVANCED_GUIDE.md](../ADVANCED_GUIDE.md) -- planning indexes under [`ROADMAP.md`](../ROADMAP.md), - [`docs/goalposts/`](./goalposts/README.md), +- planning signposts under [`ROADMAP.md`](../ROADMAP.md), [`docs/method/backlog/`](./method/backlog/README.md), [`docs/design/`](./design/README.md), [`docs/archive/BACKLOG/`](./archive/BACKLOG/README.md), and @@ -124,6 +121,6 @@ Before a doc-heavy branch is ready for review: - the changed docs point at the right canonical truth - the pre-PR doc cross-link audit passed for the touched surfaces - public and internal boundaries are not blurred -- planning indexes match the release, goalpost, backlog, and design files they - describe +- planning signposts match the GitHub milestones, GitHub issues, release docs, + and design files they describe - empty-state wording does not introduce a new style accidentally diff --git a/docs/MARKDOWN_SURFACE.md b/docs/MARKDOWN_SURFACE.md index 3119659f..f8411589 100644 --- a/docs/MARKDOWN_SURFACE.md +++ b/docs/MARKDOWN_SURFACE.md @@ -72,20 +72,18 @@ local-only surfaces. - [docs/method/process.md](./method/process.md): `KEEP` — canonical planning and delivery process for fresh work. -- [docs/goalposts/README.md](./goalposts/README.md): `KEEP` — release - goalpost index between `ROADMAP.md` and numbered design cycles. -- [docs/templates/goalpost.md](./templates/goalpost.md): `KEEP` — reusable - release-goalpost skeleton for fresh planning. - [docs/templates/design-doc.md](./templates/design-doc.md): `KEEP` — reusable METHOD cycle design skeleton for fresh planning. +- [.github/ISSUE_TEMPLATE/goalpost.yml](../.github/ISSUE_TEMPLATE/goalpost.yml): + `KEEP` — reusable release-goalpost issue form for fresh planning. +- [.github/ISSUE_TEMPLATE/slice.yml](../.github/ISSUE_TEMPLATE/slice.yml): + `KEEP` — reusable slice issue form for turn-sized proof work. - [docs/method/release.md](./method/release.md): `KEEP` — canonical release process for fresh work. - [docs/method/backlog/README.md](./method/backlog/README.md): `KEEP` — - canonical live backlog index. + retired backlog signpost that points active work to GitHub Issues. - [docs/design/0044-casservice-decomposition-plan](./design/0044-casservice-decomposition-plan/casservice-decomposition-plan.md): `KEEP` — landed design record for the decomposition trajectory. -- [docs/method/backlog/bad-code/TR_platform-dependency-leaks.md](./method/backlog/bad-code/TR_platform-dependency-leaks.md): - `KEEP` — active debt backlog work item. - [docs/method/legends/README.md](./method/legends/README.md): `KEEP` — canonical legend index for fresh work. - [docs/method/legends/RL_relay.md](./method/legends/RL_relay.md): `KEEP` — @@ -241,6 +239,6 @@ If the repo wants to act on this audit, the highest-value next changes are: 2. decide whether [CLAUDE.md](../CLAUDE.md) should leave tracked root entirely 3. collapse [STATUS.md](../STATUS.md) into other canonical surfaces and remove the duplicate snapshot doc -4. keep [ROADMAP.md](../ROADMAP.md), [docs/goalposts/](./goalposts/README.md), - and [docs/design/](./design/README.md) synchronized as the release planning - stack evolves +4. keep [ROADMAP.md](../ROADMAP.md), GitHub milestones/issues, and + [docs/design/](./design/README.md) synchronized as the release planning stack + evolves diff --git a/docs/archive/README.md b/docs/archive/README.md index 8913d95c..2b105507 100644 --- a/docs/archive/README.md +++ b/docs/archive/README.md @@ -3,10 +3,10 @@ This directory holds historical planning artifacts that are no longer part of the active working surface. -Current planning truth now lives in: +Current work-tracking truth lives in GitHub Issues and Milestones. Current repo +planning and evidence truth lives in: - [WORKFLOW.md](../../WORKFLOW.md) -- [docs/method/backlog](../method/backlog/README.md) - [docs/method/legends](../method/legends/README.md) - [docs/design](../design/README.md) - [docs/invariants](../invariants/README.md) @@ -14,4 +14,6 @@ Current planning truth now lives in: Archive subdirectories: - [BACKLOG](./BACKLOG/README.md) +- [backlog-pre-issues](./backlog-pre-issues/) - [design](./design/README.md) +- [goalposts-pre-issues](./goalposts-pre-issues/README.md) diff --git a/docs/method/backlog/bad-code/BAD-CODE-001_casservice-god-object.md b/docs/archive/backlog-pre-issues/bad-code/BAD-CODE-001_casservice-god-object.md similarity index 100% rename from docs/method/backlog/bad-code/BAD-CODE-001_casservice-god-object.md rename to docs/archive/backlog-pre-issues/bad-code/BAD-CODE-001_casservice-god-object.md diff --git a/docs/method/backlog/bad-code/DOC_api-plumbing-constructor-drift.md b/docs/archive/backlog-pre-issues/bad-code/DOC_api-plumbing-constructor-drift.md similarity index 100% rename from docs/method/backlog/bad-code/DOC_api-plumbing-constructor-drift.md rename to docs/archive/backlog-pre-issues/bad-code/DOC_api-plumbing-constructor-drift.md diff --git a/docs/method/backlog/bad-code/DOC_examples-uint8array-drift.md b/docs/archive/backlog-pre-issues/bad-code/DOC_examples-uint8array-drift.md similarity index 100% rename from docs/method/backlog/bad-code/DOC_examples-uint8array-drift.md rename to docs/archive/backlog-pre-issues/bad-code/DOC_examples-uint8array-drift.md diff --git a/docs/method/backlog/bad-code/DOC_threat-model-scheme-drift.md b/docs/archive/backlog-pre-issues/bad-code/DOC_threat-model-scheme-drift.md similarity index 100% rename from docs/method/backlog/bad-code/DOC_threat-model-scheme-drift.md rename to docs/archive/backlog-pre-issues/bad-code/DOC_threat-model-scheme-drift.md diff --git a/docs/method/backlog/bad-code/RL_agent-cli-module-size.md b/docs/archive/backlog-pre-issues/bad-code/RL_agent-cli-module-size.md similarity index 100% rename from docs/method/backlog/bad-code/RL_agent-cli-module-size.md rename to docs/archive/backlog-pre-issues/bad-code/RL_agent-cli-module-size.md diff --git a/docs/method/backlog/bad-code/RL_credential-resolution-duplication.md b/docs/archive/backlog-pre-issues/bad-code/RL_credential-resolution-duplication.md similarity index 100% rename from docs/method/backlog/bad-code/RL_credential-resolution-duplication.md rename to docs/archive/backlog-pre-issues/bad-code/RL_credential-resolution-duplication.md diff --git a/docs/method/backlog/bad-code/SEC_chunk-constructor-property-leak.md b/docs/archive/backlog-pre-issues/bad-code/SEC_chunk-constructor-property-leak.md similarity index 100% rename from docs/method/backlog/bad-code/SEC_chunk-constructor-property-leak.md rename to docs/archive/backlog-pre-issues/bad-code/SEC_chunk-constructor-property-leak.md diff --git a/docs/method/backlog/bad-code/SEC_concurrency-upper-bound.md b/docs/archive/backlog-pre-issues/bad-code/SEC_concurrency-upper-bound.md similarity index 100% rename from docs/method/backlog/bad-code/SEC_concurrency-upper-bound.md rename to docs/archive/backlog-pre-issues/bad-code/SEC_concurrency-upper-bound.md diff --git a/docs/method/backlog/bad-code/SEC_encode-slug-control-chars.md b/docs/archive/backlog-pre-issues/bad-code/SEC_encode-slug-control-chars.md similarity index 100% rename from docs/method/backlog/bad-code/SEC_encode-slug-control-chars.md rename to docs/archive/backlog-pre-issues/bad-code/SEC_encode-slug-control-chars.md diff --git a/docs/method/backlog/bad-code/SEC_framebytes-upper-bound.md b/docs/archive/backlog-pre-issues/bad-code/SEC_framebytes-upper-bound.md similarity index 100% rename from docs/method/backlog/bad-code/SEC_framebytes-upper-bound.md rename to docs/archive/backlog-pre-issues/bad-code/SEC_framebytes-upper-bound.md diff --git a/docs/method/backlog/bad-code/SEC_inline-passphrase-flags.md b/docs/archive/backlog-pre-issues/bad-code/SEC_inline-passphrase-flags.md similarity index 100% rename from docs/method/backlog/bad-code/SEC_inline-passphrase-flags.md rename to docs/archive/backlog-pre-issues/bad-code/SEC_inline-passphrase-flags.md diff --git a/docs/method/backlog/bad-code/SEC_kdf-salt-min-length.md b/docs/archive/backlog-pre-issues/bad-code/SEC_kdf-salt-min-length.md similarity index 100% rename from docs/method/backlog/bad-code/SEC_kdf-salt-min-length.md rename to docs/archive/backlog-pre-issues/bad-code/SEC_kdf-salt-min-length.md diff --git a/docs/method/backlog/bad-code/SEC_recipient-timing-oracle.md b/docs/archive/backlog-pre-issues/bad-code/SEC_recipient-timing-oracle.md similarity index 100% rename from docs/method/backlog/bad-code/SEC_recipient-timing-oracle.md rename to docs/archive/backlog-pre-issues/bad-code/SEC_recipient-timing-oracle.md diff --git a/docs/method/backlog/bad-code/SEC_schema-hex-validation.md b/docs/archive/backlog-pre-issues/bad-code/SEC_schema-hex-validation.md similarity index 100% rename from docs/method/backlog/bad-code/SEC_schema-hex-validation.md rename to docs/archive/backlog-pre-issues/bad-code/SEC_schema-hex-validation.md diff --git a/docs/method/backlog/bad-code/SEC_scrypt-memory-budget.md b/docs/archive/backlog-pre-issues/bad-code/SEC_scrypt-memory-budget.md similarity index 100% rename from docs/method/backlog/bad-code/SEC_scrypt-memory-budget.md rename to docs/archive/backlog-pre-issues/bad-code/SEC_scrypt-memory-budget.md diff --git a/docs/method/backlog/bad-code/SEC_store-source-validation.md b/docs/archive/backlog-pre-issues/bad-code/SEC_store-source-validation.md similarity index 100% rename from docs/method/backlog/bad-code/SEC_store-source-validation.md rename to docs/archive/backlog-pre-issues/bad-code/SEC_store-source-validation.md diff --git a/docs/method/backlog/bad-code/SEC_submanifest-array-limit.md b/docs/archive/backlog-pre-issues/bad-code/SEC_submanifest-array-limit.md similarity index 100% rename from docs/method/backlog/bad-code/SEC_submanifest-array-limit.md rename to docs/archive/backlog-pre-issues/bad-code/SEC_submanifest-array-limit.md diff --git a/docs/method/backlog/bad-code/SEC_submanifest-chunkcount-integrity.md b/docs/archive/backlog-pre-issues/bad-code/SEC_submanifest-chunkcount-integrity.md similarity index 100% rename from docs/method/backlog/bad-code/SEC_submanifest-chunkcount-integrity.md rename to docs/archive/backlog-pre-issues/bad-code/SEC_submanifest-chunkcount-integrity.md diff --git a/docs/method/backlog/bad-code/SEC_submanifest-chunks-unvalidated.md b/docs/archive/backlog-pre-issues/bad-code/SEC_submanifest-chunks-unvalidated.md similarity index 100% rename from docs/method/backlog/bad-code/SEC_submanifest-chunks-unvalidated.md rename to docs/archive/backlog-pre-issues/bad-code/SEC_submanifest-chunks-unvalidated.md diff --git a/docs/method/backlog/bad-code/SEC_vault-nonce-exhaustion-cap.md b/docs/archive/backlog-pre-issues/bad-code/SEC_vault-nonce-exhaustion-cap.md similarity index 100% rename from docs/method/backlog/bad-code/SEC_vault-nonce-exhaustion-cap.md rename to docs/archive/backlog-pre-issues/bad-code/SEC_vault-nonce-exhaustion-cap.md diff --git a/docs/method/backlog/bad-code/SEC_vault-passphrase-verifier-gap.md b/docs/archive/backlog-pre-issues/bad-code/SEC_vault-passphrase-verifier-gap.md similarity index 100% rename from docs/method/backlog/bad-code/SEC_vault-passphrase-verifier-gap.md rename to docs/archive/backlog-pre-issues/bad-code/SEC_vault-passphrase-verifier-gap.md diff --git a/docs/method/backlog/bad-code/TR_casservice-decomposition-pressure.md b/docs/archive/backlog-pre-issues/bad-code/TR_casservice-decomposition-pressure.md similarity index 100% rename from docs/method/backlog/bad-code/TR_casservice-decomposition-pressure.md rename to docs/archive/backlog-pre-issues/bad-code/TR_casservice-decomposition-pressure.md diff --git a/docs/method/backlog/bad-code/TR_cryptoport-node-import.md b/docs/archive/backlog-pre-issues/bad-code/TR_cryptoport-node-import.md similarity index 100% rename from docs/method/backlog/bad-code/TR_cryptoport-node-import.md rename to docs/archive/backlog-pre-issues/bad-code/TR_cryptoport-node-import.md diff --git a/docs/method/backlog/bad-code/TR_dead-decompress-method.md b/docs/archive/backlog-pre-issues/bad-code/TR_dead-decompress-method.md similarity index 100% rename from docs/method/backlog/bad-code/TR_dead-decompress-method.md rename to docs/archive/backlog-pre-issues/bad-code/TR_dead-decompress-method.md diff --git a/docs/method/backlog/bad-code/TR_domain-imports-infrastructure.md b/docs/archive/backlog-pre-issues/bad-code/TR_domain-imports-infrastructure.md similarity index 100% rename from docs/method/backlog/bad-code/TR_domain-imports-infrastructure.md rename to docs/archive/backlog-pre-issues/bad-code/TR_domain-imports-infrastructure.md diff --git a/docs/method/backlog/bad-code/TR_persistence-adapter-materialization.md b/docs/archive/backlog-pre-issues/bad-code/TR_persistence-adapter-materialization.md similarity index 100% rename from docs/method/backlog/bad-code/TR_persistence-adapter-materialization.md rename to docs/archive/backlog-pre-issues/bad-code/TR_persistence-adapter-materialization.md diff --git a/docs/method/backlog/bad-code/TR_platform-dependency-leaks.md b/docs/archive/backlog-pre-issues/bad-code/TR_platform-dependency-leaks.md similarity index 96% rename from docs/method/backlog/bad-code/TR_platform-dependency-leaks.md rename to docs/archive/backlog-pre-issues/bad-code/TR_platform-dependency-leaks.md index 8afdf193..e8f43d0d 100644 --- a/docs/method/backlog/bad-code/TR_platform-dependency-leaks.md +++ b/docs/archive/backlog-pre-issues/bad-code/TR_platform-dependency-leaks.md @@ -1,6 +1,6 @@ # TR — Platform Dependency Leaks -Legend: [TR — Truth](../../legends/TR_truth.md) +Legend: [TR - Truth](../../../method/legends/TR_truth.md) ## Idea diff --git a/docs/method/backlog/bad-code/TR_schema-node-buffer-import.md b/docs/archive/backlog-pre-issues/bad-code/TR_schema-node-buffer-import.md similarity index 100% rename from docs/method/backlog/bad-code/TR_schema-node-buffer-import.md rename to docs/archive/backlog-pre-issues/bad-code/TR_schema-node-buffer-import.md diff --git a/docs/method/backlog/bad-code/TR_vault-retry-jitter.md b/docs/archive/backlog-pre-issues/bad-code/TR_vault-retry-jitter.md similarity index 100% rename from docs/method/backlog/bad-code/TR_vault-retry-jitter.md rename to docs/archive/backlog-pre-issues/bad-code/TR_vault-retry-jitter.md diff --git a/docs/method/backlog/bad-code/TUI_store-wizard-execution-gap.md b/docs/archive/backlog-pre-issues/bad-code/TUI_store-wizard-execution-gap.md similarity index 100% rename from docs/method/backlog/bad-code/TUI_store-wizard-execution-gap.md rename to docs/archive/backlog-pre-issues/bad-code/TUI_store-wizard-execution-gap.md diff --git a/docs/method/backlog/bad-code/vault-tree-memory-loading.md b/docs/archive/backlog-pre-issues/bad-code/vault-tree-memory-loading.md similarity index 100% rename from docs/method/backlog/bad-code/vault-tree-memory-loading.md rename to docs/archive/backlog-pre-issues/bad-code/vault-tree-memory-loading.md diff --git a/docs/method/backlog/cool-ideas/.gitkeep b/docs/archive/backlog-pre-issues/cool-ideas/.gitkeep similarity index 100% rename from docs/method/backlog/cool-ideas/.gitkeep rename to docs/archive/backlog-pre-issues/cool-ideas/.gitkeep diff --git a/docs/method/backlog/cool-ideas/DX_open-cas-helper.md b/docs/archive/backlog-pre-issues/cool-ideas/DX_open-cas-helper.md similarity index 100% rename from docs/method/backlog/cool-ideas/DX_open-cas-helper.md rename to docs/archive/backlog-pre-issues/cool-ideas/DX_open-cas-helper.md diff --git a/docs/method/backlog/cool-ideas/DX_slug-tree-path-helper.md b/docs/archive/backlog-pre-issues/cool-ideas/DX_slug-tree-path-helper.md similarity index 100% rename from docs/method/backlog/cool-ideas/DX_slug-tree-path-helper.md rename to docs/archive/backlog-pre-issues/cool-ideas/DX_slug-tree-path-helper.md diff --git a/docs/method/backlog/cool-ideas/OPS_release-doc-drift-guard.md b/docs/archive/backlog-pre-issues/cool-ideas/OPS_release-doc-drift-guard.md similarity index 100% rename from docs/method/backlog/cool-ideas/OPS_release-doc-drift-guard.md rename to docs/archive/backlog-pre-issues/cool-ideas/OPS_release-doc-drift-guard.md diff --git a/docs/method/backlog/cool-ideas/SEC_aes-gcm-aad-binding.md b/docs/archive/backlog-pre-issues/cool-ideas/SEC_aes-gcm-aad-binding.md similarity index 100% rename from docs/method/backlog/cool-ideas/SEC_aes-gcm-aad-binding.md rename to docs/archive/backlog-pre-issues/cool-ideas/SEC_aes-gcm-aad-binding.md diff --git a/docs/method/backlog/cool-ideas/SEC_fastcdc-dual-mask.md b/docs/archive/backlog-pre-issues/cool-ideas/SEC_fastcdc-dual-mask.md similarity index 100% rename from docs/method/backlog/cool-ideas/SEC_fastcdc-dual-mask.md rename to docs/archive/backlog-pre-issues/cool-ideas/SEC_fastcdc-dual-mask.md diff --git a/docs/method/backlog/cool-ideas/SEC_manifest-integrity-hash.md b/docs/archive/backlog-pre-issues/cool-ideas/SEC_manifest-integrity-hash.md similarity index 100% rename from docs/method/backlog/cool-ideas/SEC_manifest-integrity-hash.md rename to docs/archive/backlog-pre-issues/cool-ideas/SEC_manifest-integrity-hash.md diff --git a/docs/method/backlog/cool-ideas/TR_adaptive-frame-sizing.md b/docs/archive/backlog-pre-issues/cool-ideas/TR_adaptive-frame-sizing.md similarity index 100% rename from docs/method/backlog/cool-ideas/TR_adaptive-frame-sizing.md rename to docs/archive/backlog-pre-issues/cool-ideas/TR_adaptive-frame-sizing.md diff --git a/docs/method/backlog/cool-ideas/TR_browser-compression-adapter.md b/docs/archive/backlog-pre-issues/cool-ideas/TR_browser-compression-adapter.md similarity index 100% rename from docs/method/backlog/cool-ideas/TR_browser-compression-adapter.md rename to docs/archive/backlog-pre-issues/cool-ideas/TR_browser-compression-adapter.md diff --git a/docs/method/backlog/cool-ideas/TR_content-aware-chunking.md b/docs/archive/backlog-pre-issues/cool-ideas/TR_content-aware-chunking.md similarity index 100% rename from docs/method/backlog/cool-ideas/TR_content-aware-chunking.md rename to docs/archive/backlog-pre-issues/cool-ideas/TR_content-aware-chunking.md diff --git a/docs/method/backlog/cool-ideas/TR_convergent-encryption.md b/docs/archive/backlog-pre-issues/cool-ideas/TR_convergent-encryption.md similarity index 100% rename from docs/method/backlog/cool-ideas/TR_convergent-encryption.md rename to docs/archive/backlog-pre-issues/cool-ideas/TR_convergent-encryption.md diff --git a/docs/method/backlog/cool-ideas/TR_dedupe-efficiency-telemetry.md b/docs/archive/backlog-pre-issues/cool-ideas/TR_dedupe-efficiency-telemetry.md similarity index 100% rename from docs/method/backlog/cool-ideas/TR_dedupe-efficiency-telemetry.md rename to docs/archive/backlog-pre-issues/cool-ideas/TR_dedupe-efficiency-telemetry.md diff --git a/docs/method/backlog/cool-ideas/TR_dual-encryption-modes.md b/docs/archive/backlog-pre-issues/cool-ideas/TR_dual-encryption-modes.md similarity index 100% rename from docs/method/backlog/cool-ideas/TR_dual-encryption-modes.md rename to docs/archive/backlog-pre-issues/cool-ideas/TR_dual-encryption-modes.md diff --git a/docs/method/backlog/cool-ideas/TR_manifest-diffing.md b/docs/archive/backlog-pre-issues/cool-ideas/TR_manifest-diffing.md similarity index 100% rename from docs/method/backlog/cool-ideas/TR_manifest-diffing.md rename to docs/archive/backlog-pre-issues/cool-ideas/TR_manifest-diffing.md diff --git a/docs/method/backlog/cool-ideas/TR_manifest-signing.md b/docs/archive/backlog-pre-issues/cool-ideas/TR_manifest-signing.md similarity index 96% rename from docs/method/backlog/cool-ideas/TR_manifest-signing.md rename to docs/archive/backlog-pre-issues/cool-ideas/TR_manifest-signing.md index f2c9972a..8d032c29 100644 --- a/docs/method/backlog/cool-ideas/TR_manifest-signing.md +++ b/docs/archive/backlog-pre-issues/cool-ideas/TR_manifest-signing.md @@ -1,6 +1,6 @@ # TR — Manifest Signing -Legend: [TR — Truth](../../legends/TR_truth.md) +Legend: [TR - Truth](../../../method/legends/TR_truth.md) ## Idea diff --git a/docs/method/backlog/cool-ideas/TR_parallel-chunk-restore.md b/docs/archive/backlog-pre-issues/cool-ideas/TR_parallel-chunk-restore.md similarity index 100% rename from docs/method/backlog/cool-ideas/TR_parallel-chunk-restore.md rename to docs/archive/backlog-pre-issues/cool-ideas/TR_parallel-chunk-restore.md diff --git a/docs/method/backlog/cool-ideas/TR_streaming-decryption.md b/docs/archive/backlog-pre-issues/cool-ideas/TR_streaming-decryption.md similarity index 95% rename from docs/method/backlog/cool-ideas/TR_streaming-decryption.md rename to docs/archive/backlog-pre-issues/cool-ideas/TR_streaming-decryption.md index f4a68d87..7455d2ff 100644 --- a/docs/method/backlog/cool-ideas/TR_streaming-decryption.md +++ b/docs/archive/backlog-pre-issues/cool-ideas/TR_streaming-decryption.md @@ -1,6 +1,6 @@ # TR — Streaming Decryption -Legend: [TR — Truth](../../legends/TR_truth.md) +Legend: [TR - Truth](../../../method/legends/TR_truth.md) ## Idea diff --git a/docs/method/backlog/cool-ideas/TR_structured-json-logging.md b/docs/archive/backlog-pre-issues/cool-ideas/TR_structured-json-logging.md similarity index 100% rename from docs/method/backlog/cool-ideas/TR_structured-json-logging.md rename to docs/archive/backlog-pre-issues/cool-ideas/TR_structured-json-logging.md diff --git a/docs/method/backlog/cool-ideas/TR_vault-privacy-mode.md b/docs/archive/backlog-pre-issues/cool-ideas/TR_vault-privacy-mode.md similarity index 96% rename from docs/method/backlog/cool-ideas/TR_vault-privacy-mode.md rename to docs/archive/backlog-pre-issues/cool-ideas/TR_vault-privacy-mode.md index 3055d482..58b97115 100644 --- a/docs/method/backlog/cool-ideas/TR_vault-privacy-mode.md +++ b/docs/archive/backlog-pre-issues/cool-ideas/TR_vault-privacy-mode.md @@ -1,6 +1,6 @@ # TR — Vault Privacy Mode -Legend: [TR — Truth](../../legends/TR_truth.md) +Legend: [TR - Truth](../../../method/legends/TR_truth.md) ## Idea diff --git a/docs/method/backlog/cool-ideas/TUI_cli-adaptive-table.md b/docs/archive/backlog-pre-issues/cool-ideas/TUI_cli-adaptive-table.md similarity index 100% rename from docs/method/backlog/cool-ideas/TUI_cli-adaptive-table.md rename to docs/archive/backlog-pre-issues/cool-ideas/TUI_cli-adaptive-table.md diff --git a/docs/method/backlog/cool-ideas/TUI_operation-feed-drawer.md b/docs/archive/backlog-pre-issues/cool-ideas/TUI_operation-feed-drawer.md similarity index 100% rename from docs/method/backlog/cool-ideas/TUI_operation-feed-drawer.md rename to docs/archive/backlog-pre-issues/cool-ideas/TUI_operation-feed-drawer.md diff --git a/docs/method/backlog/cool-ideas/TUI_os-keychain-auto-discovery.md b/docs/archive/backlog-pre-issues/cool-ideas/TUI_os-keychain-auto-discovery.md similarity index 100% rename from docs/method/backlog/cool-ideas/TUI_os-keychain-auto-discovery.md rename to docs/archive/backlog-pre-issues/cool-ideas/TUI_os-keychain-auto-discovery.md diff --git a/docs/method/backlog/cool-ideas/TUI_segmented-manifest-view.md b/docs/archive/backlog-pre-issues/cool-ideas/TUI_segmented-manifest-view.md similarity index 100% rename from docs/method/backlog/cool-ideas/TUI_segmented-manifest-view.md rename to docs/archive/backlog-pre-issues/cool-ideas/TUI_segmented-manifest-view.md diff --git a/docs/method/backlog/cool-ideas/TUI_title-screen-stats.md b/docs/archive/backlog-pre-issues/cool-ideas/TUI_title-screen-stats.md similarity index 100% rename from docs/method/backlog/cool-ideas/TUI_title-screen-stats.md rename to docs/archive/backlog-pre-issues/cool-ideas/TUI_title-screen-stats.md diff --git a/docs/method/backlog/cool-ideas/atomic-multi-store.md b/docs/archive/backlog-pre-issues/cool-ideas/atomic-multi-store.md similarity index 100% rename from docs/method/backlog/cool-ideas/atomic-multi-store.md rename to docs/archive/backlog-pre-issues/cool-ideas/atomic-multi-store.md diff --git a/docs/method/backlog/cool-ideas/merkle-tree-explorer-tui.md b/docs/archive/backlog-pre-issues/cool-ideas/merkle-tree-explorer-tui.md similarity index 100% rename from docs/method/backlog/cool-ideas/merkle-tree-explorer-tui.md rename to docs/archive/backlog-pre-issues/cool-ideas/merkle-tree-explorer-tui.md diff --git a/docs/method/backlog/cool-ideas/selective-asset-replication.md b/docs/archive/backlog-pre-issues/cool-ideas/selective-asset-replication.md similarity index 100% rename from docs/method/backlog/cool-ideas/selective-asset-replication.md rename to docs/archive/backlog-pre-issues/cool-ideas/selective-asset-replication.md diff --git a/docs/method/backlog/cool-ideas/streaming-cli-stdin.md b/docs/archive/backlog-pre-issues/cool-ideas/streaming-cli-stdin.md similarity index 100% rename from docs/method/backlog/cool-ideas/streaming-cli-stdin.md rename to docs/archive/backlog-pre-issues/cool-ideas/streaming-cli-stdin.md diff --git a/docs/method/backlog/ideas/IDEA-001_streaming-convergent-encryption.md b/docs/archive/backlog-pre-issues/ideas/IDEA-001_streaming-convergent-encryption.md similarity index 100% rename from docs/method/backlog/ideas/IDEA-001_streaming-convergent-encryption.md rename to docs/archive/backlog-pre-issues/ideas/IDEA-001_streaming-convergent-encryption.md diff --git a/docs/method/backlog/v6.0.0-polish/POL-001_string-sludge-manifest-view.md b/docs/archive/backlog-pre-issues/v6.0.0-polish/POL-001_string-sludge-manifest-view.md similarity index 100% rename from docs/method/backlog/v6.0.0-polish/POL-001_string-sludge-manifest-view.md rename to docs/archive/backlog-pre-issues/v6.0.0-polish/POL-001_string-sludge-manifest-view.md diff --git a/docs/method/backlog/v6.0.0-polish/POL-002_string-sludge-vault-report.md b/docs/archive/backlog-pre-issues/v6.0.0-polish/POL-002_string-sludge-vault-report.md similarity index 100% rename from docs/method/backlog/v6.0.0-polish/POL-002_string-sludge-vault-report.md rename to docs/archive/backlog-pre-issues/v6.0.0-polish/POL-002_string-sludge-vault-report.md diff --git a/docs/method/backlog/v6.0.0-polish/POL-003_string-sludge-encryption-card.md b/docs/archive/backlog-pre-issues/v6.0.0-polish/POL-003_string-sludge-encryption-card.md similarity index 100% rename from docs/method/backlog/v6.0.0-polish/POL-003_string-sludge-encryption-card.md rename to docs/archive/backlog-pre-issues/v6.0.0-polish/POL-003_string-sludge-encryption-card.md diff --git a/docs/method/backlog/v6.0.0-polish/POL-004_boundary-violation-history-timeline.md b/docs/archive/backlog-pre-issues/v6.0.0-polish/POL-004_boundary-violation-history-timeline.md similarity index 100% rename from docs/method/backlog/v6.0.0-polish/POL-004_boundary-violation-history-timeline.md rename to docs/archive/backlog-pre-issues/v6.0.0-polish/POL-004_boundary-violation-history-timeline.md diff --git a/docs/method/backlog/v6.0.0-polish/POL-005_raw-ansi-progress.md b/docs/archive/backlog-pre-issues/v6.0.0-polish/POL-005_raw-ansi-progress.md similarity index 100% rename from docs/method/backlog/v6.0.0-polish/POL-005_raw-ansi-progress.md rename to docs/archive/backlog-pre-issues/v6.0.0-polish/POL-005_raw-ansi-progress.md diff --git a/docs/method/backlog/v6.0.0-polish/POL-006_magic-numbers-rhythm.md b/docs/archive/backlog-pre-issues/v6.0.0-polish/POL-006_magic-numbers-rhythm.md similarity index 100% rename from docs/method/backlog/v6.0.0-polish/POL-006_magic-numbers-rhythm.md rename to docs/archive/backlog-pre-issues/v6.0.0-polish/POL-006_magic-numbers-rhythm.md diff --git a/docs/method/backlog/v6.0.0-polish/POL-007_view-state-leakage.md b/docs/archive/backlog-pre-issues/v6.0.0-polish/POL-007_view-state-leakage.md similarity index 100% rename from docs/method/backlog/v6.0.0-polish/POL-007_view-state-leakage.md rename to docs/archive/backlog-pre-issues/v6.0.0-polish/POL-007_view-state-leakage.md diff --git a/docs/method/backlog/v6.0.0-polish/POL-008_manual-clipping.md b/docs/archive/backlog-pre-issues/v6.0.0-polish/POL-008_manual-clipping.md similarity index 100% rename from docs/method/backlog/v6.0.0-polish/POL-008_manual-clipping.md rename to docs/archive/backlog-pre-issues/v6.0.0-polish/POL-008_manual-clipping.md diff --git a/docs/method/backlog/v6.0.0-polish/POL-009_transition-shaders.md b/docs/archive/backlog-pre-issues/v6.0.0-polish/POL-009_transition-shaders.md similarity index 100% rename from docs/method/backlog/v6.0.0-polish/POL-009_transition-shaders.md rename to docs/archive/backlog-pre-issues/v6.0.0-polish/POL-009_transition-shaders.md diff --git a/docs/method/backlog/v6.0.0-polish/POL-010_heatmap-grid-math.md b/docs/archive/backlog-pre-issues/v6.0.0-polish/POL-010_heatmap-grid-math.md similarity index 100% rename from docs/method/backlog/v6.0.0-polish/POL-010_heatmap-grid-math.md rename to docs/archive/backlog-pre-issues/v6.0.0-polish/POL-010_heatmap-grid-math.md diff --git a/docs/method/backlog/v6.0.0-polish/POL-011_wizard-string-geometry.md b/docs/archive/backlog-pre-issues/v6.0.0-polish/POL-011_wizard-string-geometry.md similarity index 100% rename from docs/method/backlog/v6.0.0-polish/POL-011_wizard-string-geometry.md rename to docs/archive/backlog-pre-issues/v6.0.0-polish/POL-011_wizard-string-geometry.md diff --git a/docs/method/backlog/v6.0.0-polish/POL-012_asset-card-block.md b/docs/archive/backlog-pre-issues/v6.0.0-polish/POL-012_asset-card-block.md similarity index 100% rename from docs/method/backlog/v6.0.0-polish/POL-012_asset-card-block.md rename to docs/archive/backlog-pre-issues/v6.0.0-polish/POL-012_asset-card-block.md diff --git a/docs/method/backlog/v6.0.0-polish/POL-013_merkle-explorer-block.md b/docs/archive/backlog-pre-issues/v6.0.0-polish/POL-013_merkle-explorer-block.md similarity index 100% rename from docs/method/backlog/v6.0.0-polish/POL-013_merkle-explorer-block.md rename to docs/archive/backlog-pre-issues/v6.0.0-polish/POL-013_merkle-explorer-block.md diff --git a/docs/method/backlog/v6.0.0-polish/POL-014_health-dashboard-block.md b/docs/archive/backlog-pre-issues/v6.0.0-polish/POL-014_health-dashboard-block.md similarity index 100% rename from docs/method/backlog/v6.0.0-polish/POL-014_health-dashboard-block.md rename to docs/archive/backlog-pre-issues/v6.0.0-polish/POL-014_health-dashboard-block.md diff --git a/docs/method/backlog/v6.0.0-polish/POL-015_wizard-block.md b/docs/archive/backlog-pre-issues/v6.0.0-polish/POL-015_wizard-block.md similarity index 100% rename from docs/method/backlog/v6.0.0-polish/POL-015_wizard-block.md rename to docs/archive/backlog-pre-issues/v6.0.0-polish/POL-015_wizard-block.md diff --git a/docs/method/backlog/v6.0.0-polish/POL-016_operation-feed-block.md b/docs/archive/backlog-pre-issues/v6.0.0-polish/POL-016_operation-feed-block.md similarity index 100% rename from docs/method/backlog/v6.0.0-polish/POL-016_operation-feed-block.md rename to docs/archive/backlog-pre-issues/v6.0.0-polish/POL-016_operation-feed-block.md diff --git a/docs/method/backlog/v6.0.0-polish/POL-017_heatmap-block.md b/docs/archive/backlog-pre-issues/v6.0.0-polish/POL-017_heatmap-block.md similarity index 100% rename from docs/method/backlog/v6.0.0-polish/POL-017_heatmap-block.md rename to docs/archive/backlog-pre-issues/v6.0.0-polish/POL-017_heatmap-block.md diff --git a/docs/method/backlog/v6.0.0/REL_audit-blocker-burn-down.md b/docs/archive/backlog-pre-issues/v6.0.0/REL_audit-blocker-burn-down.md similarity index 100% rename from docs/method/backlog/v6.0.0/REL_audit-blocker-burn-down.md rename to docs/archive/backlog-pre-issues/v6.0.0/REL_audit-blocker-burn-down.md diff --git a/docs/method/backlog/v6.0.0/REL_breaking-changes-doc.md b/docs/archive/backlog-pre-issues/v6.0.0/REL_breaking-changes-doc.md similarity index 100% rename from docs/method/backlog/v6.0.0/REL_breaking-changes-doc.md rename to docs/archive/backlog-pre-issues/v6.0.0/REL_breaking-changes-doc.md diff --git a/docs/method/backlog/v6.0.0/REL_docs-accuracy-audit.md b/docs/archive/backlog-pre-issues/v6.0.0/REL_docs-accuracy-audit.md similarity index 100% rename from docs/method/backlog/v6.0.0/REL_docs-accuracy-audit.md rename to docs/archive/backlog-pre-issues/v6.0.0/REL_docs-accuracy-audit.md diff --git a/docs/method/backlog/v6.0.0/REL_migration-script.md b/docs/archive/backlog-pre-issues/v6.0.0/REL_migration-script.md similarity index 100% rename from docs/method/backlog/v6.0.0/REL_migration-script.md rename to docs/archive/backlog-pre-issues/v6.0.0/REL_migration-script.md diff --git a/docs/method/backlog/v6.0.0/REL_signpost-rewrite.md b/docs/archive/backlog-pre-issues/v6.0.0/REL_signpost-rewrite.md similarity index 100% rename from docs/method/backlog/v6.0.0/REL_signpost-rewrite.md rename to docs/archive/backlog-pre-issues/v6.0.0/REL_signpost-rewrite.md diff --git a/docs/method/backlog/v6.0.0/REL_version-bump.md b/docs/archive/backlog-pre-issues/v6.0.0/REL_version-bump.md similarity index 100% rename from docs/method/backlog/v6.0.0/REL_version-bump.md rename to docs/archive/backlog-pre-issues/v6.0.0/REL_version-bump.md diff --git a/docs/method/backlog/v6.x-tui/TUI_accordion-detail-pane.md b/docs/archive/backlog-pre-issues/v6.x-tui/TUI_accordion-detail-pane.md similarity index 100% rename from docs/method/backlog/v6.x-tui/TUI_accordion-detail-pane.md rename to docs/archive/backlog-pre-issues/v6.x-tui/TUI_accordion-detail-pane.md diff --git a/docs/method/backlog/v6.x-tui/TUI_animated-transitions.md b/docs/archive/backlog-pre-issues/v6.x-tui/TUI_animated-transitions.md similarity index 100% rename from docs/method/backlog/v6.x-tui/TUI_animated-transitions.md rename to docs/archive/backlog-pre-issues/v6.x-tui/TUI_animated-transitions.md diff --git a/docs/method/backlog/v6.x-tui/TUI_badge-components.md b/docs/archive/backlog-pre-issues/v6.x-tui/TUI_badge-components.md similarity index 100% rename from docs/method/backlog/v6.x-tui/TUI_badge-components.md rename to docs/archive/backlog-pre-issues/v6.x-tui/TUI_badge-components.md diff --git a/docs/method/backlog/v6.x-tui/TUI_box-surface-migration.md b/docs/archive/backlog-pre-issues/v6.x-tui/TUI_box-surface-migration.md similarity index 100% rename from docs/method/backlog/v6.x-tui/TUI_box-surface-migration.md rename to docs/archive/backlog-pre-issues/v6.x-tui/TUI_box-surface-migration.md diff --git a/docs/method/backlog/v6.x-tui/TUI_framed-app-shell.md b/docs/archive/backlog-pre-issues/v6.x-tui/TUI_framed-app-shell.md similarity index 100% rename from docs/method/backlog/v6.x-tui/TUI_framed-app-shell.md rename to docs/archive/backlog-pre-issues/v6.x-tui/TUI_framed-app-shell.md diff --git a/docs/method/backlog/v6.x-tui/TUI_fullscreen-detail-view.md b/docs/archive/backlog-pre-issues/v6.x-tui/TUI_fullscreen-detail-view.md similarity index 100% rename from docs/method/backlog/v6.x-tui/TUI_fullscreen-detail-view.md rename to docs/archive/backlog-pre-issues/v6.x-tui/TUI_fullscreen-detail-view.md diff --git a/docs/method/backlog/v6.x-tui/TUI_help-overlay.md b/docs/archive/backlog-pre-issues/v6.x-tui/TUI_help-overlay.md similarity index 100% rename from docs/method/backlog/v6.x-tui/TUI_help-overlay.md rename to docs/archive/backlog-pre-issues/v6.x-tui/TUI_help-overlay.md diff --git a/docs/method/backlog/v6.x-tui/TUI_layout-primitives.md b/docs/archive/backlog-pre-issues/v6.x-tui/TUI_layout-primitives.md similarity index 100% rename from docs/method/backlog/v6.x-tui/TUI_layout-primitives.md rename to docs/archive/backlog-pre-issues/v6.x-tui/TUI_layout-primitives.md diff --git a/docs/method/backlog/v6.x-tui/TUI_merkle-dag-viewer.md b/docs/archive/backlog-pre-issues/v6.x-tui/TUI_merkle-dag-viewer.md similarity index 100% rename from docs/method/backlog/v6.x-tui/TUI_merkle-dag-viewer.md rename to docs/archive/backlog-pre-issues/v6.x-tui/TUI_merkle-dag-viewer.md diff --git a/docs/method/backlog/v6.x-tui/TUI_orphaned-chunk-health-check.md b/docs/archive/backlog-pre-issues/v6.x-tui/TUI_orphaned-chunk-health-check.md similarity index 100% rename from docs/method/backlog/v6.x-tui/TUI_orphaned-chunk-health-check.md rename to docs/archive/backlog-pre-issues/v6.x-tui/TUI_orphaned-chunk-health-check.md diff --git a/docs/method/backlog/v6.x-tui/TUI_pager-scrollable-content.md b/docs/archive/backlog-pre-issues/v6.x-tui/TUI_pager-scrollable-content.md similarity index 100% rename from docs/method/backlog/v6.x-tui/TUI_pager-scrollable-content.md rename to docs/archive/backlog-pre-issues/v6.x-tui/TUI_pager-scrollable-content.md diff --git a/docs/method/backlog/v6.x-tui/TUI_status-bar.md b/docs/archive/backlog-pre-issues/v6.x-tui/TUI_status-bar.md similarity index 100% rename from docs/method/backlog/v6.x-tui/TUI_status-bar.md rename to docs/archive/backlog-pre-issues/v6.x-tui/TUI_status-bar.md diff --git a/docs/method/backlog/v6.x-tui/TUI_store-wizard.md b/docs/archive/backlog-pre-issues/v6.x-tui/TUI_store-wizard.md similarity index 100% rename from docs/method/backlog/v6.x-tui/TUI_store-wizard.md rename to docs/archive/backlog-pre-issues/v6.x-tui/TUI_store-wizard.md diff --git a/docs/method/backlog/v6.x-tui/TUI_toast-notifications.md b/docs/archive/backlog-pre-issues/v6.x-tui/TUI_toast-notifications.md similarity index 100% rename from docs/method/backlog/v6.x-tui/TUI_toast-notifications.md rename to docs/archive/backlog-pre-issues/v6.x-tui/TUI_toast-notifications.md diff --git a/docs/goalposts/README.md b/docs/archive/goalposts-pre-issues/README.md similarity index 75% rename from docs/goalposts/README.md rename to docs/archive/goalposts-pre-issues/README.md index 74674f1c..44221543 100644 --- a/docs/goalposts/README.md +++ b/docs/archive/goalposts-pre-issues/README.md @@ -1,8 +1,8 @@ # Goalposts -Goalposts are release-scale commitments. They sit between -[ROADMAP.md](../../ROADMAP.md) and numbered METHOD cycles under -[docs/design/](../design/README.md). +Goalposts were release-scale commitments. They sat between +[ROADMAP.md](../../../ROADMAP.md) and numbered METHOD cycles under +[docs/design/](../../design/README.md). Use goalposts when a release needs more structure than a single backlog card: @@ -24,5 +24,5 @@ Use goalposts when a release needs more structure than a single backlog card: ## Template -New goalposts should start from -[docs/templates/goalpost.md](../templates/goalpost.md). +New goalposts now start from the +[GitHub goalpost issue form](../../../.github/ISSUE_TEMPLATE/goalpost.yml). diff --git a/docs/goalposts/v6.0.1/release-truth-closeout.md b/docs/archive/goalposts-pre-issues/v6.0.1/release-truth-closeout.md similarity index 94% rename from docs/goalposts/v6.0.1/release-truth-closeout.md rename to docs/archive/goalposts-pre-issues/v6.0.1/release-truth-closeout.md index 956f905d..73a74cd5 100644 --- a/docs/goalposts/v6.0.1/release-truth-closeout.md +++ b/docs/archive/goalposts-pre-issues/v6.0.1/release-truth-closeout.md @@ -22,12 +22,12 @@ evidence all agree with what is on `main`. ## Current Truth -- [STATUS.md](../../../STATUS.md) describes `v6.0.1` as a patch candidate on +- [STATUS.md](../../../../STATUS.md) describes `v6.0.1` as a patch candidate on `main` and records `npm run release:verify -- --skip-jsr` passing 12/12 steps with 5,383 observed tests. -- [ROADMAP.md](../../../ROADMAP.md) now treats release planning as goalpost +- [ROADMAP.md](../../../../ROADMAP.md) now treats release planning as goalpost driven rather than milestone fiction. -- [docs/method/backlog/README.md](../../method/backlog/README.md) has empty +- [docs/method/backlog/README.md](../../../method/backlog/README.md) has empty `asap/` and `up-next/` lanes. - Some older TUI backlog cards still describe pre-ship states and need a truth pass before they become `v6.2.0` goalpost work. diff --git a/docs/goalposts/v6.1.0/bounded-residency.md b/docs/archive/goalposts-pre-issues/v6.1.0/bounded-residency.md similarity index 92% rename from docs/goalposts/v6.1.0/bounded-residency.md rename to docs/archive/goalposts-pre-issues/v6.1.0/bounded-residency.md index 9aa2527d..eba88a5d 100644 --- a/docs/goalposts/v6.1.0/bounded-residency.md +++ b/docs/archive/goalposts-pre-issues/v6.1.0/bounded-residency.md @@ -23,17 +23,17 @@ trees or blobs. ## Current Truth -- [docs/method/backlog/bad-code/vault-tree-memory-loading.md](../../method/backlog/bad-code/vault-tree-memory-loading.md) +- [docs/archive/backlog-pre-issues/bad-code/vault-tree-memory-loading.md](../../backlog-pre-issues/bad-code/vault-tree-memory-loading.md) names full vault tree loading as active debt. -- [docs/method/backlog/bad-code/TR_persistence-adapter-materialization.md](../../method/backlog/bad-code/TR_persistence-adapter-materialization.md) +- [docs/archive/backlog-pre-issues/bad-code/TR_persistence-adapter-materialization.md](../../backlog-pre-issues/bad-code/TR_persistence-adapter-materialization.md) names `GitPersistenceAdapter.readBlob()` materialization pressure as active debt. -- [src/infrastructure/adapters/GitPersistenceAdapter.js](../../../src/infrastructure/adapters/GitPersistenceAdapter.js) +- [src/infrastructure/adapters/GitPersistenceAdapter.js](../../../../src/infrastructure/adapters/GitPersistenceAdapter.js) already provides `readBlobStream()`, a default `readBlob()` safety limit, and tree iteration helpers. -- [src/domain/services/VaultPersistence.js](../../../src/domain/services/VaultPersistence.js) +- [src/domain/services/VaultPersistence.js](../../../../src/domain/services/VaultPersistence.js) already contains direct tree-entry and streaming tree iteration boundaries. -- [src/domain/services/VaultService.js](../../../src/domain/services/VaultService.js) +- [src/domain/services/VaultService.js](../../../../src/domain/services/VaultService.js) still has cached vault tree paths that can turn single-entry work into whole-tree residency. diff --git a/docs/goalposts/v6.2.0/operator-tui.md b/docs/archive/goalposts-pre-issues/v6.2.0/operator-tui.md similarity index 91% rename from docs/goalposts/v6.2.0/operator-tui.md rename to docs/archive/goalposts-pre-issues/v6.2.0/operator-tui.md index a26023a2..5959e79d 100644 --- a/docs/goalposts/v6.2.0/operator-tui.md +++ b/docs/archive/goalposts-pre-issues/v6.2.0/operator-tui.md @@ -22,10 +22,10 @@ agent-readable evidence. ## Current Truth -- [BEARING.md](../../../BEARING.md) names TUI modernization as an open tension. -- [docs/method/backlog/v6.x-tui/](../../method/backlog/v6.x-tui/) contains the +- [BEARING.md](../../../../BEARING.md) names TUI modernization as an open tension. +- [docs/archive/backlog-pre-issues/v6.x-tui/](../../backlog-pre-issues/v6.x-tui/) contains the v6.x TUI lane. -- [docs/method/backlog/bad-code/TUI_store-wizard-execution-gap.md](../../method/backlog/bad-code/TUI_store-wizard-execution-gap.md) +- [docs/archive/backlog-pre-issues/bad-code/TUI_store-wizard-execution-gap.md](../../backlog-pre-issues/bad-code/TUI_store-wizard-execution-gap.md) is marked resolved in the backlog index, so the v6.x TUI lane needs a truth pass before implementation begins. diff --git a/docs/goalposts/v6.3.0/agent-automation-parity.md b/docs/archive/goalposts-pre-issues/v6.3.0/agent-automation-parity.md similarity index 95% rename from docs/goalposts/v6.3.0/agent-automation-parity.md rename to docs/archive/goalposts-pre-issues/v6.3.0/agent-automation-parity.md index 5434f252..5b981ba2 100644 --- a/docs/goalposts/v6.3.0/agent-automation-parity.md +++ b/docs/archive/goalposts-pre-issues/v6.3.0/agent-automation-parity.md @@ -22,9 +22,9 @@ details. ## Current Truth -- [STATUS.md](../../../STATUS.md) says the machine-facing `git cas agent` +- [STATUS.md](../../../../STATUS.md) says the machine-facing `git cas agent` surface exists, but parity and portability are still partial. -- [docs/design/](../../design/README.md) contains landed Relay and agent CLI +- [docs/design/](../../../design/README.md) contains landed Relay and agent CLI design history. ## Scope diff --git a/docs/goalposts/v6.4.0/browser-edge-read-path.md b/docs/archive/goalposts-pre-issues/v6.4.0/browser-edge-read-path.md similarity index 97% rename from docs/goalposts/v6.4.0/browser-edge-read-path.md rename to docs/archive/goalposts-pre-issues/v6.4.0/browser-edge-read-path.md index e4cb800d..ac938c96 100644 --- a/docs/goalposts/v6.4.0/browser-edge-read-path.md +++ b/docs/archive/goalposts-pre-issues/v6.4.0/browser-edge-read-path.md @@ -21,7 +21,7 @@ restoring existing content without shelling out to the Git CLI. ## Current Truth -- [BEARING.md](../../../BEARING.md) names browser/edge persistence as an open +- [BEARING.md](../../../../BEARING.md) names browser/edge persistence as an open tension. - The current Git persistence path depends on the Git CLI through `@git-stunts/plumbing`. diff --git a/docs/goalposts/v7.0.0/protocol-audit-response.md b/docs/archive/goalposts-pre-issues/v7.0.0/protocol-audit-response.md similarity index 97% rename from docs/goalposts/v7.0.0/protocol-audit-response.md rename to docs/archive/goalposts-pre-issues/v7.0.0/protocol-audit-response.md index 5431c554..6fa77d6c 100644 --- a/docs/goalposts/v7.0.0/protocol-audit-response.md +++ b/docs/archive/goalposts-pre-issues/v7.0.0/protocol-audit-response.md @@ -21,7 +21,7 @@ evidence requires a breaking change. Otherwise the work remains in `v6.x`. ## Current Truth -- [BEARING.md](../../../BEARING.md) names formal crypto audit as an open +- [BEARING.md](../../../../BEARING.md) names formal crypto audit as an open tension. - `v6.0.0` simplified encryption schemes and added migration tooling. - No third-party audit result is currently recorded in the repo. diff --git a/docs/audit/2026-05-04_ship-readiness.md b/docs/audit/2026-05-04_ship-readiness.md index b9722970..6af3560e 100644 --- a/docs/audit/2026-05-04_ship-readiness.md +++ b/docs/audit/2026-05-04_ship-readiness.md @@ -259,4 +259,4 @@ TUI-specific work may defer to the v6.x release line. ### Deferred To v6.x - **Operational Gap 3 - TUI Orphaned-Chunk Health Check:** Deferred to - [TUI — Orphaned-Chunk Health Check](../method/backlog/v6.x-tui/TUI_orphaned-chunk-health-check.md). + [TUI — Orphaned-Chunk Health Check](../archive/backlog-pre-issues/v6.x-tui/TUI_orphaned-chunk-health-check.md). diff --git a/docs/design/0045-v6-1-bounded-residency/bounded-residency.md b/docs/design/0045-v6-1-bounded-residency/bounded-residency.md index 502b444d..8e27793b 100644 --- a/docs/design/0045-v6-1-bounded-residency/bounded-residency.md +++ b/docs/design/0045-v6-1-bounded-residency/bounded-residency.md @@ -4,8 +4,9 @@ cycle: "0045" task_id: "bounded-residency" legend: "PERF" release_home: "v6.1.0" -goalpost: "docs/goalposts/v6.1.0/bounded-residency.md" -issue: "not opened yet" +issue: "https://github.com/git-stunts/git-cas/issues/38" +goalpost_issue: "https://github.com/git-stunts/git-cas/issues/38" +tracker_source: "github" status: "draft" base_commit: "662fcc7661114715670c0eb48e78bcce47cae43c" owners: @@ -15,8 +16,8 @@ sponsors: agent: "Codex" blocking_issues: [] supersedes: - - "docs/method/backlog/bad-code/vault-tree-memory-loading.md" - - "docs/method/backlog/bad-code/TR_persistence-adapter-materialization.md" + - "docs/archive/backlog-pre-issues/bad-code/vault-tree-memory-loading.md" + - "docs/archive/backlog-pre-issues/bad-code/TR_persistence-adapter-materialization.md" superseded_by: null created: "2026-06-13" updated: "2026-06-13" @@ -26,11 +27,17 @@ updated: "2026-06-13" ## Linked Issue -- `not opened yet` +- https://github.com/git-stunts/git-cas/issues/38 -## Linked Goalpost +## Linked Tracker -- [v6.1.0 Bounded Residency](../../goalposts/v6.1.0/bounded-residency.md) +- Milestone: `v6.1.0` +- Goalpost issue: https://github.com/git-stunts/git-cas/issues/38 +- Slice issues: + - https://github.com/git-stunts/git-cas/issues/43 + - https://github.com/git-stunts/git-cas/issues/44 + - https://github.com/git-stunts/git-cas/issues/45 + - https://github.com/git-stunts/git-cas/issues/46 ## Design Type @@ -72,10 +79,10 @@ without overstating custom adapter guarantees. ## Current Truth -- `docs/method/backlog/bad-code/vault-tree-memory-loading.md` says +- `docs/archive/backlog-pre-issues/bad-code/vault-tree-memory-loading.md` says `VaultService.#readCachedVaultTree` and dependencies read and parse an entire Git tree into a slug map. -- `docs/method/backlog/bad-code/TR_persistence-adapter-materialization.md` says +- `docs/archive/backlog-pre-issues/bad-code/TR_persistence-adapter-materialization.md` says `GitPersistenceAdapter.readBlob` materialization creates O(N) residency pressure. - `src/infrastructure/adapters/GitPersistenceAdapter.js` exposes @@ -108,7 +115,7 @@ This cycle includes: `readBlobStream()` when payload size is unbounded. - Implementation changes inside `VaultService`, `VaultPersistence`, `ChunkRepository`, `ManifestRepository`, or adapters as needed. -- Documentation updates to the goalpost, backlog cards, `STATUS.md`, +- Documentation updates to the GitHub issues, design witness, `STATUS.md`, `CHANGELOG.md`, and release evidence. ## Non-Goals @@ -245,7 +252,7 @@ Agents can inspect the result through: - stable test names - `CasError` codes and metadata - command transcripts in `docs/design/0045-v6-1-bounded-residency/witness/` -- goalpost closeout checkboxes +- GitHub issue closeout tasks - changelog entries that name the actual bounded surfaces ## Linked Invariants @@ -319,7 +326,7 @@ The implementation must be proven through: - Add streaming vault list tests. - Add or tighten `readBlob()`/`readBlobStream()` residency tests. - Implement the bounded read behavior. -- Update docs, changelog, goalpost, and witness evidence. +- Update docs, changelog, GitHub issue closeout, and witness evidence. Each slice should be independently reviewable and should close with a concrete test or witness. @@ -339,8 +346,9 @@ Behavior tests required: Documentation/process tests, only if relevant: -- [ ] Goalpost and roadmap links point to real files. -- [ ] Backlog cards are updated or dispositioned after implementation. +- [ ] GitHub issue links point to the canonical goalpost and slice issues. +- [ ] Archived backlog inputs are dispositioned through GitHub issue comments or + closeout notes after implementation. Rule: documentation tests cannot be the only proof for implementation work. @@ -353,7 +361,7 @@ The work is done when: - [ ] Runtime tests prove the blob read contract. - [ ] Errors are explicit when safe streaming support is missing. - [ ] Docs, changelog, and release notes are updated. -- [ ] Goalpost closeout is updated. +- [ ] Goalpost issue closeout is updated. - [ ] CI and local validation are green. ## Validation Plan @@ -397,7 +405,7 @@ Mitigations: ## Follow-On Debt -Create backlog files or GitHub issues for: +Create GitHub issues for: - public paginated vault APIs, if tests prove operator need - browser/edge read-path adapter work @@ -407,9 +415,13 @@ Create backlog files or GitHub issues for: | Issue | Role | Expected disposition | | --- | --- | --- | -| `docs/method/backlog/bad-code/vault-tree-memory-loading.md` | primary input | close or mark resolved when tests and implementation land | -| `docs/method/backlog/bad-code/TR_persistence-adapter-materialization.md` | primary input | close or rewrite to remaining custom-adapter risk | -| `not opened yet` | umbrella issue | open before implementation PR | +| `docs/archive/backlog-pre-issues/bad-code/vault-tree-memory-loading.md` | historical input | cite from the goalpost issue and mark resolved when tests and implementation land | +| `docs/archive/backlog-pre-issues/bad-code/TR_persistence-adapter-materialization.md` | historical input | cite from the goalpost issue or create a narrower follow-up issue for remaining custom-adapter risk | +| https://github.com/git-stunts/git-cas/issues/38 | umbrella issue | update and close when all accepted slices land | +| https://github.com/git-stunts/git-cas/issues/43 | slice | close when targeted vault lookup proof lands | +| https://github.com/git-stunts/git-cas/issues/44 | slice | close when streaming vault list proof lands | +| https://github.com/git-stunts/git-cas/issues/45 | slice | close when blob read residency proof lands | +| https://github.com/git-stunts/git-cas/issues/46 | slice | close when docs, witness, and release evidence are updated | ## Done Does Not Mean diff --git a/docs/legends/RL-relay.md b/docs/legends/RL-relay.md index 946f75ce..7e37f1ef 100644 --- a/docs/legends/RL-relay.md +++ b/docs/legends/RL-relay.md @@ -11,7 +11,9 @@ Build a first-class machine-facing `git cas agent` contract and keep the shared application boundary explicit enough that later human-surface work can reuse it honestly. -## Current METHOD Backlog +## Current METHOD Tracker + +GitHub Issues and Milestones own current Relay work. - none currently diff --git a/docs/legends/TR-truth.md b/docs/legends/TR-truth.md index a1e8fb3f..538d847e 100644 --- a/docs/legends/TR-truth.md +++ b/docs/legends/TR-truth.md @@ -10,11 +10,11 @@ Current legend truth now lives in Keep the repo honest about what `git-cas` is, how it works, what it protects, and what tradeoffs it makes. -## Current METHOD Backlog +## Current METHOD Tracker -- none currently in `asap/` -- none currently in `up-next/` -- [TR — Platform Dependency Leaks](../method/backlog/bad-code/TR_platform-dependency-leaks.md) +GitHub Issues and Milestones own current Truth work. + +- none currently tracked in this file ## Legacy Landed Truth Cycles diff --git a/docs/method/backlog/README.md b/docs/method/backlog/README.md index 428d30a2..5e10b7af 100644 --- a/docs/method/backlog/README.md +++ b/docs/method/backlog/README.md @@ -1,162 +1,21 @@ -# Method Backlog +# Retired Method Backlog -This is the active backlog for fresh `git-cas` work. +This directory is no longer an active work tracker. -The lane is the priority: +GitHub Issues and Milestones are now the canonical source of truth for work +that needs to get done. If work is actionable, it must be represented by a +GitHub Issue. -- `inbox/` — raw capture -- `asap/` — pull this soon -- `up-next/` — likely after the current pull -- `cool-ideas/` — interesting, not committed -- `bad-code/` — debt that works but bothers us -- `v6.0.0/` — completed v6.0.0 release gate archive -- `v6.x-tui/` — post-6.0 TUI modernization work for the v6 release line +Historical backlog files were moved to: -Backlog filenames use legend prefixes when they belong to a named domain and do -not use numeric IDs. +- [docs/archive/backlog-pre-issues/](../../archive/backlog-pre-issues/) -## Current Lanes +Use those files only as source material when opening GitHub Issues. -### `inbox/` +Do not add new work cards here. -- none currently +For current workflow, read: -### `asap/` - -- none currently - -### `up-next/` - -- none currently - -### `v6.0.0/` (completed release gate) - -Active: - -- none currently - -Resolved: - -- [REL — Audit Blocker Burn-Down](./v6.0.0/REL_audit-blocker-burn-down.md) — non-TUI May 4 audit leftovers cleared before `v6.0.0` -- [Version Bump](./v6.0.0/REL_version-bump.md) — tag/publish gate completed; JSR publication remains deferred externally -- [REL — Migration Script](./v6.0.0/REL_migration-script.md) — `npm run upgrade` with dry-run + execute modes -- [REL — Breaking Changes Doc](./v6.0.0/REL_breaking-changes-doc.md) — `UPGRADING.md` with migration guide -- [REL — Docs Accuracy Audit](./v6.0.0/REL_docs-accuracy-audit.md) — GUIDE examples and tracked Markdown links covered by tests -- [REL — Signpost Rewrite](./v6.0.0/REL_signpost-rewrite.md) — README, BEARING, VISION, STATUS for v6 - -### `v6.x-tui/` (Bijou v5 TUI modernization) - -Post-6.0 minor release line, not a v6.0.0 tag blocker. - -1. [TUI-001 — Framed App Shell](./v6.x-tui/TUI_framed-app-shell.md) — Foundation: `createFramedApp()` + `startApp()` -2. [TUI-002 — boxV3 -> boxSurface](./v6.x-tui/TUI_box-surface-migration.md) — Breaking API fix (Small) -3. [TUI-003 — Status Bar](./v6.x-tui/TUI_status-bar.md) — Persistent bottom bar -4. [TUI-004 — Toast Notifications](./v6.x-tui/TUI_toast-notifications.md) — Replace custom toast with built-in -5. [TUI-005 — Badge Components](./v6.x-tui/TUI_badge-components.md) — Bijou `badge` for encryption/compression tags -6. [TUI-006 — Layout Primitives](./v6.x-tui/TUI_layout-primitives.md) — hstack/vstack/flex/grid -7. [TUI-007 — Help Overlay](./v6.x-tui/TUI_help-overlay.md) — `?` key -> full keybinding reference -8. [TUI-008 — Merkle DAG Viewer](./v6.x-tui/TUI_merkle-dag-viewer.md) — `dagPane` for manifest structure -9. [TUI-009 — Interactive Store Wizard](./v6.x-tui/TUI_store-wizard.md) — Guided store flow inside TUI -10. [TUI-010 — Pager Scrollable Content](./v6.x-tui/TUI_pager-scrollable-content.md) — Scrollable detail pane -11. [TUI-011 — Accordion Detail Pane](./v6.x-tui/TUI_accordion-detail-pane.md) — Collapsible manifest sections -12. [TUI-012 — Animated Transitions](./v6.x-tui/TUI_animated-transitions.md) — Spring physics + transition shaders -13. [TUI-013 — Full-Screen Detail View](./v6.x-tui/TUI_fullscreen-detail-view.md) — Replace split pane with list/detail drill-in -14. [TUI-014 — Orphaned-Chunk Health Check](./v6.x-tui/TUI_orphaned-chunk-health-check.md) — Dashboard-visible CAS reachability health - -### `cool-ideas/` - -Active: - -- [DX — One-step CAS Opener](./cool-ideas/DX_open-cas-helper.md) -- [OPS — Release-Gate Docs and Examples Drift Guard](./cool-ideas/OPS_release-doc-drift-guard.md) -- [TR — Adaptive Framed-Encryption Sizing](./cool-ideas/TR_adaptive-frame-sizing.md) -- [TR — Convergent Encryption](./cool-ideas/TR_convergent-encryption.md) ✅ -- [TR — Browser Compression Adapter](./cool-ideas/TR_browser-compression-adapter.md) -- [TR — Manifest Diffing](./cool-ideas/TR_manifest-diffing.md) ✅ -- [TR — Parallel Chunk Restore](./cool-ideas/TR_parallel-chunk-restore.md) ✅ -- [TR — Content-Aware Chunking](./cool-ideas/TR_content-aware-chunking.md) -- [TUI — CLI Adaptive Table](./cool-ideas/TUI_cli-adaptive-table.md) -- [TUI — Operation Feed Drawer](./cool-ideas/TUI_operation-feed-drawer.md) -- [TUI — OS Keychain Auto-Discovery](./cool-ideas/TUI_os-keychain-auto-discovery.md) -- [TUI — Segmented Manifest View](./cool-ideas/TUI_segmented-manifest-view.md) -- [TUI — Title Screen Stats](./cool-ideas/TUI_title-screen-stats.md) -- [Atomic Multi-Store](./cool-ideas/atomic-multi-store.md) -- [Merkle Tree Explorer TUI](./cool-ideas/merkle-tree-explorer-tui.md) -- [Selective Asset Replication](./cool-ideas/selective-asset-replication.md) -- [Streaming CLI stdin](./cool-ideas/streaming-cli-stdin.md) -- [TR — CAS Health & Dedupe Telemetry](./cool-ideas/TR_dedupe-efficiency-telemetry.md) -- [TR — Industrial Structured Logging](./cool-ideas/TR_structured-json-logging.md) - -Resolved — `security/audit-fixes` branch: - -- [TR — Dual Encryption Modes](./cool-ideas/TR_dual-encryption-modes.md) ✅ -- [TR — Manifest Signing](./cool-ideas/TR_manifest-signing.md) ✅ -- [TR — Streaming Decryption](./cool-ideas/TR_streaming-decryption.md) ✅ -- [TR — Vault Privacy Mode](./cool-ideas/TR_vault-privacy-mode.md) ✅ -- [SEC — AES-GCM AAD Binding](./cool-ideas/SEC_aes-gcm-aad-binding.md) ✅ -- [SEC — FastCDC Dual-Mask Normalization](./cool-ideas/SEC_fastcdc-dual-mask.md) ✅ -- [SEC — Manifest-Level Integrity Hash](./cool-ideas/SEC_manifest-integrity-hash.md) ✅ - -Resolved — 2026-05-05 final v6 release polish: - -- [DX — Slug Tree-Path Helper](./cool-ideas/DX_slug-tree-path-helper.md) ✅ - -### `bad-code/` - -Active: - -- [Vault Tree Memory Loading](./bad-code/vault-tree-memory-loading.md) -- [TR — GitPersistenceAdapter Full Materialization](./bad-code/TR_persistence-adapter-materialization.md) - -Resolved — 2026-05-09 v6.0.1 patch: - -- [TUI — Store Wizard Execution Gap](./bad-code/TUI_store-wizard-execution-gap.md) ✅ - -Resolved — 2026-05-05 CasService de-sludge: - -- [BAD-CODE-001 — CasService God Object](./bad-code/BAD-CODE-001_casservice-god-object.md) ✅ - -Resolved — 2026-05-08 VaultService decomposition: - -- [TR — VaultService Optimistic Contention](./bad-code/TR_vault-retry-jitter.md) ✅ - -Resolved — 2026-05-05 core orchestration cleanup: - -- [TR — CasService Decomposition Pressure](./bad-code/TR_casservice-decomposition-pressure.md) ✅ - -Resolved — 2026-05-05 final v6 release polish: - -- [RL — Credential Resolution Duplication](./bad-code/RL_credential-resolution-duplication.md) ✅ - -Resolved — 2026-05-05 agent boundary cleanup: - -- [RL — Agent CLI Module Size](./bad-code/RL_agent-cli-module-size.md) ✅ - -Resolved — 2026-05-05 release-truth cleanup: - -- [DOC — API Reference Plumbing Constructor Drift](./bad-code/DOC_api-plumbing-constructor-drift.md) ✅ -- [DOC — Examples Uint8Array Drift](./bad-code/DOC_examples-uint8array-drift.md) ✅ -- [DOC — Threat Model Scheme Drift](./bad-code/DOC_threat-model-scheme-drift.md) ✅ -- [SEC — Inline Passphrase Flags](./bad-code/SEC_inline-passphrase-flags.md) ✅ -- [SEC — Vault Nonce Exhaustion Cap](./bad-code/SEC_vault-nonce-exhaustion-cap.md) ✅ -- [SEC — Vault Passphrase Verifier Gap](./bad-code/SEC_vault-passphrase-verifier-gap.md) ✅ - -Resolved — `security/audit-fixes` branch: - -- [SEC — Chunk Constructor Property Leak](./bad-code/SEC_chunk-constructor-property-leak.md) ✅ -- [SEC — Schema Hex Validation](./bad-code/SEC_schema-hex-validation.md) ✅ -- [SEC — Scrypt Memory Budget](./bad-code/SEC_scrypt-memory-budget.md) ✅ -- [SEC — Sub-Manifest Array Limit](./bad-code/SEC_submanifest-array-limit.md) ✅ -- [SEC — encodeSlug Control Chars](./bad-code/SEC_encode-slug-control-chars.md) ✅ -- [SEC — KDF Salt Min Length](./bad-code/SEC_kdf-salt-min-length.md) ✅ -- [SEC — frameBytes Upper Bound](./bad-code/SEC_framebytes-upper-bound.md) ✅ -- [SEC — Concurrency Upper Bound](./bad-code/SEC_concurrency-upper-bound.md) ✅ -- [SEC — Sub-Manifest chunkCount Integrity](./bad-code/SEC_submanifest-chunkcount-integrity.md) ✅ -- [SEC — Recipient Timing Oracle](./bad-code/SEC_recipient-timing-oracle.md) ✅ -- [SEC — Store Source Validation](./bad-code/SEC_store-source-validation.md) ✅ -- [SEC — Sub-Manifest Chunks Unvalidated](./bad-code/SEC_submanifest-chunks-unvalidated.md) ✅ -- [TR — Platform Dependency Leaks](./bad-code/TR_platform-dependency-leaks.md) ✅ -- [TR — Dead \_decompress() Method](./bad-code/TR_dead-decompress-method.md) ✅ -- [TR — Domain Imports Infrastructure](./bad-code/TR_domain-imports-infrastructure.md) ✅ -- [TR — CryptoPort node:crypto Import](./bad-code/TR_cryptoport-node-import.md) ✅ -- [TR — ManifestSchema node:buffer Import](./bad-code/TR_schema-node-buffer-import.md) ✅ +- [ROADMAP.md](../../../ROADMAP.md) +- [docs/method/process.md](../process.md) +- [docs/design/README.md](../../design/README.md) diff --git a/docs/method/legends/RL_relay.md b/docs/method/legends/RL_relay.md index bc1d736f..afb02549 100644 --- a/docs/method/legends/RL_relay.md +++ b/docs/method/legends/RL_relay.md @@ -24,7 +24,9 @@ behavior. - machine-facing commands emit explicit records and exit codes - human and agent surfaces stay separate over one shared core -## Current Backlog +## Current Tracker + +GitHub Issues and Milestones own current Relay work. - none currently diff --git a/docs/method/legends/TR_truth.md b/docs/method/legends/TR_truth.md index 2d90601d..91deefe7 100644 --- a/docs/method/legends/TR_truth.md +++ b/docs/method/legends/TR_truth.md @@ -20,16 +20,16 @@ discovering later that an important boundary, tradeoff, or workflow was stale. ## How We Know -- backlog and design surfaces agree +- GitHub tracker and design surfaces agree - canonical docs point to the right adjacent truths - threat, benchmark, and architecture claims match shipped behavior - follow-on investigative work is named instead of hand-waved -## Current Backlog +## Current Tracker -- none currently in `asap/` -- none currently in `up-next/` -- [TR — Platform Dependency Leaks](../backlog/bad-code/TR_platform-dependency-leaks.md) +GitHub Issues and Milestones own current Truth work. + +- none currently tracked in this file ## Historical Context diff --git a/docs/method/process.md b/docs/method/process.md index 31777f9b..382964c4 100644 --- a/docs/method/process.md +++ b/docs/method/process.md @@ -5,6 +5,11 @@ _A backlog, a loop, and honest bookkeeping._ This file is the canonical planning and delivery process for fresh work in `git-cas`. +The core rule is: + +> If it is actionable work, it must be a GitHub Issue. If it only appears in a +> Markdown file, it is not tracked work. + ## Principles - The human and the agent sit at the same table. Both are named in every @@ -23,24 +28,25 @@ This file is the canonical planning and delivery process for fresh work in over hardcoded left/right assumptions. - Agent surfaces must be explicit and inspectable. Design must say what is agent-generated, what evidence it relies on, and what action it expects next. -- The filesystem is the database. A directory is a priority. A filename is an - identity. Moving a file is a decision. +- GitHub Issues are the tracker. Milestones, labels, issue state, issue links, + and pull requests own active work status. +- The filesystem is the design and evidence ledger. Markdown explains decisions, + proof plans, witnesses, public docs, and historical context; it does not own + open work state. - Process should stay calm. No sprints, velocity theater, or burndown charts. ## Structure -Fresh planning now uses: +Fresh work now uses: ```text +GitHub + milestones/ + issues/ + labels/ + docs/ - goalposts/ method/ - backlog/ - inbox/ - asap/ - up-next/ - cool-ideas/ - bad-code/ legends/ retro//.md graveyard/ @@ -56,72 +62,68 @@ Repo-specific notes: - `docs/design//witness/` holds playback evidence for the cycle. - Top-level legacy cycle docs already in `docs/design/` remain in place for history and link stability. -- Legacy planning compatibility surfaces remain in `docs/BACKLOG/` and - `docs/legends/`, but they are no longer the source of truth for fresh work. +- Legacy planning compatibility surfaces remain in `docs/BACKLOG/`, + `docs/legends/`, and `docs/archive/`, but they are not active tracking + surfaces. ## Roadmap And Goalposts -[ROADMAP.md](../../ROADMAP.md) lists upcoming versioned releases. A release is -made of goalposts, and a goalpost is a release-scale feature, invariant, or -evidence packet that must be met before that release can honestly ship. - -Goalpost docs live in [docs/goalposts/](../goalposts/README.md). They do not -replace backlog items or design cycles: +[ROADMAP.md](../../ROADMAP.md) lists the intended release train and points to +GitHub Milestones. A release milestone is made of GitHub Issues: -- backlog files capture raw debt and ideas -- goalposts choose which work belongs to a versioned release -- design cycles make one goalpost implementable and testable -- pull requests should normally carry one goalpost +- `type:goalpost` issues own release-scale features, invariants, or evidence + packets. +- `type:slice` issues or sub-issues own turn-sized proof work. +- Pull requests should normally carry one goalpost issue or one coherent slice + under a goalpost. -Goalposts are subdivided into slices. A slice should be small enough to finish -in one focused turn and should name its expected proof. +Goalposts and slices are tracked in GitHub, not in repo-local Markdown. -Use [docs/templates/goalpost.md](../templates/goalpost.md) for new goalposts and -[docs/templates/design-doc.md](../templates/design-doc.md) for new cycle -designs. +Use [docs/templates/design-doc.md](../templates/design-doc.md) for new cycle +designs. Use the GitHub issue forms under `.github/ISSUE_TEMPLATE/` for +goalposts, slices, bugs, debt, and ideas. -## Backlog +## GitHub Tracker -Backlog items are Markdown files. The directory lane is the priority. +GitHub owns: -### Lanes +- release membership through milestones +- work identity through issues +- priority and routing through labels +- status through issue state and labels +- parent/child relationships through sub-issues, linked issues, or task lists +- pull request linkage through closing keywords and issue references -- `inbox/` — raw capture, anyone anytime -- `asap/` — pull this soon -- `up-next/` — likely after the current pull -- `cool-ideas/` — interesting, not committed -- `bad-code/` — working debt that bothers us +Recommended label families: -Anything outside those lanes but still under `docs/method/backlog/` is an -exception surface and should be rare. +- `type:goalpost`, `type:slice`, `type:bug`, `type:debt`, `type:idea`, + `type:design`, `type:release` +- `area:storage`, `area:vault`, `area:tui`, `area:agent`, `area:docs`, + `area:security`, `area:runtime` +- `status:blocked`, `status:needs-design`, `status:ready`, + `status:in-progress`, `status:review`, `status:carried-forward` -### Naming +## Retired Repo Backlog -Use a legend prefix when the work belongs to a named domain. Do not use numeric -IDs in backlog filenames. +The former repo-local backlog is retired. Historical cards may remain under +`docs/archive/`, but active work must be promoted to GitHub Issues before it is +considered tracked. -Examples: +Do not add new work cards under `docs/method/backlog/`. Use GitHub Issues. -- `TR_streaming-encrypted-restore.md` -- `RL_agent-session-protocol.md` -- `debt-tui-layout-coupling.md` +## Promoting Work To Design -### Promoting +Pulling a GitHub Issue into a design cycle means: -Pulling a backlog item into a cycle means: - -1. remove the backlog file from its lane +1. confirm the issue is in the correct milestone and has the right type labels 2. create the next numbered cycle directory under `docs/design/` 3. write the cycle doc inside that directory - -`git-cas` cycle directories now use four-digit sequential prefixes: +4. link the design doc from the issue +5. keep issue status in GitHub, not in Markdown - `docs/design/0020-method-adoption/` - `docs/design/0021-something-else/` -The promoted backlog file does not go back. Follow-on work re-enters the -backlog as a new file if the cycle pivots or ends partial. - ### Empty-State Style For planning surfaces and legend summaries, the house empty-state phrasing is: diff --git a/docs/method/retro/0021-store-write-backpressure/enforce-store-backpressure.md b/docs/method/retro/0021-store-write-backpressure/enforce-store-backpressure.md index 522617ea..e8db8135 100644 --- a/docs/method/retro/0021-store-write-backpressure/enforce-store-backpressure.md +++ b/docs/method/retro/0021-store-write-backpressure/enforce-store-backpressure.md @@ -40,6 +40,6 @@ No design drift is currently visible inside this cycle. - No new cool-ideas card came out of this cycle. - Existing streaming follow-on work remains captured in - [TR — Streaming Decryption](../../backlog/cool-ideas/TR_streaming-decryption.md) + [TR - Streaming Decryption](../../../archive/backlog-pre-issues/cool-ideas/TR_streaming-decryption.md) and [TR — Streaming Encrypted Restore](../0027-framed-v1-streaming-restore/framed-v1-streaming-restore.md). diff --git a/docs/method/retro/0022-git-persistence-read-blob-stream/add-read-blob-stream.md b/docs/method/retro/0022-git-persistence-read-blob-stream/add-read-blob-stream.md index b8cf00a6..dad21e42 100644 --- a/docs/method/retro/0022-git-persistence-read-blob-stream/add-read-blob-stream.md +++ b/docs/method/retro/0022-git-persistence-read-blob-stream/add-read-blob-stream.md @@ -38,4 +38,4 @@ No design drift is visible inside this cycle. - Existing follow-on streaming work remains captured in [TR — Streaming Encrypted Restore](../0027-framed-v1-streaming-restore/framed-v1-streaming-restore.md) and - [TR — Streaming Decryption](../../backlog/cool-ideas/TR_streaming-decryption.md). + [TR - Streaming Decryption](../../../archive/backlog-pre-issues/cool-ideas/TR_streaming-decryption.md). diff --git a/docs/method/retro/0023-casservice-read-blob-stream-integration/use-read-blob-stream-in-restore.md b/docs/method/retro/0023-casservice-read-blob-stream-integration/use-read-blob-stream-in-restore.md index 81655d74..f2408d1d 100644 --- a/docs/method/retro/0023-casservice-read-blob-stream-integration/use-read-blob-stream-in-restore.md +++ b/docs/method/retro/0023-casservice-read-blob-stream-integration/use-read-blob-stream-in-restore.md @@ -39,4 +39,4 @@ No design drift is visible inside this cycle. - Existing follow-on streaming work remains captured in [TR — Streaming Encrypted Restore](../0027-framed-v1-streaming-restore/framed-v1-streaming-restore.md) and - [TR — Streaming Decryption](../../backlog/cool-ideas/TR_streaming-decryption.md). + [TR - Streaming Decryption](../../../archive/backlog-pre-issues/cool-ideas/TR_streaming-decryption.md). diff --git a/docs/templates/design-doc.md b/docs/templates/design-doc.md index b2660df9..b3871820 100644 --- a/docs/templates/design-doc.md +++ b/docs/templates/design-doc.md @@ -24,8 +24,9 @@ cycle: "" task_id: "" legend: "" release_home: "vX.Y.Z|none" -goalpost: "docs/goalposts/vX.Y.Z/.md|none" -issue: "https://github.com/git-stunts/git-cas/issues/|not opened yet" +issue: "https://github.com/git-stunts/git-cas/issues/" +goalpost_issue: "https://github.com/git-stunts/git-cas/issues/|none" +tracker_source: "github" status: "draft|active|landed|superseded" base_commit: "" owners: @@ -41,19 +42,23 @@ updated: "YYYY-MM-DD" --- ``` -Status meanings: +Status meanings are local design-doc lifecycle states only. They do not replace +GitHub Issue state: - `draft`: not yet committed as active work. - `active`: pulled into a cycle; sponsors own the hill. - `landed`: implementation and witness evidence merged or otherwise complete. - `superseded`: replaced by another design; `superseded_by` points at it. +GitHub Issues remain the canonical tracker for open, blocked, active, review, +carried-forward, and closed work. + ## Required Sections Every new cycle design doc must include these sections: - Linked Issue -- Linked Goalpost +- Linked Tracker - Design Type - Decision Summary - Sponsored Human @@ -134,8 +139,9 @@ cycle: "" task_id: "" legend: "" release_home: "vX.Y.Z|none" -goalpost: "docs/goalposts/vX.Y.Z/.md|none" -issue: "https://github.com/git-stunts/git-cas/issues/|not opened yet" +issue: "https://github.com/git-stunts/git-cas/issues/" +goalpost_issue: "https://github.com/git-stunts/git-cas/issues/|none" +tracker_source: "github" status: "draft|active|landed|superseded" base_commit: "" owners: @@ -154,11 +160,13 @@ updated: "YYYY-MM-DD" ## Linked Issue -- `not opened yet` +- https://github.com/git-stunts/git-cas/issues/ -## Linked Goalpost +## Linked Tracker -- `docs/goalposts/vX.Y.Z/.md` +- Milestone: `vX.Y.Z` +- Goalpost issue: https://github.com/git-stunts/git-cas/issues/ +- Slice issues: https://github.com/git-stunts/git-cas/issues/ ## Design Type @@ -420,14 +428,13 @@ Mitigations: ## Follow-On Debt -Create GitHub issues or backlog files for anything deferred. Do not hide future -work in prose. +Create GitHub issues for anything deferred. Do not hide future work in prose. ## Tracker Disposition | Issue | Role | Expected disposition | | --- | --- | --- | -| not opened yet | primary / blocks / blocked-by / follow-on | close / update / leave open / create follow-up | +| https://github.com/git-stunts/git-cas/issues/ | primary / blocks / blocked-by / follow-on | close / update / leave open / create follow-up | ## Done Does Not Mean @@ -441,5 +448,5 @@ Fill this in after implementation. PR: -- `not opened yet` +- https://github.com/git-stunts/git-cas/pull/ ```` diff --git a/docs/templates/goalpost.md b/docs/templates/goalpost.md deleted file mode 100644 index 7fb56480..00000000 --- a/docs/templates/goalpost.md +++ /dev/null @@ -1,115 +0,0 @@ -# Goalpost Template - -Copy this skeleton when creating a `git-cas` release goalpost. - -Goalposts sit between the release roadmap and METHOD design cycles. They name a -release-scale outcome, divide it into turn-sized slices, and point to the proof -that must exist before a pull request can land. One pull request should carry -one goalpost. - -````markdown -# - -## Identity - -| Field | Value | -| --- | --- | -| Goalpost id | `` | -| Release home | `vX.Y.Z` | -| Umbrella issue | `https://github.com/git-stunts/git-cas/issues/` or `not opened yet` | -| Goalpost doc | `` | -| Design cycle | `` or `not active yet` | -| Slice budget | `` | -| Status | `planned|scaffolded|active|review-ready|landed|superseded` | -| Sponsor human | `` | -| Sponsor agent | `` | - -## Outcome - -State the release-scale outcome this goalpost unlocks. - -## Current Truth - -Cite current repo-visible facts. Strong claims need source, test, command, -issue, pull request, generated artifact, witness, release note, or CI evidence. - -## Scope - -- `` - -## Out Of Scope - -- `` - -## Proof Stories - -Use the proof-story form: - -```text -A needs -so that , -without relying on . -``` - -| Story issue | Actor | Need | Reason | Slice budget | -| --- | --- | --- | --- | ---: | -| `not opened yet` | `` | `` | `` | `` | - -## Slice Budget - -| Slice | Status | Description | Expected proof | -| ---: | --- | --- | --- | -| 1 | open | `` | `` | - -## Acceptance Criteria - -- [ ] `` - -## Deterministic Evidence - -| Claim | Canonical fixture or input | Witness | Replay command | Expected deterministic result | -| --- | --- | --- | --- | --- | -| `` | `` | `` | `` | `` | - -## Substrate / Residency Geometry - -Name the Git substrate basis, aperture, materialization law, projection, support -obligations, budget posture, residual posture, and witness posture for any claim -about refs, commits, trees, blobs, manifests, vaults, or large-content reads. - -| Reading claim | Basis | Aperture | Law/projection | Support obligations | Witness posture | -| --- | --- | --- | --- | --- | --- | -| `` | `` | `` | `` | `` | `` | - -## Validation Plan - -```bash -npx eslint . -npm test -npm run release:verify -- --skip-jsr -``` - -Trim commands that do not apply. Add focused tests, fixtures, Docker runtime -commands, or witness replay commands when needed. - -## Release Gate Impact - -Describe how this goalpost affects the target release gate, release evidence -packet, changelog, docs, package surface, migration posture, or runtime matrix. - -## Residual Risks - -| Risk | Rationale | Owner | Follow-up issue | -| --- | --- | --- | --- | -| `None` | `No accepted residual risks.` | `n/a` | `n/a` | - -## Closeout - -- [ ] Slices complete or honestly dispositioned. -- [ ] Proof matrix replayed. -- [ ] Goalpost issue updated. -- [ ] Child proof-story issues closed, superseded, or carried forward. -- [ ] Pull request merged for this goalpost. -- [ ] Release evidence updated when release-relevant. -- [ ] Retrospective or closeout note written. -```` diff --git a/test/unit/docs/casservice-decomposition.test.js b/test/unit/docs/casservice-decomposition.test.js index 98875df7..1534c5ff 100644 --- a/test/unit/docs/casservice-decomposition.test.js +++ b/test/unit/docs/casservice-decomposition.test.js @@ -36,7 +36,7 @@ describe('CasService decomposition boundary', () => { it('keeps audit and status docs aligned with the completed de-sludge', () => { const audit = read('docs/audit/2026-05-05_v6-release-readiness.md'); - const releaseBlocker = read('docs/method/backlog/v6.0.0/REL_audit-blocker-burn-down.md'); + const releaseBlocker = read('docs/archive/backlog-pre-issues/v6.0.0/REL_audit-blocker-burn-down.md'); const status = read('STATUS.md'); expect(audit).toContain('ISSUE-001: CasService.js Logic Leak'); @@ -51,7 +51,7 @@ describe('CasService decomposition boundary', () => { it('keeps architecture and backlog docs aligned with the extracted strategy layout', () => { const architecture = read('ARCHITECTURE.md'); const guide = read('GUIDE.md'); - const backlog = read('docs/method/backlog/bad-code/BAD-CODE-001_casservice-god-object.md'); + const backlog = read('docs/archive/backlog-pre-issues/bad-code/BAD-CODE-001_casservice-god-object.md'); expect(architecture.match(/^#### Value Objects \(`src\/domain\/value-objects\/`\)$/gm)).toHaveLength(1); expect(guide).toMatch(/Lean domain\s+facade/); diff --git a/test/unit/docs/markdown-links.test.js b/test/unit/docs/markdown-links.test.js index d4786348..150155ff 100644 --- a/test/unit/docs/markdown-links.test.js +++ b/test/unit/docs/markdown-links.test.js @@ -8,7 +8,9 @@ const markdownLinkIt = existsSync(path.join(repoRoot, '.git')) ? it : it.skip; function trackedMarkdownFiles() { const output = execFileSync('git', ['ls-files', '*.md'], { encoding: 'utf8' }).trim(); - return output ? output.split('\n') : []; + return output + ? output.split('\n').filter((file) => existsSync(path.join(repoRoot, file))) + : []; } function stripCodeFences(markdown) { diff --git a/test/unit/docs/planning-surfaces.test.js b/test/unit/docs/planning-surfaces.test.js index 3be41c73..cbe267db 100644 --- a/test/unit/docs/planning-surfaces.test.js +++ b/test/unit/docs/planning-surfaces.test.js @@ -43,27 +43,6 @@ function assertLocalMarkdownLinksExist(file) { expect(missing).toEqual([]); } -function statusLine(markdown) { - return markdown.match(/^-\s+\*\*Status\*\*:\s*(.+)$/mu)?.[1] ?? ''; -} - -function activeLinksForLane(markdown, lane) { - const body = sectionBody(markdown, `### \`${lane}/\``); - const activeStart = body.indexOf('Active:'); - if (activeStart === -1) { - return []; - } - const activeBody = body.slice(activeStart); - const resolvedStart = activeBody.indexOf('\nResolved'); - return markdownLinks(resolvedStart === -1 ? activeBody : activeBody.slice(0, resolvedStart)); -} - -function laneFiles(lane) { - return readdirSync(path.join(repoRoot, 'docs/method/backlog', lane)) - .filter((name) => !name.startsWith('.')) - .sort(); -} - function cycleDirs() { return readdirSync(path.join(repoRoot, 'docs/design'), { withFileTypes: true }) .filter((entry) => entry.isDirectory() && /^\d{4}-/.test(entry.name)) @@ -72,33 +51,37 @@ function cycleDirs() { } describe('planning surfaces', () => { // eslint-disable-line max-lines-per-function - it('uses the canonical empty-state bullet across planning surfaces', () => { + it('keeps GitHub Issues named as the canonical work tracker', () => { const checks = [ - ['docs/design/README.md', '## Landed METHOD Cycles'], - ['docs/method/backlog/README.md', "### `inbox/`"], - ['docs/legends/RL-relay.md', '## Current METHOD Backlog'], - ['docs/method/legends/RL_relay.md', '## Current Backlog'], + ['ROADMAP.md', 'GitHub Issues and Milestones are the source of truth'], + ['WORKFLOW.md', 'Work tracking truth lives in GitHub Issues and Milestones'], + ['docs/method/process.md', 'If it is actionable work, it must be a GitHub Issue'], + ['docs/method/backlog/README.md', 'This directory is no longer an active work tracker'], + ['docs/method/legends/TR_truth.md', 'GitHub Issues and Milestones own current Truth work'], + ['docs/legends/TR-truth.md', 'GitHub Issues and Milestones own current Truth work'], ]; - for (const [file, heading] of checks) { - expect(sectionBody(read(file), heading)).toContain('- none currently'); + for (const [file, expected] of checks) { + expect(read(file)).toContain(expected); } }); - it('keeps the backlog index in sync with the live lane files', () => { - const backlog = read('docs/method/backlog/README.md'); - - const expectations = [ - ['### `asap/`', laneFiles('asap')], - ['### `up-next/`', laneFiles('up-next')], - ['### `cool-ideas/`', laneFiles('cool-ideas')], - ['### `bad-code/`', laneFiles('bad-code')], + it('publishes GitHub issue forms for canonical tracker work types', () => { + const forms = [ + '.github/ISSUE_TEMPLATE/goalpost.yml', + '.github/ISSUE_TEMPLATE/slice.yml', + '.github/ISSUE_TEMPLATE/bug.yml', + '.github/ISSUE_TEMPLATE/debt.yml', + '.github/ISSUE_TEMPLATE/idea.yml', ]; - for (const [heading, files] of expectations) { - const links = markdownLinks(sectionBody(backlog, heading)).map((link) => path.basename(link)).sort(); - expect(links).toEqual(files); + for (const form of forms) { + expect(existsSync(path.join(repoRoot, form))).toBe(true); } + + expect(read('.github/ISSUE_TEMPLATE/goalpost.yml')).toContain('type:goalpost'); + expect(read('.github/ISSUE_TEMPLATE/slice.yml')).toContain('type:slice'); + expect(read('docs/method/process.md')).toContain('.github/ISSUE_TEMPLATE/'); }); it('keeps the active design index in sync with numbered cycle directories', () => { @@ -110,36 +93,39 @@ describe('planning surfaces', () => { // eslint-disable-line max-lines-per-funct expect(links).toEqual(cycleDirs()); }); - it('does not list resolved bad-code cards under Active', () => { + it('keeps the retired repo backlog from acting like a live queue', () => { const backlog = read('docs/method/backlog/README.md'); - const resolvedActiveCards = activeLinksForLane(backlog, 'bad-code') - .map((link) => path.normalize(path.join('docs/method/backlog', link))) - .filter((file) => statusLine(read(file)).startsWith('Resolved')); - expect(resolvedActiveCards).toEqual([]); + expect(backlog).toContain('Do not add new work cards here.'); + expect(backlog).toContain('docs/archive/backlog-pre-issues/'); + expect(backlog).not.toContain('bad-code/'); + expect(backlog).not.toContain('cool-ideas/'); + assertLocalMarkdownLinksExist('docs/method/backlog/README.md'); }); - it('keeps current legend backlog links pointed at real backlog files', () => { + it('keeps current legend tracker summaries out of repo-local backlog lanes', () => { const files = [ 'docs/method/legends/TR_truth.md', + 'docs/method/legends/RL_relay.md', 'docs/legends/TR-truth.md', + 'docs/legends/RL-relay.md', ]; for (const file of files) { - const section = sectionBody(read(file), '## Current Backlog') || sectionBody(read(file), '## Current METHOD Backlog'); - const links = markdownLinks(section); - for (const link of links) { - expect(() => read(path.join(path.dirname(file), link))).not.toThrow(); - } + const section = sectionBody(read(file), '## Current Tracker') + || sectionBody(read(file), '## Current METHOD Tracker'); + expect(section).toContain('GitHub Issues and Milestones'); + expect(section).not.toContain('method/backlog'); + assertLocalMarkdownLinksExist(file); } }); - it('keeps roadmap goalpost links pointed at real planning docs', () => { + it('keeps roadmap and process links pointed at real repo docs', () => { const files = [ 'ROADMAP.md', 'WORKFLOW.md', - 'docs/goalposts/README.md', 'docs/method/process.md', + 'docs/templates/design-doc.md', ]; for (const file of files) { diff --git a/test/unit/docs/release-state.test.js b/test/unit/docs/release-state.test.js index 6bf25870..45ed41ee 100644 --- a/test/unit/docs/release-state.test.js +++ b/test/unit/docs/release-state.test.js @@ -25,7 +25,7 @@ describe('release state docs', () => { }); it('keeps the v6 release checklist evidence current with the pre-tag candidate', () => { - const releaseCard = read('docs/method/backlog/v6.0.0/REL_version-bump.md'); + const releaseCard = read('docs/archive/backlog-pre-issues/v6.0.0/REL_version-bump.md'); expect(releaseCard).toContain('v6 release-readiness polish'); expect(releaseCard).toMatch(/168\s+files, 1502 passed, 2 skipped/); From 106d4a84801be66e78447d25d0b1fa4665e3b5f5 Mon Sep 17 00:00:00 2001 From: James Ross Date: Sat, 13 Jun 2026 01:49:21 -0700 Subject: [PATCH 3/5] docs: clean root documentation truth --- CHANGELOG.md | 4 ++++ CLAUDE.md | 32 +------------------------------- GRAVEYARD.md | 31 ------------------------------- README.md | 2 +- STATUS.md | 2 +- docs/MARKDOWN_SURFACE.md | 14 ++++++-------- 6 files changed, 13 insertions(+), 72 deletions(-) delete mode 100644 GRAVEYARD.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 89e9be8b..b3ae0f44 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 and follow-on work now live in GitHub Issues and Milestones. Repo Markdown carries design docs, witnesses, release history, public docs, and archived planning source material, but does not own the active queue. +- **Root-doc accuracy cleanup** — the README product statement is now + version-neutral, `STATUS.md` records the latest docs validation snapshot, + `CLAUDE.md` delegates to `AGENTS.md`, and the stale root `GRAVEYARD.md` file + has been removed. ## [6.0.1] — 2026-05-09 diff --git a/CLAUDE.md b/CLAUDE.md index db85e6e2..ad122aab 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,31 +1 @@ -# CLAUDE.md — Project Instructions - -## Quality Policy - -**Zero tolerance for failing tests.** Pre-existing failures are not acceptable. If any test fails on any supported runtime (Node, Bun, Deno), it must be fixed before proceeding. Never skip, ignore, or defer a failing test. - -## Supported Runtimes - -All code must pass on all three runtimes: -- Node.js 22.x (primary) -- Bun (via Docker: `docker compose run --build --rm test-bun`) -- Deno (via Docker: `docker compose run --build --rm test-deno`) - -## Test Commands - -- `npm test` — unit tests (Node) -- `npx eslint .` — lint (0 errors required) -- `docker compose run --build --rm test-bun bunx vitest run test/unit` — Bun unit tests -- `docker compose run --build --rm test-deno deno run -A npm:vitest run test/unit` — Deno unit tests -- `docker compose run --build --rm test-bun bunx vitest run test/integration` — Bun integration tests -- `docker compose run --build --rm test-deno deno run -A npm:vitest run test/integration` — Deno integration tests - -## Release Checklist - -Before tagging a release, ALL of the following must pass: -1. `npx eslint .` — 0 errors -2. `npm test` — all tests pass (Node) -3. Bun unit + integration tests pass -4. Deno unit + integration tests pass -5. `npm pack --dry-run` — clean -6. `npx jsr publish --dry-run --allow-dirty` — clean, unless a documented upstream JSR/Deno toolchain failure prevents package validation from starting. In that case, run `npm run release:verify -- --skip-jsr`, record the skipped step, and keep JSR publishing out of the tag workflow until the dry-run is healthy again. +See [AGENTS.md](./AGENTS.md) diff --git a/GRAVEYARD.md b/GRAVEYARD.md deleted file mode 100644 index c8aa19e8..00000000 --- a/GRAVEYARD.md +++ /dev/null @@ -1,31 +0,0 @@ -# Task Graveyard - -Tasks moved here from ROADMAP.md because they were superseded or duplicated by other work. - ---- - -## Task 8.1: Streaming restore *(superseded by Task 14.2)* - -**Originally in:** M8 — Spit Shine (v2.1.0) - -**Superseded by:** Task 14.2 (Streaming restore) in M14 — Conduit (v4.0.0) - -**Reason:** Task 14.2 implemented all of Task 8.1's requirements plus additional integration with ObservabilityPort metrics/spans and the `restoreStream()` → `restore()` unification. The M14 version is strictly a superset. - -**User Story** -As a developer restoring large files, I want a streaming restore path so I don't buffer the entire file in memory. - -**Requirements** -- R1: Add `CasService.restoreStream({ manifest, encryptionKey, passphrase })` returning `AsyncIterable`. -- R2: Each yielded buffer is one verified, decrypted, decompressed chunk — ready to write. -- R3: Integrity verified per-chunk before yield (not after full reassembly). -- R4: Decompression and decryption applied per-chunk in streaming fashion. -- R5: `restoreFile()` in the facade uses `restoreStream()` internally with `createWriteStream()` instead of `writeFileSync()`. -- R6: Existing `restore()` method remains unchanged (returns `{ buffer, bytesWritten }`) for backward compat. - -**Acceptance Criteria** -- AC1: `restoreStream()` yields chunks that, when concatenated, match the original file byte-for-byte. -- AC2: Memory usage during streaming restore is O(chunkSize), not O(fileSize). -- AC3: `restoreFile()` writes via stream and does not call `writeFileSync()`. -- AC4: Encrypted + compressed files round-trip correctly via streaming restore. -- AC5: Existing `restore()` method behavior unchanged. diff --git a/README.md b/README.md index 259451db..ba9b904f 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ > > `git-cas` addresses this by making artifact distribution inherit Git’s existing replication model, allowing binaries to be stored, verified, and transported anywhere Git can operate, including mirrored networks, constrained environments, or fully offline contexts. -`git-cas` 6.0.0 is an industrial-grade Content-Addressable Storage (CAS) engine backed by Git’s object database. Its Security First posture makes explicit restore boundaries, bounded metadata reads, authenticated encryption, and legacy-scheme rejection the default. Stored content is chunked, deduplicated, and optionally encrypted — keeping high-fidelity assets and security-sensitive files directly within your repository history. +`git-cas` is an industrial-grade Content-Addressable Storage (CAS) engine backed by Git’s object database. Its Security First posture makes explicit restore boundaries, bounded metadata reads, authenticated encryption, and legacy-scheme rejection the default. Stored content is chunked, deduplicated, and optionally encrypted — keeping high-fidelity assets and security-sensitive files directly within your repository history. `git-cas` is designed for the architect who demands mathematical certainty and the operator who needs a stable foundation for artifact storage. It scales from simple binary blob management to multi-recipient envelope-encrypted vaults with key rotation, privacy-mode slug hashing, and Merkle-style manifests for assets of any size. diff --git a/STATUS.md b/STATUS.md index 0a98a114..0b824e2d 100644 --- a/STATUS.md +++ b/STATUS.md @@ -2,7 +2,7 @@ **Last tagged release:** `v6.0.0` (`2026-05-09`) **Current release state:** `v6.0.1` patch candidate on `main`; `v6.0.0` is published to npm and GitHub Releases, and JSR publication is deferred for the v6.0.x line. -**Latest verification:** `npm run release:verify -- --skip-jsr` passed 12/12 steps with 5,383 observed tests. +**Latest verification:** root-doc cleanup: `npx eslint .` and `npm test` passed on `2026-06-13` (`187` files, `1,644` passed, `2` skipped). **Playback truth:** `main` **Runtimes:** Node.js 22.x, Bun, Deno **Current planning method:** [WORKFLOW.md](./WORKFLOW.md) diff --git a/docs/MARKDOWN_SURFACE.md b/docs/MARKDOWN_SURFACE.md index f8411589..3955bc0e 100644 --- a/docs/MARKDOWN_SURFACE.md +++ b/docs/MARKDOWN_SURFACE.md @@ -43,10 +43,10 @@ local-only surfaces. shortest path from current state to planned releases. - [STATUS.md](../STATUS.md): `KEEP`, `MERGE` — compact snapshot value is real, but it should stay derivative and slim. -- [GRAVEYARD.md](../GRAVEYARD.md): `KEEP`, `MOVE` — still useful historical - context, but it belongs under `docs/archive/` instead of the repo root. -- [CLAUDE.md](../CLAUDE.md): `CUT`, `MOVE` — tool-specific instruction files - should not occupy tracked root doctrine alongside canonical project docs. +- `GRAVEYARD.md`: `CUT` — removed from the root; stale historical task text no + longer occupies a tracked planning surface. +- [CLAUDE.md](../CLAUDE.md): `KEEP` — compatibility pointer only; canonical + agent/operator instructions live in [AGENTS.md](../AGENTS.md). ## Canonical Docs Under `docs/` @@ -235,10 +235,8 @@ change: If the repo wants to act on this audit, the highest-value next changes are: -1. move [GRAVEYARD.md](../GRAVEYARD.md) under `docs/archive/` -2. decide whether [CLAUDE.md](../CLAUDE.md) should leave tracked root entirely -3. collapse [STATUS.md](../STATUS.md) into other canonical surfaces and remove +1. collapse [STATUS.md](../STATUS.md) into other canonical surfaces and remove the duplicate snapshot doc -4. keep [ROADMAP.md](../ROADMAP.md), GitHub milestones/issues, and +2. keep [ROADMAP.md](../ROADMAP.md), GitHub milestones/issues, and [docs/design/](./design/README.md) synchronized as the release planning stack evolves From fa2bdeda640b6648855ec17ae76e3c194d492701 Mon Sep 17 00:00:00 2001 From: James Ross Date: Sat, 13 Jun 2026 02:08:25 -0700 Subject: [PATCH 4/5] docs: resolve tracker review findings --- .github/ISSUE_TEMPLATE/bug.yml | 2 +- .github/ISSUE_TEMPLATE/config.yml | 2 +- .github/ISSUE_TEMPLATE/debt.yml | 2 +- .github/ISSUE_TEMPLATE/goalpost.yml | 6 +-- .github/ISSUE_TEMPLATE/slice.yml | 2 +- .github/pull_request_template.md | 3 +- .gitignore | 1 - AGENTS.md | 65 +++++++++++++++++++++++++++ CONTRIBUTING.md | 4 +- STATUS.md | 2 +- docs/MARKDOWN_SURFACE.md | 4 +- docs/method/process.md | 7 +-- test/unit/docs/markdown-links.test.js | 4 +- 13 files changed, 84 insertions(+), 20 deletions(-) create mode 100644 AGENTS.md diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml index d4cb0aa8..e1bef86e 100644 --- a/.github/ISSUE_TEMPLATE/bug.yml +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -24,7 +24,7 @@ body: label: Evidence description: Commands, files, logs, tests, screenshots, or examples. value: | - - + - validations: required: true - type: dropdown diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index c20c6921..a55f392d 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,4 +1,4 @@ -blank_issues_enabled: true +blank_issues_enabled: false contact_links: - name: Security vulnerability url: mailto:james@flyingrobots.dev diff --git a/.github/ISSUE_TEMPLATE/debt.yml b/.github/ISSUE_TEMPLATE/debt.yml index c8fd3893..6f479ba8 100644 --- a/.github/ISSUE_TEMPLATE/debt.yml +++ b/.github/ISSUE_TEMPLATE/debt.yml @@ -30,7 +30,7 @@ body: attributes: label: Proof needed value: | - - + - validations: required: true - type: input diff --git a/.github/ISSUE_TEMPLATE/goalpost.yml b/.github/ISSUE_TEMPLATE/goalpost.yml index 724680c5..372adef1 100644 --- a/.github/ISSUE_TEMPLATE/goalpost.yml +++ b/.github/ISSUE_TEMPLATE/goalpost.yml @@ -37,7 +37,7 @@ body: label: Scope description: What is included? value: | - - + - validations: required: true - type: textarea @@ -46,7 +46,7 @@ body: label: Out of scope description: What is explicitly excluded? value: | - - + - validations: required: true - type: textarea @@ -73,7 +73,7 @@ body: label: Required proof description: Tests, fixtures, witnesses, schemas, commands, or release evidence required before closeout. value: | - - + - validations: required: true - type: textarea diff --git a/.github/ISSUE_TEMPLATE/slice.yml b/.github/ISSUE_TEMPLATE/slice.yml index 8aacf81e..1e983444 100644 --- a/.github/ISSUE_TEMPLATE/slice.yml +++ b/.github/ISSUE_TEMPLATE/slice.yml @@ -32,7 +32,7 @@ body: label: Expected proof description: What proves this slice is done? value: | - - + - validations: required: true - type: textarea diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 0e3d4803..7fc99170 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,6 +1,7 @@ ## Linked Issue -- Closes # +- Refs # +- Closes # only when this PR completes the issue. ## Design / Proof diff --git a/.gitignore b/.gitignore index 8e9e3a95..6d7d63e7 100644 --- a/.gitignore +++ b/.gitignore @@ -9,7 +9,6 @@ coverage/ .obsidian/ .codex/ lastchat.txt -AGENTS.md EDITORS-REPORT EDITORS-REPORT.* CODE-EVAL.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..b0a1793c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,65 @@ +# AGENTS + +This guide is for AI agents and human operators recovering context in the +`git-cas` repository. + +## Git Rules + +- **NEVER** amend commits. +- **NEVER** rebase or force-push. +- **NEVER** push to `main` without explicit permission. +- Always use standard commits and regular pushes. + +## Documentation & Planning Map + +Do not audit the repository by recursively walking the filesystem. Follow the +authoritative manifests: + +### 1. The Entrance + +- **`README.md`**: Public front door, core value prop, and quick start. +- **`GUIDE.md`**: Orientation and productive-fast path. +- **`docs/WALKTHROUGH.md`**: Long-form manual and examples. + +### 2. The Bedrock + +- **`ARCHITECTURE.md`**: The authoritative structural reference (Facade, + Domain, Ports). +- **`VISION.md`**: Core tenets and project identity. +- **`WORKFLOW.md`** and **`docs/method/process.md`**: Repo work doctrine. + +### 3. The Direction + +- **`BEARING.md`**: Current execution gravity and active tensions. +- **GitHub Issues and Milestones**: Active source of truth for pending work. +- **`ROADMAP.md`**: Signpost to the GitHub release tracker. +- **`docs/design/`**: Durable design contracts and proof plans. + +### 4. The Proof + +- **`CHANGELOG.md`**: Historical truth of merged behavior. +- **`STATUS.md`**: Compact snapshot of release and runtime truth. + +## Context Recovery Protocol + +When starting a new session or recovering from context loss: + +1. **Read `BEARING.md`** to find the current execution gravity. +2. **Read `WORKFLOW.md` and `docs/method/process.md`** to understand the work + doctrine. +3. **Check GitHub Issues and Milestones** for tracked work. +4. **Check `ROADMAP.md`** for release-train orientation. +5. **Check `git log -n 5` and `git status`** to verify the current branch state. + +## End of Turn Checklist + +After altering files: + +1. **Verify Truth**: Ensure documentation is updated if behavior or structure + changed. +2. **Log Debt**: Add follow-on work as GitHub Issues. +3. **Commit**: Use focused, conventional commit messages. +4. **Validate**: Run `npm test` and `npx eslint .`. + +--- +**The goal is inevitably. Every feature is defined by its tests.** diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f85ff7bf..c56651df 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -131,13 +131,11 @@ that checklist pass. ## Directory Model -New planning work uses: +Fresh work uses: - GitHub Issues and Milestones -- [`docs/method/backlog/`](./docs/method/backlog/README.md) - [`docs/method/legends/`](./docs/method/legends/README.md) - [`docs/method/retro/`](./docs/method/retro/README.md) -- [`docs/method/graveyard/`](./docs/method/graveyard/README.md) - [`docs/design/`](./docs/design/) - [`docs/invariants/`](./docs/invariants/) - [`test/cycles/`](./test/cycles/) diff --git a/STATUS.md b/STATUS.md index 0b824e2d..7252a6dc 100644 --- a/STATUS.md +++ b/STATUS.md @@ -2,7 +2,7 @@ **Last tagged release:** `v6.0.0` (`2026-05-09`) **Current release state:** `v6.0.1` patch candidate on `main`; `v6.0.0` is published to npm and GitHub Releases, and JSR publication is deferred for the v6.0.x line. -**Latest verification:** root-doc cleanup: `npx eslint .` and `npm test` passed on `2026-06-13` (`187` files, `1,644` passed, `2` skipped). +**Latest local verification:** PR #47 review cleanup on `2026-06-13`: `git diff --check`, focused docs tests, `npx eslint .`, and `npm test` passed. GitHub PR CI remains the merge gate. **Playback truth:** `main` **Runtimes:** Node.js 22.x, Bun, Deno **Current planning method:** [WORKFLOW.md](./WORKFLOW.md) diff --git a/docs/MARKDOWN_SURFACE.md b/docs/MARKDOWN_SURFACE.md index 3955bc0e..5498db2c 100644 --- a/docs/MARKDOWN_SURFACE.md +++ b/docs/MARKDOWN_SURFACE.md @@ -47,6 +47,9 @@ local-only surfaces. longer occupies a tracked planning surface. - [CLAUDE.md](../CLAUDE.md): `KEEP` — compatibility pointer only; canonical agent/operator instructions live in [AGENTS.md](../AGENTS.md). +- [AGENTS.md](../AGENTS.md): `KEEP` — canonical agent/operator recovery, + Git, and playback instructions; tracked because compatibility pointers route + here. ## Canonical Docs Under `docs/` @@ -226,7 +229,6 @@ These files are not part of the tracked Markdown audit and should remain out of the canonical tracked doctrine surface unless the repo makes an explicit policy change: -- `AGENTS.md` - `EDITORS-REPORT.md` - `.claude/bad_code.md` - `.claude/cool_ideas.md` diff --git a/docs/method/process.md b/docs/method/process.md index 382964c4..dc5f8cd5 100644 --- a/docs/method/process.md +++ b/docs/method/process.md @@ -160,8 +160,8 @@ If a posture is not relevant, say so explicitly. ### The Loop -0. Pull the work from the backlog and own it. -1. Write the design doc in `docs/design//`. +0. Select or open the canonical GitHub Issue and own it. +1. Write or revise the design doc in `docs/design//`. 2. Write failing tests. Default to the agent surface first unless the design explicitly says otherwise. 3. Make the tests pass. @@ -169,7 +169,8 @@ If a posture is not relevant, say so explicitly. playback questions for both the human and agent views. 5. Open the PR and iterate until merge. 6. After merge, write the retro in `docs/method/retro//.md`, - perform the drift check, and feed new debt or ideas back into the backlog. + perform the drift check, and open GitHub follow-up issues for new debt or + ideas. ## Playback And Witness diff --git a/test/unit/docs/markdown-links.test.js b/test/unit/docs/markdown-links.test.js index 150155ff..d4786348 100644 --- a/test/unit/docs/markdown-links.test.js +++ b/test/unit/docs/markdown-links.test.js @@ -8,9 +8,7 @@ const markdownLinkIt = existsSync(path.join(repoRoot, '.git')) ? it : it.skip; function trackedMarkdownFiles() { const output = execFileSync('git', ['ls-files', '*.md'], { encoding: 'utf8' }).trim(); - return output - ? output.split('\n').filter((file) => existsSync(path.join(repoRoot, file))) - : []; + return output ? output.split('\n') : []; } function stripCodeFences(markdown) { From b3aaedcd23d8b07dc6753c38f87c763d9e0157db Mon Sep 17 00:00:00 2001 From: James Ross Date: Sat, 13 Jun 2026 02:18:02 -0700 Subject: [PATCH 5/5] Fix: align archived goalpost identity paths --- .../v6.0.1/release-truth-closeout.md | 2 +- .../v6.1.0/bounded-residency.md | 2 +- .../v6.2.0/operator-tui.md | 2 +- .../v6.3.0/agent-automation-parity.md | 2 +- .../v6.4.0/browser-edge-read-path.md | 2 +- .../v7.0.0/protocol-audit-response.md | 2 +- test/unit/docs/planning-surfaces.test.js | 18 ++++++++++++++++++ 7 files changed, 24 insertions(+), 6 deletions(-) diff --git a/docs/archive/goalposts-pre-issues/v6.0.1/release-truth-closeout.md b/docs/archive/goalposts-pre-issues/v6.0.1/release-truth-closeout.md index 73a74cd5..c76a4d98 100644 --- a/docs/archive/goalposts-pre-issues/v6.0.1/release-truth-closeout.md +++ b/docs/archive/goalposts-pre-issues/v6.0.1/release-truth-closeout.md @@ -7,7 +7,7 @@ | Goalpost id | `v6.0.1-gp-release-truth-closeout` | | Release home | `v6.0.1` | | Umbrella issue | `not opened yet` | -| Goalpost doc | `docs/goalposts/v6.0.1/release-truth-closeout.md` | +| Goalpost doc | `docs/archive/goalposts-pre-issues/v6.0.1/release-truth-closeout.md` | | Design cycle | `not active yet` | | Slice budget | `3` | | Status | `scaffolded` | diff --git a/docs/archive/goalposts-pre-issues/v6.1.0/bounded-residency.md b/docs/archive/goalposts-pre-issues/v6.1.0/bounded-residency.md index eba88a5d..2ed1dd78 100644 --- a/docs/archive/goalposts-pre-issues/v6.1.0/bounded-residency.md +++ b/docs/archive/goalposts-pre-issues/v6.1.0/bounded-residency.md @@ -7,7 +7,7 @@ | Goalpost id | `v6.1.0-gp-bounded-residency` | | Release home | `v6.1.0` | | Umbrella issue | `not opened yet` | -| Goalpost doc | `docs/goalposts/v6.1.0/bounded-residency.md` | +| Goalpost doc | `docs/archive/goalposts-pre-issues/v6.1.0/bounded-residency.md` | | Design cycle | `docs/design/0045-v6-1-bounded-residency/bounded-residency.md` | | Slice budget | `5` | | Status | `scaffolded` | diff --git a/docs/archive/goalposts-pre-issues/v6.2.0/operator-tui.md b/docs/archive/goalposts-pre-issues/v6.2.0/operator-tui.md index 5959e79d..8bfff71e 100644 --- a/docs/archive/goalposts-pre-issues/v6.2.0/operator-tui.md +++ b/docs/archive/goalposts-pre-issues/v6.2.0/operator-tui.md @@ -7,7 +7,7 @@ | Goalpost id | `v6.2.0-gp-operator-tui` | | Release home | `v6.2.0` | | Umbrella issue | `not opened yet` | -| Goalpost doc | `docs/goalposts/v6.2.0/operator-tui.md` | +| Goalpost doc | `docs/archive/goalposts-pre-issues/v6.2.0/operator-tui.md` | | Design cycle | `not active yet` | | Slice budget | `6` | | Status | `planned` | diff --git a/docs/archive/goalposts-pre-issues/v6.3.0/agent-automation-parity.md b/docs/archive/goalposts-pre-issues/v6.3.0/agent-automation-parity.md index 5b981ba2..b190b2cf 100644 --- a/docs/archive/goalposts-pre-issues/v6.3.0/agent-automation-parity.md +++ b/docs/archive/goalposts-pre-issues/v6.3.0/agent-automation-parity.md @@ -7,7 +7,7 @@ | Goalpost id | `v6.3.0-gp-agent-automation-parity` | | Release home | `v6.3.0` | | Umbrella issue | `not opened yet` | -| Goalpost doc | `docs/goalposts/v6.3.0/agent-automation-parity.md` | +| Goalpost doc | `docs/archive/goalposts-pre-issues/v6.3.0/agent-automation-parity.md` | | Design cycle | `not active yet` | | Slice budget | `5` | | Status | `planned` | diff --git a/docs/archive/goalposts-pre-issues/v6.4.0/browser-edge-read-path.md b/docs/archive/goalposts-pre-issues/v6.4.0/browser-edge-read-path.md index ac938c96..36fdb9a8 100644 --- a/docs/archive/goalposts-pre-issues/v6.4.0/browser-edge-read-path.md +++ b/docs/archive/goalposts-pre-issues/v6.4.0/browser-edge-read-path.md @@ -7,7 +7,7 @@ | Goalpost id | `v6.4.0-gp-browser-edge-read-path` | | Release home | `v6.4.0` | | Umbrella issue | `not opened yet` | -| Goalpost doc | `docs/goalposts/v6.4.0/browser-edge-read-path.md` | +| Goalpost doc | `docs/archive/goalposts-pre-issues/v6.4.0/browser-edge-read-path.md` | | Design cycle | `not active yet` | | Slice budget | `6` | | Status | `planned` | diff --git a/docs/archive/goalposts-pre-issues/v7.0.0/protocol-audit-response.md b/docs/archive/goalposts-pre-issues/v7.0.0/protocol-audit-response.md index 6fa77d6c..a06028e4 100644 --- a/docs/archive/goalposts-pre-issues/v7.0.0/protocol-audit-response.md +++ b/docs/archive/goalposts-pre-issues/v7.0.0/protocol-audit-response.md @@ -7,7 +7,7 @@ | Goalpost id | `v7.0.0-gp-protocol-audit-response` | | Release home | `v7.0.0` | | Umbrella issue | `not opened yet` | -| Goalpost doc | `docs/goalposts/v7.0.0/protocol-audit-response.md` | +| Goalpost doc | `docs/archive/goalposts-pre-issues/v7.0.0/protocol-audit-response.md` | | Design cycle | `not active yet` | | Slice budget | `unknown` | | Status | `planned` | diff --git a/test/unit/docs/planning-surfaces.test.js b/test/unit/docs/planning-surfaces.test.js index cbe267db..918451b3 100644 --- a/test/unit/docs/planning-surfaces.test.js +++ b/test/unit/docs/planning-surfaces.test.js @@ -50,6 +50,16 @@ function cycleDirs() { .sort(); } +function archivedGoalpostFiles() { + const root = path.join(repoRoot, 'docs/archive/goalposts-pre-issues'); + return readdirSync(root, { withFileTypes: true }) + .filter((entry) => entry.isDirectory()) + .flatMap((entry) => readdirSync(path.join(root, entry.name)) + .filter((name) => name.endsWith('.md')) + .map((name) => path.posix.join('docs/archive/goalposts-pre-issues', entry.name, name))) + .sort(); +} + describe('planning surfaces', () => { // eslint-disable-line max-lines-per-function it('keeps GitHub Issues named as the canonical work tracker', () => { const checks = [ @@ -132,4 +142,12 @@ describe('planning surfaces', () => { // eslint-disable-line max-lines-per-funct assertLocalMarkdownLinksExist(file); } }); + + it('keeps archived goalpost identity paths pointed at their archived files', () => { + for (const file of archivedGoalpostFiles()) { + const goalpostDoc = read(file).match(/^\| Goalpost doc \| `([^`]+)` \|$/mu)?.[1]; + + expect(goalpostDoc).toBe(file); + } + }); });