Refresh the technical docs against the current codebase - #321
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>
Vendored strategic-plan submodule is behind upstreamThe vendored submodule pointer at The submodule is pinned at upstream This is an advisory comment from |
This was referenced Jul 27, 2026
ProfessorPolymorphic
added a commit
that referenced
this pull request
Jul 27, 2026
…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>
This was referenced Jul 27, 2026
ProfessorPolymorphic
added a commit
that referenced
this pull request
Jul 27, 2026
…#322) * Refresh the technical docs against the current codebase 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> * Purge the legacy status vocabulary from docs, and delete a dead seed 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> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
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.
Closes the
/docsdrift tracked since May: #94, #96, #97.API Reference (#94)
Documented the submissions and registry endpoints; missed three others entirely. Now covered with their real contracts, read off the route handlers:
POST /api/ask— the site assistant. Rate limits (60/hr public, 600/hr internal) with theRetry-After/X-RateLimit-*headers, and the deliberate 200-with-fallback: truebehaviour on a MindRouter outage — it doesn't 500, so the chat widget degrades instead of erroring.POST /api/similarity/preview— and why it's separate from/api/submissions/[id]/similarity: threshold 0.2 vs 0.3, stateless vs persisting. Over-notify and let the submitter judge.POST /internal/sync— the ClickUp trigger, including 409-when-in-flight (a run is 30–60s of sequential calls; overlapping runs would double-write).Verified: all 12 routes under
app/api/andapp/internal/now appear on the page.Architecture (#96)
Described the migration-003 schema — five tables, no lifecycle columns, no friction ledger, no ClickUp projections, no request registry, no agent log.
CREATE TABLEacrossdb/migrations/*against the page).applicationssince, grouped by the migration and ADR that introduced them.verify:portfolioare the enforcement, deliberately, so adding a lifecycle state stays a governance change rather than a migration.lib/*directly, and the route handlers exist for mutations, the agent, and the sync trigger.Admin Guide (#97)
Listed a six-state lifecycle superseded by ADR 0001. Now carries the real twelve-state ladder, plus a section on where the admin surfaces actually sit: registry edits are overwritten by the next
seed:portfolioTRUNCATE, status narrative comes from ClickUp, requests live intech_requests. Submissions review is the part that's still the live workflow.STATUS_OPTIONSinapp/admin/registry/[id]/page.tsxstill offers the legacy submission states (in-development,staging,retired) and the pre-ADR-0001 capitalised union (Planned,Prototype,Piloting, …) — ADR 0001 explicitly supersedes the latter. None are members of the current taxonomy.applications.statusis plainTEXTwith no CHECK, so those values write successfully, andpublicStageFromStatus()buckets anything unrecognised as Exploring so the UI never crashes. Net effect: an admin can silently misfile a project on/portfolio, andverify:portfoliowon't catch it — the verifier readslib/portfolio.ts, not the database.I documented it rather than fixing it, because the fix is a product decision (restrict the list? add a CHECK? extend the verifier to the DB? retire the surface, since REFACTOR.md has it retiring when ClickUp write-side lands). Flagged as a follow-up.
Verification
npm run buildandnpm run lintpass. All three pages rendered in the browser and checked for content, not just compilation.🤖 Generated with Claude Code