docs: commit the architectural rationale and the Gateway acceptance corpus - #85
Merged
Conversation
…orpus The founding thesis, the invariants, and the deliberate non-goals existed only in session transcripts; the plan file that held the original proposal was overwritten, and docs/COMPOSER.md advertised IMPLEMENTATION_LOG.md as Composer history although that log ends before Composer existed. - docs/ARCHITECTURE.md — the document someone joining in a year needs: the problem, the UI-over-existing-seams thesis, the core loop, why the AI proposes and deterministic machinery decides, the product model, why flows sit above surfaces, the browser/agent boundary, nine invariants, and what Composer deliberately does not do. - acceptance/gateway-corpus/ — the twelve prompts verbatim and immutable, the paraphrase set, the expected classification with each remaining item attributed to vocabulary/runtime/product-model, and the harness. Live model calls, so deliberately NOT in CI; the README carries the operational rules learned the hard way (pace it, sample more than once, discard adapter failures) and evidence/ is git-ignored. The harness is now path-portable. - docs/COMPOSER.md + README.md point at the current record instead of the historical one. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ✅ Deployment successful! View logs |
dspack-studio-composer | db4762e | Aug 12 2026, 05:32 PM |
There was a problem hiding this comment.
Pull request overview
This PR captures long-lived project knowledge in-repo by adding an architectural rationale document and committing the Gateway acceptance corpus (prompts, expected classifications, and a runnable harness), while updating top-level docs to point to these sources of truth.
Changes:
- Add
docs/ARCHITECTURE.mddocumenting Composer’s core thesis, invariants, non-goals, and key rationale. - Add
acceptance/gateway-corpus/with an “immutable prompts” charter, expected classifications, paraphrases, and a harness for producing evidence (with evidence output git-ignored). - Update
README.mdanddocs/COMPOSER.mdto correct stale pointers and link to the new architecture doc and acceptance corpus.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Updates top-level documentation links to point to the new architecture rationale and acceptance corpus. |
| docs/COMPOSER.md | Corrects historical pointers and links readers to architecture rationale + acceptance corpus. |
| docs/ARCHITECTURE.md | New architectural rationale document capturing load-bearing decisions, invariants, and non-goals. |
| acceptance/gateway-corpus/README.md | New corpus README describing immutability rules, operational constraints, and how to run the harness. |
| acceptance/gateway-corpus/paraphrases.mjs | Adds paraphrase set for measuring generalization beyond exact prompt strings. |
| acceptance/gateway-corpus/harness.mjs | Adds an evidence harness that drives the real pipeline and writes per-cell evidence outputs. |
| acceptance/gateway-corpus/EXPECTED.md | Adds expected per-prompt classification and ownership of remaining blockers. |
| acceptance/gateway-corpus/corpus.mjs | Adds the 12 immutable acceptance prompts verbatim. |
| acceptance/gateway-corpus/.gitignore | Ignores generated evidence/ output. |
Suppressed comments (1)
acceptance/gateway-corpus/harness.mjs:11
- The usage comment currently shows
node harness.mjs ..., but this file imports a local.tsmodule (packages/composer-core/src/plan.ts). That invocation will fail in a default Node setup; the usage instructions should match the actual required runner (e.g.pnpm exec tsx).
// Usage:
// node harness.mjs <n> <ds> one run (n=1..12, ds=shadcn|astryx)
// node harness.mjs all full corpus, sequential, paced
// GW_BASE=... overrides the gateway origin (default production).
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+13
to
+30
| import { readFileSync, writeFileSync, mkdirSync, realpathSync } from "node:fs"; | ||
| import { createHash } from "node:crypto"; | ||
| import { createRequire } from "node:module"; | ||
| // GW_CORPUS selects an alternate corpus module (e.g. ./paraphrases.mjs); | ||
| // GW_PREFIX prefixes evidence filenames so alternate runs never collide. | ||
| const CORPUS_MODULE = process.env.GW_CORPUS ?? "./corpus.mjs"; | ||
| const PREFIX = process.env.GW_PREFIX ?? "run"; | ||
| const { CORPUS } = await import(CORPUS_MODULE); | ||
|
|
||
| // Repo root, derived from this file's own location (acceptance/gateway-corpus/). | ||
| const REPO = new URL("../../", import.meta.url).pathname.replace(/\/$/, ""); | ||
| // GW_GEN / GW_EMIT point the harness at local package builds (post-fix evidence | ||
| // runs on exact merged code before npm publish); default = the app's installed deps. | ||
| const GEN = realpathSync(process.env.GW_GEN ?? `${REPO}/apps/composer/node_modules/@aestheticfunction/dspack-gen`); | ||
| const EMIT = realpathSync(process.env.GW_EMIT ?? `${REPO}/apps/composer/node_modules/@aestheticfunction/dspack-emit`); | ||
| const BASE = process.env.GW_BASE ?? "https://composer.aesthetic-function.com"; | ||
| const EVIDENCE = new URL("./evidence/", import.meta.url).pathname; | ||
| mkdirSync(EVIDENCE, { recursive: true }); |
| `#${ev.promptN} ${ev.ds}: plan=${ev.planning?.hosted?.intent}(${ev.planning?.pathUsed})` + | ||
| `${ev.vocabGap ? " VOCAB-GAP" : ` outcome=${ev.pipeline?.outcome} exit=${ev.pipeline?.exitCode}`}` + | ||
| `${ev.renderer ? ` wf=${ev.renderer.wireframe.length}/${ev.renderer.used.length}` : ""}` + | ||
| ` [${gateStr.slice(0, 120)}] ${Math.round((ev.durationMs ?? 0) / 1000)}s → ${file.split("/").pop()}`, |
Comment on lines
+1
to
+6
| // Gateway MCP corpus evidence harness. Makes LIVE model calls — never run in CI. | ||
| // See README.md in this directory for the rules and the operational notes. | ||
| // Drives the REAL pipeline: composer-core plan.ts (native TS import) → dspack-gen | ||
| // runPipeline (browser subpath, product-identical orchestrator) → dspack-emit — | ||
| // with the model turn on the production Worker (/api/propose), exactly like a | ||
| // hosted build in the product (adapter cloned from apps/composer/app/hosted-build.ts:118-151). |
Comment on lines
+27
to
+29
| ```bash | ||
| node acceptance/gateway-corpus/harness.mjs all | ||
| ``` |
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
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.
Phase E of the pre-1.0 milestone. The product's design rationale and its acceptance evidence existed only in session transcripts and a scratchpad; the plan file holding the original architecture proposal was overwritten, and
docs/COMPOSER.mdadvertisedIMPLEMENTATION_LOG.mdas Composer's phase-by-phase history although that log ends before Composer existed.docs/ARCHITECTURE.md— the document a person joining in a year actually needs: the problem, the UI over seams that already exist thesis (with the 72/72 grammar-ceiling measurement that justified project-scoping), the core loop, why the AI proposes and deterministic machinery decides, the product model incl. base+delta, why flows live above surfaces rather than inside generated ones, the browser/agent boundary, nine invariants that must not change casually, the documented evolutions (every reversal loosened access while tightening honesty), and an explicit list of what Composer does not do.acceptance/gateway-corpus/— the twelve prompts verbatim and immutable, the paraphrase set,EXPECTED.md(current classification with each remaining item attributed to vocabulary / runtime / product-model), and the harness, now path-portable. It makes live model calls, so it is deliberately not in CI; the README carries the immutability charter and the operational rules learned the hard way — pace it, sample contested cells more than once, discard adapter failures rather than reporting them.evidence/is git-ignored.docs/COMPOSER.mdandREADME.md;IMPLEMENTATION_LOG.mdstays as the honest historical record of the exhibit era, now labelled as such.Docs only — no source, no tests, no behavior.
🤖 Generated with Claude Code