@erclx/canon 5.14.0 → 5.15.0

package/src/sandbox/expect.ts

@@ -138,7 +138,6 @@ export function expectFilePath(
 ): string {
   return join(
     root,
-    'scripts',
     'sandbox',
     'fixtures',
     category,

package/src/serve/static.ts

@@ -13,7 +13,7 @@ export const SERVE_HOST = '127.0.0.1'
 export const DEFAULT_PORT = 8787
 
 /** How far past the requested port to look before refusing. */
-const PORT_ATTEMPTS = 20
+export const PORT_ATTEMPTS = 20
 
 const DEFAULT_ENTRY = 'index.html'
 
@@ -216,23 +216,23 @@ export function shouldWalkPast(error: unknown): boolean {
   return (error as NodeJS.ErrnoException | null)?.code === 'EADDRINUSE'
 }
 
+type BoundServer = ReturnType<typeof Bun.serve>
+
 /**
  * Picks a listening port, starting at the requested one and walking forward.
  * A busy port is the ordinary case rather than a failure, since a preview of
  * one workspace is routinely open while another is started.
+ *
+ * Takes the bind as a parameter so every surface that serves walks ports the
+ * same way, whatever routes it binds.
  */
-function listen(
-  root: string,
+export function bindFirstFree(
   first: number,
-  index: boolean,
-): { server: ReturnType<typeof Bun.serve>; port: number } | undefined {
+  bind: (port: number) => BoundServer,
+): { server: BoundServer; port: number } | undefined {
   for (let port = first; port < first + PORT_ATTEMPTS; port++) {
     try {
-      const server = Bun.serve({
-        hostname: SERVE_HOST,
-        port,
-        fetch: (request) => respond(root, request, index),
-      })
+      const server = bind(port)
       /**
        * The bound port rather than the requested one. Port 0 asks the OS to
        * choose, so reporting the request builds a URL pointing at nothing.
@@ -245,7 +245,7 @@ function listen(
        * Contention is the one cause worth walking past. A permission failure
        * or an unavailable interface swallowed here would be retried twenty
        * times and then reported as a port range being full, which names a
-       * cause nothing checked. `startServer` turns the rethrow into a refusal.
+       * cause nothing checked. The caller turns the rethrow into a refusal.
        */
       if (!shouldWalkPast(error)) throw error
     }
@@ -253,6 +253,20 @@ function listen(
   return undefined
 }
 
+function listen(
+  root: string,
+  first: number,
+  index: boolean,
+): { server: BoundServer; port: number } | undefined {
+  return bindFirstFree(first, (port) =>
+    Bun.serve({
+      hostname: SERVE_HOST,
+      port,
+      fetch: (request) => respond(root, request, index),
+    }),
+  )
+}
+
 export async function respond(
   root: string,
   request: Request,

package/src/shipped/references.ts

@@ -36,13 +36,10 @@ export const SHIPPED_CORPORA = [
 
 /**
  * Trees inside a corpus above that no target receives, matching the negations
- * the `files` field already makes. A number under either names something its
- * only reader can already resolve.
+ * the `files` field already makes. A number under one names something its only
+ * reader can already resolve.
  */
-export const SHIPPED_EXCLUSIONS = [
-  /^scripts\/sandbox\//,
-  /^scripts\/eval\//,
-] as const
+export const SHIPPED_EXCLUSIONS = [/^scripts\/eval\//] as const
 
 /** Whether a repository-relative path sits in the gated corpus. */
 export function isShippedCorpus(path: string): boolean {
@@ -97,10 +94,11 @@ const PULL_REQUEST = /(?<![0-9A-Za-z_])#([0-9]+)(?![0-9A-Za-z_])/g
  * The third is the one a later author meets. Admitting an all-digit sha admits
  * every run of seven or more decimal digits with it, so a date written without
  * separators, a large count, or a float artifact reads as a commit reference.
- * The corpus carries no instance and that is the exclusions rather than luck:
- * twelve such runs sit under the seven roots, eleven of them under
- * `scripts/sandbox/`, `scripts/eval/`, or a test file, and the twelfth is the
- * genuine sha in `orchestrator-poll.md`. Write a seven-digit measurement into a
+ * The corpus carries no instance and that is the corpus bounds rather than luck:
+ * twelve such runs were counted when the scenario tree still sat under
+ * `scripts/`, eleven of them under that tree, `scripts/eval/`, or a test file,
+ * all now outside the corpus, and the twelfth is the genuine sha in
+ * `orchestrator-poll.md`. Write a seven-digit measurement into a
  * shipped page and the push fails on it, which the marker answers and no
  * narrowing can, since requiring a letter loses the all-digit sha above.
  */

package/src/surface-root.ts

@@ -43,7 +43,6 @@ export const SURFACE_ENTRIES: readonly string[] = [
   'DESIGN.md',
   'context',
   'wireframes',
-  'decisions',
   'canon',
 ]
 

package/src/targets/pulls.ts

@@ -8,7 +8,7 @@ const GH_TIMEOUT_MS = 30_000
  * The two headings a review pass posts under.
  *
  * Owned by `review-pr`, which states the full set once, and pinned here
- * the way `role-orchestrator/scripts/poll.sh` pins them. All three surfaces
+ * the way `role-orchestrator/scripts/poll.ts` pins them. All three surfaces
  * ship separately, so a heading added in that skill goes stale here with
  * nothing comparing the copies.
  */
@@ -139,7 +139,7 @@ export function rollup(checks: readonly RawCheck[]): ChecksState | null {
 
 /**
  * Reads the heading of the newest pass carrying one, matching on the first line
- * alone the way `poll.sh` does.
+ * alone the way `poll.ts` does.
  *
  * The reviews arrive oldest first, so the last match is the current state of
  * the thread. A pass carrying neither heading is somebody reviewing by hand and

package/standards/architecture.md

@@ -40,7 +40,7 @@ The slots come from a scale test. Ask whether the decision would still be in thi
 - A decision that fills no slot. It lives in the domain context entry it constrains, and this file carries at most one line pointing at it.
 - A measurement paragraph specific to one domain's own mechanism, even behind a slot decision. Route it to that domain's context entry and keep the choice, the alternative that lost, and one reason here.
 - The instances of a build principle. The principle takes one sentence here, and each instance lives in the domain entry where it applies.
-- The history of how a decision was reached or revised: rounds of candidates, a figure followed by its correction, a branch or change that moved a number. That trail goes to the decision log or the change that introduced it.
+- The history of how a decision was reached or revised: rounds of candidates, a figure followed by its correction, a branch or change that moved a number. Cut it. Git and the change that introduced it keep the trail.
 
 ## Sections
 

package/standards/context.md

@@ -100,7 +100,7 @@ Only the `development` entry carries this section. It is not a general-purpose h
 - Anything already in `canon/REQUIREMENTS.md` or `canon/ARCHITECTURE.md`.
 - The history of how the domain reached its current shape. An entry describes the repository as it stands, so a change number, release label, or date attached to a change goes wherever the project tracks work.
 - A rejected alternative's provenance, which is the same rule at the one place the section above admits history. Keep what was tried and why it lost. Cut who tried it and when.
-- The route to a decision: the rounds of candidates, the tuning steps a threshold passed through, the review pass that caught a miss. State the decision, what lost, and why, once and in the present tense. The route goes to the decision log or the change that introduced it.
+- The route to a decision: the rounds of candidates, the tuning steps a threshold passed through, the review pass that caught a miss. State the decision, what lost, and why, once and in the present tense. Cut the route. Git and the change that introduced it keep it.
 - Measured results a generated file already carries. Point at the file instead of copying the figure, so a re-run cannot leave the entry behind.
 
 ## Length

package/standards/design.md

@@ -27,7 +27,7 @@ Does not govern:
 
 - CSS classes and prop names. Those live in code.
 - Anything that needs updating every time the code is refactored
-- The history of how a value or a mark was chosen: the candidates, the rounds, the date of a pick. State the rule and the current value. The trail goes to the decision log.
+- The history of how a value or a mark was chosen: the candidates, the rounds, the date of a pick. State the rule and the current value, and cut the trail. Git keeps it.
 
 ## Format
 

package/standards/index.md

@@ -12,7 +12,6 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Branch reference](branch.md): Branch naming format and type conventions
 - [Commit reference](commit.md): Commit message format and type conventions
 - [Context entry reference](context.md): Shape and content rules for canon/context/<domain>.md entries
-- [Decisions reference](decisions.md): Folder layout, ordinal filename, frontmatter, record sections, and the append-only lifecycle for canon/decisions/
 - [Design reference](design.md): Shape and content rules for canon/DESIGN.md
 - [Diagram reference](diagrams.md): Shape and content rules for .canon/diagrams/<kind>.md files
 - [Docs reference](docs.md): Reader and jurisdiction, frontmatter, page structure, what a page links out to, the diagram permission, and when a category earns a subfolder

package/standards/requirements.md

@@ -9,7 +9,7 @@ Applies to `canon/REQUIREMENTS.md`. Describes what the product does and why, not
 
 ## Scope
 
-Governs the product-scope document at `canon/REQUIREMENTS.md`: problem, goals, non-goals, MVP features, distribution, stack, and constraints.
+Governs the product-scope document at `canon/REQUIREMENTS.md`: problem, goals, non-goals, MVP features, distribution, and constraints.
 
 Does not govern:
 
@@ -23,7 +23,6 @@ Does not govern:
 - User-facing goals stated as outcomes, not implementation
 - Explicit non-goals that prevent feature creep. Mark deferred items "(deferred)" so they read as paused, not excluded. A non-goal resting on how an outside tool, an installer, or the model behaves may close with one `Revisit when <finding>.` sentence, and a non-goal resting on scope alone takes none.
 - MVP features as a numbered list: feature name and one-line description
-- Tech stack as a plain list of tools
 - Hard constraints that shape every decision
 
 ## What does not go in
@@ -31,14 +30,15 @@ Does not govern:
 - Implementation details, API names, or internal component references
 - Anything that describes how a feature is built rather than what it does
 - Measured results, such as scores, benchmark figures, or token counts. They move on every run and this file changes least. Name where the results live instead.
+- Content another canonical doc owns, such as the stack list, which the stack-and-runtime slot of `canon/ARCHITECTURE.md` holds, or the rules of this standard itself
 
 ## Sections
 
-Use `## Problem`, `## Goals`, `## Non-goals`, `## MVP features`, `## Tech stack`, and `## Constraints`. Add `## Distribution` when the rule below applies. Add `## Premise` when the project exists to answer a question, stated as the question and what would count as an answer, never as the answer measured so far. Drop a section rather than pad it with filler.
+Use `## Problem`, `## Goals`, `## Non-goals`, `## MVP features`, and `## Constraints`. Add `## Distribution` when the rule below applies. Add `## Worldview` when the project holds beliefs that shape every decision, and keep a belief there only when it changes a decision, since a padded worldview turns into a second goals list. Add `## Premise` when the project exists to answer a question, stated as the question and what would count as an answer, never as the answer measured so far. Drop a section rather than pad it with filler.
 
 ## Lifecycle
 
-The MVP list is a historical record of the original scope. Once those features ship it stays as written. Do not renumber it, do not append to it, and do not annotate entries with status. A reader telling the original scope apart from what followed depends on the first one staying legible.
+Once every entry in the MVP list, or in a later scope section, has shipped, delete the section. Git keeps the old text, and the document states the project as it stands. Do not annotate an entry as shipped and leave it in place. While any entry is unshipped, do not renumber the list or append to it.
 
 Later scope arrives as a new section rather than as an extension of the MVP list. Name the section for what it delivers and state its entries as outcomes, the same way the goals are stated. Nothing sequences either list into versions. Work reaches the board as discrete tasks under `tasks.md`, and `board.md` orders them by readiness, so a section here states what is wanted and never when it lands.
 
@@ -65,7 +65,5 @@ State each entry as an outcome the consumer reaches, never as the mechanism that
 
 <!-- ## Distribution: include only when shipping outside the repository -->
 
-## Tech stack
-
 ## Constraints
 ```

package/standards/wireframes.md

@@ -76,11 +76,11 @@ Both fields feed `canon/wireframes/index.md` when regenerated.
 ## Not on this surface
 
 - State what was deliberately left off, one bullet per exclusion, as a present-tense rule: `- No navigation rail`. This is the section that stops a draft from proposing what was already ruled out.
-- Keep the reason to a clause where one is needed. The rounds that ruled it out go to the decision log.
+- Keep the reason to a clause where one is needed. Cut the rounds that ruled it out.
 
 ## What moves out
 
-- Which candidate beat which, and when: the decision log
+- Which candidate beat which, and when: nowhere. Cut it, since git keeps the old text
 - Measurements such as contrast ratios and timings: `canon/DESIGN.md` for tokens and floors, the surface's context entry for the rest
 
 ## What moves to canon/context/

package/tooling/claude/reference.md

@@ -14,7 +14,6 @@ canon/
 ├── ARCHITECTURE.md    ← seeded. Technical design decisions and open questions
 ├── DESIGN.md          ← seeded. Visual intent and the decisions behind it
 ├── context/           ← seeded. Per-domain narrative. `index.md` is the discovery anchor.
-├── decisions/         ← seeded. Decision history a canonical doc points at, never loaded eagerly. `<nn>-<slug>.md` records.
 └── wireframes/        ← seeded. Per-surface regions and states. `index.md` is the discovery anchor; `<surface>.md` files hold the regions list, the states table, and the behavior bullets.
 
 .claude/

package/tooling/claude/seeds/canon/REQUIREMENTS.md

@@ -13,6 +13,4 @@ Authoring guidance: the requirements standard.
 1. Feature: description
 2. Feature: description
 
-## Tech stack
-
 ## Constraints

package/tsconfig.json

@@ -11,5 +11,5 @@
       "@/*": ["./src/*"]
     }
   },
-  "include": ["src"]
+  "include": ["src", "claude/skills/*/scripts/**/*.ts"]
 }