Repository navigation
Rename PLATFORM-001 -> The Appwrite Seam Contract in this repo's citations (cosmetic, non-blocking) #158
Description
What
The VIEWS cross-repo seam contract has been renamed. PLATFORM-001 is retired; it is now The Appwrite Seam Contract, at:
docs/ADRs/platform/appwrite_seam_contract.md
Recorded in views-appwrite ADR-011; the rename landed in a81a9cc.
Nothing in this repo is broken, and this is not urgent. Correctly-pinned URLs resolve against commits where the old filename still exists, and the contract's header records PLATFORM-001 as a former name, so a reader arriving with the old identifier still lands correctly.
Why bother at all
The rename exists because the old identifier carried no information at the point of use, and that has a measured cost on this platform: unreadable identifiers hide staleness. Two repos are pinned at 60674b2 — which is contract v1.0.0, two versions behind — and nobody noticed, because nothing about 60674b2 signals age. Every PLATFORM-001 mention costs a reader a lookup for the same reason.
Higher priority than the rest: CLAUDE.md
CLAUDE.md line ~90 says cross-repo contracts live in PLATFORM-001. That file ends with its own rule — "keep the six repos' versions in step; change this file first and propagate" — and it is agent working instructions, read at the start of every session in this repo, not documentation. Until it is synced, every session here is told the wrong name.
Canonical text from views-appwrite:
Cross-repo contracts live in **The Appwrite Seam Contract** (homed in `views-appwrite`, formerly
`PLATFORM-001`) and are referenced **by URL at a pinned commit, never copied**.
This repo's citations — 12 mentions across 6 files
| File | Mentions |
|---|---|
reports/technical_risk_register.md |
3 |
docs/ADRs/013_sampled_forecast_wire_contract.md |
3 |
views_postprocessing/unfao/appwrite_env.py |
2 |
tests/test_redaction_guard.py |
1 |
tests/test_env_declaration.py |
1 |
CLAUDE.md |
1 |
Observation specific to this repo
Two of your citations are in tests that enforce contract clauses — tests/test_env_declaration.py:97 (the suffix/secret rule) and tests/test_redaction_guard.py:2 (the multi-carrier redaction clause). Those are the only mechanical enforcement of the contract anywhere on the platform, in any repo, and they are worth knowing about.
Neither is broken by the rename; both cite the contract in a comment or docstring. When you update those two strings, consider whether the test should also record which version of the clause it enforces — §5.7 was struck in v1.2.0, and a test asserting a clause that no longer exists would pass silently.
Do NOT repoint pins as part of this
If this repo pins the contract or registry at a tag or sha, leave the pin alone. Moving a pin means reading the diff between versions and accepting the changes — a deliberate act with its own review. It is not part of a cosmetic rename, and bundling the two is how an unreviewed contract change slips in.
If you want to move to the current version, that is a separate piece of work. v1.2.0 struck §5.7 entirely and amended §5.1, §5.3 and §5.5.
Reference
- Contract:
docs/ADRs/platform/appwrite_seam_contract.mdinviews-appwrite - New:
joining_the_seam.md— non-normative onboarding checklist, including the pin form - Tracking epic: views-appwrite#14
Labels
documentation, non-blocking.
Activity
chore: close the three unblocked items /falsify found (#177)
Polichinel commentedon Aug 1, 2026
Done in PR #177 — surfaced by the
/falsifyaudit that disproved "there is nothing more to do in this repo". Actionable with no external dependency; simply never done.Polichinel commentedon Aug 1, 2026
Reopened in effect by #184 (epic #181, S3).
This was closed 2026-08-01, but the code half never landed — four
PLATFORM-001citations survive in.py, including one inside the raised message inappwrite_env.assert_env_declared, which points an operator at a retired contract name on the day their delivery refuses to launch.Leaving this closed and tracking the remainder in #184, which also adds a test banning the retired name so the same gap cannot reopen silently.
docs(seam): S3 #184 — finish #158's rename, fix the URL it broke, and…
Polichinel commentedon Aug 2, 2026
Finished by #195 (S3 / #184, epic #181).
For the record of what "cosmetic, non-blocking" turned out to mean:
PLATFORM-001citations survived in.py— one inside the message raised byappwrite_env.assert_env_declared, i.e. what an operator reads when a delivery refuses to launch..../platform/the Appwrite Seam Contract_identity_secrets_configuration_contract.md— a path with spaces that has never resolved.Both fixed, both §7d links now pinned to a commit rather than
main, andtests/test_doc_accuracy.pyrefuses the retired name in code so it cannot return quietly.