docs: retire GOAL.md, Plan.md and HANDOFF.md #24

Merged

jlxq0 merged 1 commit from chore/retire-state-files into main

2026-09-01 17:05:11 +00:00

jlxq0 commented

2026-09-01 17:02:55 +00:00

Owner

Retires the three state files. Issues filed first, so nothing was deleted before its
replacement existed.

Issues opened

#22 the GitHub mirror is public while the Forge repo is private, waiting-on-julian
#23 .spec/ is untracked and exists on one disk, waiting-on-julian, blocked on #22

#23 is the load-bearing one. HANDOFF.md was the only written record that .spec/
exists and is "not reconstructable from tracked files". Deleting it without filing that
would have lost the fact rather than the file, which is the compression failure this was
meant to avoid.

#22 had never been filed at all. It has been carried in session messages for a week,
which is exactly the hold that cannot outlive the session holding it.

Per file: migrated against dropped

`Plan.md`, 262 lines

Migrated. Nothing new. Its Deferred section was already issues #6 to #16 on
2026-08-26. Three design rationales not readable from the code went to AGENTS.md: store
ids being opaque on purpose (output groups have no content identity, and content addressing
would reveal cross-tenant equality), a signed link staying usable during an OIDC provider
outage, and the subprocess-per-compile reasoning.

Dropped. Every one of its ~60 boxes is ticked. The OfficeMaster commits, the vendoring
rationale and the four brand paths are already in templates/UPSTREAM, which is tracked.
Manifest paths, DNS records and edge config live in oddie-apps/platform, dns-primary
and edge-config and are discoverable there. Module descriptions restate the code.

`GOAL.md`, 157 lines

Migrated to AGENTS.md. §2's argument for linking Typst in-process (typst::World
is the sandbox; the CLI would be handed a real directory and resolver). §5's two findings
were already in CLAUDE.md and are now in AGENTS.md. §6's constraint that the IdP is
the Hanso Entra tenant and only that, and that Logto is never this server's issuer.
§4's output-durability position and the no-beta-environment decision.

Dropped. §1's "Current distribution checkpoint" was stale, naming v0.2.0 and the
v0.2.0 digest; docs/release-evidence.md carries the current v0.2.1 evidence. §3's G1 to
G11 are all ticked and their verification is recorded in that same file. §4's other
non-goals are already issues #9 to #15. §7's diagram restates the routes. §8 pointed at
.spec/, which no checkout of this repo contains, and at Plan.md.

`HANDOFF.md`, 66 lines

Migrated. Only the .spec/ fact, as #23.

Dropped. Everything else was stale state: release v0.2.0 at a commit six behind, the
v0.2.0 digest, "In flight: None", "Broken: none", and an "Exact next step" directing the
reader to cd /Users/jl/Code/jlxq0/typst-mcp, a checkout twelve commits behind at the time
I read it.

`CLAUDE.md` reduced to `@AGENTS.md`

AGENTS.md exists and did not need creating. It was not a duplicate of CLAUDE.md but a
divergent copy, and the divergence was doing harm: AGENTS.md carried none of
CLAUDE.md's eighteen Typst and rmcp core pitfalls. Codex reads AGENTS.md and not
CLAUDE.md, so every cross-engine review of this repository has run without the FileId
interner leak, the comemo double-link, the byte-offset abort, the Pixmap saturation, the
Entra v2.0 audience trap or the rmcp DNS-rebinding default. Now in one file both engines
read.

Nine other CLAUDE.md pitfalls were dropped as genuine duplicates. Each was checked against
its surviving AGENTS.md equivalent by name rather than assumed, since the two used
different wording throughout:

dropped from `CLAUDE.md`	surviving equivalent in `AGENTS.md`
Size worker memory from the final image	Worker memory must be tested in the final image
An expired signed link is 410, not 403	Expired and invalid signed links are different public errors
Length and character bounds (telemetry)	Length and character bounds do not make request-derived telemetry labels safe
A capacity check must decide whether insertion is allowed	Do not retain anonymous OAuth authorization state in process memory
Classify domain failures before selecting a transport	Classify a domain failure once, before choosing HTTP or MCP transport
OAuth bridge state and codes must be stateless	same entry, which carries the bind-before-forward requirement
Parent-process parsers need their own limits	Bound work done by archive and schema libraries
Storage quotas must serialize the decision and commit	Storage quota checks and commits are one serialized transaction
rmcp's local session manager is not capacity-bounded	In-memory MCP sessions need an admission ceiling

Conventions, Gate and both Verified environment facts sections moved across intact.

`fondue`: 10 to 6

Three occurrences were in Plan.md and one in GOAL.md, and both files are gone.
CLAUDE.md's moved into AGENTS.md rather than being removed, per the ruling that
GitOps paths and the cluster name in operational prose stay. The six that remain are
ci.yml:89, Dockerfile:6, README.md:186, docs/release-evidence.md:54,
docs/security.md:50 and the moved AGENTS.md:369. Nothing else was touched.

Also

README.md linked to Plan.md as "the completed build plan". That link is removed; the
sentence still points at docs/release-evidence.md.

Gate

fmt=0, clippy=0, test=0, 287 passed across 7 binaries, zero failures, at load 68.

jlxq0/mantis#299.

Retires the three state files. Issues filed first, so nothing was deleted before its replacement existed. ## Issues opened - **#22** the GitHub mirror is public while the Forge repo is private, `waiting-on-julian` - **#23** `.spec/` is untracked and exists on one disk, `waiting-on-julian`, blocked on #22 **#23 is the load-bearing one.** `HANDOFF.md` was the only written record that `.spec/` exists and is *"not reconstructable from tracked files"*. Deleting it without filing that would have lost the fact rather than the file, which is the compression failure this was meant to avoid. **#22 had never been filed at all.** It has been carried in session messages for a week, which is exactly the hold that cannot outlive the session holding it. ## Per file: migrated against dropped ### `Plan.md`, 262 lines **Migrated.** Nothing new. Its `Deferred` section was already issues #6 to #16 on 2026-08-26. Three design rationales not readable from the code went to `AGENTS.md`: store ids being opaque on purpose (output groups have no content identity, and content addressing would reveal cross-tenant equality), a signed link staying usable during an OIDC provider outage, and the subprocess-per-compile reasoning. **Dropped.** Every one of its ~60 boxes is ticked. The OfficeMaster commits, the vendoring rationale and the four brand paths are already in `templates/UPSTREAM`, which is tracked. Manifest paths, DNS records and edge config live in `oddie-apps/platform`, `dns-primary` and `edge-config` and are discoverable there. Module descriptions restate the code. ### `GOAL.md`, 157 lines **Migrated to `AGENTS.md`.** §2's argument for linking Typst in-process (`typst::World` *is* the sandbox; the CLI would be handed a real directory and resolver). §5's two findings were already in `CLAUDE.md` and are now in `AGENTS.md`. §6's constraint that **the IdP is the Hanso Entra tenant and only that**, and that Logto is never this server's issuer. §4's output-durability position and the no-beta-environment decision. **Dropped.** §1's "Current distribution checkpoint" was stale, naming v0.2.0 and the v0.2.0 digest; `docs/release-evidence.md` carries the current v0.2.1 evidence. §3's G1 to G11 are all ticked and their verification is recorded in that same file. §4's other non-goals are already issues #9 to #15. §7's diagram restates the routes. §8 pointed at `.spec/`, which no checkout of this repo contains, and at `Plan.md`. ### `HANDOFF.md`, 66 lines **Migrated.** Only the `.spec/` fact, as #23. **Dropped.** Everything else was stale state: release `v0.2.0` at a commit six behind, the v0.2.0 digest, *"In flight: None"*, *"Broken: none"*, and an "Exact next step" directing the reader to `cd /Users/jl/Code/jlxq0/typst-mcp`, a checkout twelve commits behind at the time I read it. ## `CLAUDE.md` reduced to `@AGENTS.md` `AGENTS.md` exists and did not need creating. It was not a duplicate of `CLAUDE.md` but a **divergent** copy, and the divergence was doing harm: `AGENTS.md` carried **none** of `CLAUDE.md`'s eighteen Typst and rmcp core pitfalls. Codex reads `AGENTS.md` and not `CLAUDE.md`, so every cross-engine review of this repository has run without the `FileId` interner leak, the `comemo` double-link, the byte-offset abort, the `Pixmap` saturation, the Entra v2.0 audience trap or the rmcp DNS-rebinding default. Now in one file both engines read. Nine other `CLAUDE.md` pitfalls were dropped as genuine duplicates. Each was checked against its surviving `AGENTS.md` equivalent by name rather than assumed, since the two used different wording throughout: | dropped from `CLAUDE.md` | surviving equivalent in `AGENTS.md` | |---|---| | Size worker memory from the final image | Worker memory must be tested in the final image | | An expired signed link is 410, not 403 | Expired and invalid signed links are different public errors | | Length and character bounds (telemetry) | Length and character bounds do not make request-derived telemetry labels safe | | A capacity check must decide whether insertion is allowed | Do not retain anonymous OAuth authorization state in process memory | | Classify domain failures before selecting a transport | Classify a domain failure once, before choosing HTTP or MCP transport | | OAuth bridge state and codes must be stateless | same entry, which carries the bind-before-forward requirement | | Parent-process parsers need their own limits | Bound work done by archive and schema libraries | | Storage quotas must serialize the decision and commit | Storage quota checks and commits are one serialized transaction | | rmcp's local session manager is not capacity-bounded | In-memory MCP sessions need an admission ceiling | `Conventions`, `Gate` and both `Verified environment facts` sections moved across intact. ## `fondue`: 10 to 6 Three occurrences were in `Plan.md` and one in `GOAL.md`, and both files are gone. `CLAUDE.md`'s **moved into `AGENTS.md` rather than being removed**, per the ruling that GitOps paths and the cluster name in operational prose stay. The six that remain are `ci.yml:89`, `Dockerfile:6`, `README.md:186`, `docs/release-evidence.md:54`, `docs/security.md:50` and the moved `AGENTS.md:369`. Nothing else was touched. ## Also `README.md` linked to `Plan.md` as "the completed build plan". That link is removed; the sentence still points at `docs/release-evidence.md`. ## Gate `fmt=0`, `clippy=0`, `test=0`, 287 passed across 7 binaries, zero failures, at load 68. `jlxq0/mantis#299`.

jlxq0 added 1 commit

2026-09-01 17:02:55 +00:00

docs: retire GOAL.md, Plan.md and HANDOFF.md

CI / cargo (pull_request) Successful in 1m35s

Details

CI / docker (pull_request) Successful in 20s

Details

3a4a165882

Open work belongs in Forgejo issues and constraints in AGENTS.md. Status
written into a file is always wrong, because a file has no state, and all
three had gone stale: GOAL.md and HANDOFF.md both described v0.2.0 as the
live release while production has run v0.2.1 since 2026-08-25, and
HANDOFF.md directed the next session to a checkout twelve commits behind.

Filed first, so nothing was deleted before its replacement existed:

  #22  the GitHub mirror is public while the Forge repo is private
  #23  .spec/ is untracked and exists on one disk

#23 is the load-bearing one. HANDOFF.md was the only written record that
.spec/ exists and is not reconstructable from tracked files, so deleting it
without filing that would have lost the fact rather than the file.

Plan.md's Deferred section was already migrated to #6 through #16 on
2026-08-26. Every other item in all three files is either a ticked box, or a
constraint now in AGENTS.md, or readable from the repository.

CLAUDE.md is reduced to @AGENTS.md. It was not a duplicate of AGENTS.md but a
divergent copy: AGENTS.md carried none of its eighteen Typst and rmcp core
pitfalls, so Codex, which reads AGENTS.md and not CLAUDE.md, has been
reviewing this repository without the FileId interner leak, the comemo pin,
the byte-offset abort or the Entra audience trap. Those are now in one file
that both engines read.

Nine further CLAUDE.md pitfalls were dropped as genuine duplicates, each
verified against its surviving AGENTS.md equivalent rather than assumed.

fondue occurrences go from 10 to 6. Four were in the deleted files; CLAUDE.md's
moved into AGENTS.md rather than being removed, per the ruling that GitOps
paths and the cluster name in operational prose stay.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018CXx4uyuDhqwungt4SMN4S