Repository navigation
docs: delete obsolete documentation and record the lifecycle policy - #371
Merged
Merged
Conversation
Git history is the archive. Deletes documentation for retired interfaces, removed generation paths, superseded contracts, completed or abandoned plans, and dated snapshots, after confirming what happened to everything each document named and moving any rule that still binds into its canonical owner. Live ideas from the deleted backlog became issues (#358-#364); genuinely unresolved document authority is isolated in #365-#369, with those documents left unchanged apart from dead links. Policy: docs/method/documentation-lifecycle.md owns when documentation is kept, rewritten, or deleted, registered in durable-decisions.md (which gains rule 7 and covers deletion in rule 3). process.md, roadmap-planning.md, the design TEMPLATE, and AGENTS.md no longer keep superseded documents, graveyards, or retrospectives as history. AGENTS.md's structure and current-reality sections now name real owners and the real quality gate. Moved rules: CI shard and impact planning to docs/method/ci.md; the Graft drawer's display-only lane rule to drawers-and-panels.md; title-scene developer commands to title-screen.md; the Continuum boundary to supported-outcome-settlement-and-why.md; the identity-doctrine checklist to #358; the title-scene freeze leash to docs/method/title-scene-freeze.md (scripts/ci/frozen-paths.mjs updated). Corrections: ARCHITECTURE (no MCP; Graft API; Jim.edict buffer lifecycle; Echo hosts the rope as law), README, GUIDE, VISION, BEARING, CODE_STANDARDS, the ownership map (accepted, flat-text reference authored), the hosting and end-to-end guides (checkpoint declaration is implemented; jedit.text owns text lawpacks), text-edit-algebra, 0157, 0148, and the UI topics (save, range :why, and causal markers are currently obstructed). Tests: specs that only asserted the wording of deleted documents were removed (release-quickstart, causal-roadmap-signpost, causal-rope-text-authority-inventory, vim-power parity and usability fixtures, the skipped graph-rope RED matrix, and the doc-reading tests in design-cycle-policy, audit-docs, anchor-transform-cycle, and the 0102 closeout, renamed vim-command-line-teardown-docs). Behavioural checks were kept; BEARING's undo assertions moved into the corridor test. The quality gate no longer requires the deleted 0027 to link the identity doctrine, the CI shard map drops the deleted release-quickstart spec, and a stale .gitignore entry for retired structural-history generation is removed.
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
Important Review skippedToo many files! This PR contains 329 files, which is 229 over the limit of 100. To get a review, reduce the PR to 100 files or fewer by splitting it into smaller PRs or changing its base branch. Upgrade to a paid plan to raise the limit. Usage-priced reviews support at most 300 files. ⚙️ Run configuration
⛔ Files ignored due to path filters: 6
📒 Files selected for processing: 329
You can disable this status message by setting the
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9ee2435b2e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
# Conflicts: # CHANGELOG.md
# Conflicts: # CHANGELOG.md
Owner
Author
|
@codex review please. Focus on: (1) any deleted document whose still-binding rule did not reach its canonical owner; (2) rewritten passages in AGENTS.md, ARCHITECTURE.md, VISION.md, BEARING, the ownership map, and the Echo guides that misstate current code; (3) whether docs/method/documentation-lifecycle.md and durable-decisions.md rule 7 conflict with anything left in docs/method/; (4) dead references to deleted paths outside CHANGELOG. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6e2d9c39e5
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
# Conflicts: # CHANGELOG.md
The quality job now runs scripts/ci/shellcheck.sh after the quality gate. ci.md describes what it checks (tracked .sh files, bash/sh shebangs directly or through a plain env, and the generated hook launchers), that env shebangs with options, quotes, or escapes fail the check, and where the classifier and its spec live. It also corrects the local-check line: npm run check runs build, tests, and the quality gate, while ShellCheck runs in CI.
… cycle docs Codex review of #371: deleting 0002 and 0145 removed the only prose statement of two active contracts. text-edit-algebra.md's Anchors section now states the four point-anchor transform laws (unchanged before startByte; bias decides at a pure insertion point; shift by the replacement delta at or after endByte; collapse to startByte inside a replaced span), matching src/domain/anchor-transform-contract.ts and its specs, with interval anchors left to #359. GUIDE.md gains Startup flags: --version/-V and --help/-h output, exiting before the workspace module loads, and the sole-argument rule, matching src/adapters/jedit-startup-cli.ts and spec/jedit-startup-cli.spec.mjs.
Owner
Author
|
@codex review please, focus on 93d5834 and the merge 02adf43 / ci.md 8b8d305: whether any other deleted document was the only statement of a contract that is still active (as 0002 and 0145 were), and whether docs/method/ci.md's ShellCheck section matches scripts/ci/shellcheck.sh and scripts/ci/lib/shebang.sh. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 93d583452d
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Codex review of #371: deleting 0045 removed the only documentation of title:record's machine-readable output, which spec/title-scene-record-cli.spec.mjs still pins. The same held for title:preview (0043) and title:profile (0104), so docs/topics/ui/title-screen.md's Developer Tools section now states all three: options and defaults, the JSON structure (recording/frames with glyphRows and per-cell fgRGB/bgRGB; preview/inspector; scene/render/timing/checksum), determinism, the usage exit code, and the spec that pins each, checked against the scripts.
Owner
Author
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: dd14ab8c0f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Codex review of #371: 0104 held the only statement that the title:profile allocation witness reports unmeasured, not success, without allocation instrumentation. docs/topics/ui/title-screen.md now says the witness runs in Braille render mode, reports unmeasured without --expose-gc and also for a zero forced-GC retained-heap delta (which does not show zero allocation), reports allocating only for a positive delta, and never reports bounded-after-warmup or zero-hot-loop, matching scripts/title-scene-allocation-witness.mjs and its spec.
Owner
Author
|
Codex Review: Didn't find any major issues. Chef's kiss. Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
Tests pin behavior; they never open a Markdown file or assert its wording. Removed specs that only read docs: audit-docs, design-cycle-policy, guide-path-references, echo-application-hosting-guide (its one behavioural case duplicated production-cutover-guard), rope-fact-inspector-design, and vim-command-line-teardown-docs. Removed the DL-0158 ledger half of replace-range-law-cycle and its audit-ledger helper, keeping the lawpack digest-sidecar, provenance, and native-source checks. Removed the quality gate's identity-doctrine-links rule, which required Markdown files to contain links, and the now-empty docs-release CI shard: docs-only changes now run build and quality but no test shard. documentation-lifecycle.md now owns the rule that tests never read documentation; AGENTS.md, process.md, project-invariants.md, and ci.md point to it instead of allowing "evidence-ledger" doc assertions.
Owner
Author
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c5089648e7
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
ShellCheck discovery read the first line of every tracked non-.sh file, including Markdown, which contradicts the rule that no check opens documentation. Markdown paths are now skipped before shebang classification; a driver spec pins that a Markdown file with an unparseable env shebang is never reported.
Owner
Author
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f5f4450a3b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
The rule is that no check's result can depend on a document's content. Copying a directory byte-for-byte into a fixture (the ReplaceRange proof harness copies edict/replace-range, READMEs included) is not reading it; parsing a document, even only its first line, is. AGENTS.md, process.md, and ci.md now say so instead of forbidding any file open.
Owner
Author
|
Codex Review: Didn't find any major issues. Hooray! Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
README.md now owns current truth (Current posture: what works, how the text path works, authority and artifact boundaries, roadmap, hard gates) and product direction (Where Jim is going). The Vim-parody introduction is unchanged. VISION.md and docs/BEARING.md are deleted; AGENTS.md, the durable-decision register, process, roadmap-planning, the ownership map, text-edit-algebra, and the teardown point at the README sections. BEARING's completed checklist items and its Verification block (duplicated in GUIDE.md) were dropped. Two CI specs used docs/BEARING.md only as a sample path string and now use docs/method/ci.md.
Owner
Author
|
@codex review please, focus on 2f55e40: VISION.md and docs/BEARING.md were folded into README.md (Current posture, Where Jim is going). Check that no binding rule from either was lost, nothing now stale was carried over, every reference points at the README sections, and the README introduction (through Documentation) is unchanged. |
Brings in #336 (Leader settings), #339 (static title screen), and #342 (explorer search). quality-baseline.json takes main's lower title-screen spec budget and keeps this branch's removal of the law-cycle entry. title-screen.md folds the freeze reference into main's Standalone Scene Tools section, 0160 links the moved freeze doc, and the freeze doc now says the engine and assets (reachable only through the title tools) are frozen, since the title screen itself is a static logo.
Owner
Author
|
Codex Review: Didn't find any major issues. 👍 Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Git history is the archive. This deletes documentation for retired interfaces, removed generation paths, superseded contracts, finished or abandoned plans, and dated snapshots. It also records that rule in the repository, so future sessions follow it without relying on agent memory.
A path that no longer exists was only a lead. For every document, I confirmed whether each name it used was removed, renamed, moved, generated, or owned by another repository, checking current code, build scripts, accepted decisions, and open work. Rules that still bind were moved into their canonical owners before deletion. Live ideas became issues. Documents whose authority is genuinely unclear were left unchanged (apart from dead links) and isolated as questions.
No runtime architecture or review requirement changes. Documentation that overlaps #356 (
docs/data-model.md,ADVANCED_GUIDE.md, reopen passages in 0148, 0159, and the end-to-end guide) is left for #356; this branch will take its merged changes before finalizing.Policy
docs/method/documentation-lifecycle.mdowns when documentation is kept, rewritten, or deleted. It covers:docs/method/durable-decisions.md. Rule 3 now also covers deletion; new rule 7 says a superseded document is not kept beside its replacement.AGENTS.md("Historical design documents remain evidence of their cycle"; stale "active"/"completed" plan bullets; a false "Current Reality");process.md"Landing A Cycle" (kept design docs as history, moved material tograveyard/);roadmap-planning.md(asupersededlifecycle state, BEARING as a "historical ledger", the retired v0.1.0 instance, a draft-PR rule that contradictedprocess.md);TEMPLATE.md(asupersededstatus).docs/method/ci.mddocuments CI planning. This rule was undocumented outside a stale cycle doc.Deleted or substantially rewritten
docs/design/0001–0008src/domain/anchor-transform-contract.ts+ spec;project-invariants.md§5, 12–16, 6–11; ownership map; cutover guarddocs/design/0009–0015,0036–0046,0078,0099,0101docs/topics/ui/*(title developer commands moved totitle-screen.md)docs/design/0016–0023scripts/jedit-echo-host-witness.mjs;spec/workspace-shutdown.spec.mjsdocs/design/0024–0029,0031–0033,0035AGENTS.mdfalsely called 0027 and 0033 activeecho-identity-doctrine.mddocs/design/0034-design-cycle-template-and-lifecycle.mdprocess.md,TEMPLATE.md,AGENTS.md,durable-decisions.mddocs/design/0034-ci-shard-and-impact-planning.mddocs/method/ci.md(rewritten againstscripts/ci/andci.yml, adds the title freeze and Edict job)docs/design/0034-echo-history-drawer.mddocs/design/0102docs/design/0103,0104,0107docs/method/title-scene-freeze.md; #108docs/design/0105(md + 2 JSON fixtures),0105-vim-target-usability-tests.mdjim.core)docs/design/0106,0108,0108a:whyroadmaps; Current Truth false (history drawer, WSC, export)supported-outcome-settlement-and-why.mddocs/design/0145,0146,0147,0149,0151(inventory),0154,0155,0156docs/design/0150–0153drawers-and-panels.md(display-only lanes and bounded payloads)docs/design/structural-history-graphql-authority.mdproject-invariants.md,text-edit-algebra.md, lawpack schema, nativerope/replace.rs, BEARINGdocs/design/optic-session-bootstrap-contract.md,jedit-echo-graph-model.mdecho-identity-doctrine.md; 0158/0159docs/stack-map.md,docs/code-standards-audit.md,docs/audits/*VISION.md;CODE_STANDARDS.md+ quality gatedocs/releases/**,docs/method/release*.md,docs/method/releases/docs/method/backlog/**(53 cards),graveyard/,retro/docs/method/title-scene-freeze.mdedict/replace-range-probes/{buffer-decoder,leaf-slice,node-atom-read,range-assembly,state-read}edict/replace-range/;basis-identitykept pending #369AGENTS.md,ARCHITECTURE.md,README.md,GUIDE.md,VISION.md,CODE_STANDARDS.md,docs/BEARING.md,docs/jim-component-ownership.md, hosting and end-to-end guides,text-edit-algebra.md,echo-identity-doctrine.md, 0148, 0157, UI topicsecho-textsubstrate, optic/WASM boundary, checkpoint "obstructed", all:whyobstructed, "Jim-owned" text lawpacks, draft status of the ownership map, ESLint rules that do not exist, deleted range readerIsolated questions (documents left unchanged)
runtime-temperatures.md: is "no privileged graph" still doctrine?0121: are:ttd,:strand,:braidstill product commands?technical-teardown.md: keep and cut, or delete after moving §12?editor-chrome.md: is pending-intent text "optimistic text"?basis-identityprobe: live reproduction input or history?Tests and tooling
release-quickstart,causal-roadmap-signpost,causal-rope-text-authority-inventory,vim-power-parity-matrix,vim-power-target-usability-fixtures, and the always-skippedgraph-rope-runtime-red-matrix.design-cycle-policy,audit-docs,guide-path-references,echo-application-hosting-guide(its one behavioural case duplicatedproduction-cutover-guard),rope-fact-inspector-design, and the 0102 teardown check;anchor-transform-cyclelost its doc cases, andreplace-range-law-cyclelost its DL-0158 ledger half andtests/support/replace-range-audit-ledger.mjs.scripts/quality-gate.mjsdrops theidentity-doctrine-linksrule, which required Markdown files to contain links. Thedocs-releaseshard is gone, so a docs-only change runs build and quality but no test shard.scripts/ci/test-shards.mjsdrops the deleted spec's pattern.frozen-paths.mjspoints at the moved freeze doc. A.gitignoreline for retired structural-history output is removed.Validation
At 6e2d9c3 (after merging
mainwith #351, #354, and #356):[#N](url)placeholders inAGENTS.md's progress-footer template, which are inline examples, not links.