Purge the legacy status vocabulary from docs; delete a dead seed file - #322
Merged
Conversation
Closes the /docs drift tracked since May as #94, #96, and #97. API Reference (#94) documented the submissions and registry endpoints and missed three others entirely: POST /api/ask (the site assistant), POST /api/similarity/preview, and POST /internal/sync. All three are now covered with their real contracts — /api/ask's rate limits and headers, its 200-with-fallback behaviour on a MindRouter outage (it deliberately does not 500, so the chat widget degrades), the 0.2-vs-0.3 threshold that distinguishes the preview endpoint from the persisting one, and the sync trigger's 409-when-in-flight. Verified against the route handlers, and all twelve routes under app/api and app/internal now appear. Architecture (#96) described the migration-003 schema: five tables, no lifecycle columns, no friction ledger, no ClickUp projections, no request registry, no agent log. It now covers all seventeen tables, the ~40 columns added to applications since, and why the enums carry no CHECK constraints (the typed modules and verify:portfolio are the enforcement, so adding a lifecycle state stays a governance change rather than a migration). The component diagram showed a browser-calls-API architecture that was never true of most of this site — it now says plainly that pages are server components reading lib/* directly, and that the route handlers exist for mutations, the agent, and the sync trigger. Admin Guide (#97) listed a six-state lifecycle superseded by ADR 0001. It now carries the real twelve-state ladder and states where the admin surfaces actually sit: registry edits are overwritten by the next seed:portfolio TRUNCATE, status narrative comes from ClickUp, requests live in the tech_requests registry. Submissions review is the part that is still the live workflow. Also documents a defect found while checking that page rather than papering over it: STATUS_OPTIONS in app/admin/registry/[id]/page.tsx still offers the legacy submission states and the pre-ADR-0001 capitalised union. applications.status is plain TEXT with no CHECK, so those values write successfully, and publicStageFromStatus() buckets anything unrecognised as Exploring — an admin can silently misfile a project on /portfolio, and verify:portfolio won't catch it because the verifier reads lib/portfolio.ts, not the database. The page now warns against using that control until the list is fixed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…file Follow-up to #321, which refreshed these pages but left two lines still describing the pre-ADR-0001 lifecycle — my miss. /docs/api-reference documented the registry PATCH `status` parameter as "idea | approved | in-development | staging | production | retired". That is the legacy submission lifecycle, not the operational ladder. It now lists the twelve real values and states the consequence of sending anything else: the column is plain TEXT with no CHECK, so a bad value writes successfully and renders as Exploring. /docs/architecture had two contradictory `status` lines in the same applications block — the legacy one it always had, and the correct twelve-value one #321 added lower down. Removed the legacy line. Deletes db/seed_applications.sql. It is an unreferenced, byte-identical copy of migration 004 whose header instructs the reader to run it with `psql "$DATABASE_URL" -f db/seed_applications.sql`. That is precisely what #312 established as forbidden and what /docs/deployment warns against: it would TRUNCATE applications and repopulate every row with 2026-era statuses like 'in-development', which no longer exist in the taxonomy and which publicStageFromStatus() buckets as Exploring. A loaded gun with instructions attached, referenced by nothing. Verified both databases are already clean — every row in dev (29) and prod (15) carries a current-taxonomy value, so no data repair is needed. The applied migrations 003 and 004 still contain the legacy vocabulary in comments and seed data. Left alone deliberately: they are history, they have already run, and rewriting them would misrepresent what was applied. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Vendored strategic-plan submodule is behind upstreamThe vendored submodule pointer at The submodule is pinned at upstream This is an advisory comment from |
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
1 participant
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.
Part of making the ADR 0001 taxonomy the only lifecycle vocabulary on the site. This PR deliberately does not touch the admin registry files — a background task is already working those (
app/admin/registry/[id]/page.tsx,app/admin/registry/page.tsx,app/api/registry/route.ts).Docs — my miss in #321
#321 refreshed these pages but left two lines still describing the pre-ADR-0001 lifecycle:
/docs/api-referencedocumented the registryPATCHstatusparameter asidea | approved | in-development | staging | production | retired— the legacy submission lifecycle, not the operational ladder. Now lists the twelve real values and states the consequence of sending anything else: the column is plainTEXTwith no CHECK, so a bad value writes successfully and renders as Exploring./docs/architecturehad two contradictorystatuslines in the sameapplicationsblock — the legacy one it always had, and the correct twelve-value one Refresh the technical docs against the current codebase #321 added below it. Removed the legacy line.db/seed_applications.sql— deletedAn unreferenced, byte-identical copy of migration 004, whose header says:
That is precisely what #312 established as forbidden and what
/docs/deploymentwarns against. Running it wouldTRUNCATEapplicationsand repopulate every row with 2026-era statuses likein-development— values that no longer exist in the taxonomy and thatpublicStageFromStatus()buckets as Exploring. A loaded gun with instructions attached, referenced by nothing.Data is already clean
Checked both databases directly rather than assuming:
Every row on the current taxonomy. No data repair needed — the exposure was a form that could write bad values, not values already written.
Left alone deliberately
Applied migrations 003 and 004 still contain the legacy vocabulary in comments and seed data. They are history, they have already run, and rewriting them would misrepresent what was applied.
Note for the admin-registry work
While surveying I found there are four hardcoded status lists, and
app/admin/registry/new/page.tsxalready has the correct taxonomy — someone updated that copy and not[id]/page.tsx. That is the argument for deriving the list fromlib/portfolio.ts(e.g.Object.keys(OPERATIONAL_LABEL), which tsc keeps exhaustive) rather than fixing one more copy by hand.🤖 Generated with Claude Code