@erclx/canon 5.14.1 → 5.15.0

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/surface-root.ts

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

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/governance/rules/canon/645-decisions.md

@@ -1,12 +0,0 @@
----
-description: Route canon/decisions/ edits to the decisions standard for record shape and lifecycle
-paths:
-  - 'canon/decisions/**'
-  - '.claude/decisions/**'
----
-
-# Decisions standards
-
-## Authority
-
-- Follow the decisions standard for folder layout, the ordinal filename, frontmatter, record sections, and the append-only lifecycle. It is the single source. Read it with `canon standards decisions`.

package/standards/decisions.md

@@ -1,105 +0,0 @@
----
-title: Decisions reference
-description: Folder layout, ordinal filename, frontmatter, record sections, and the append-only lifecycle for canon/decisions/
----
-
-# Decisions reference
-
-Applies to `canon/decisions/`. Holds the history a canonical doc used to carry itself: pick rounds, superseded figures, and a decision's rejected alternatives, in a tracked folder nothing loads eagerly. A canonical doc points at a record from its own history section rather than restating it.
-
-## Scope
-
-Governs `canon/decisions/`: folder layout, the ordinal filename, frontmatter, record sections, and the append-only lifecycle.
-
-Does not govern:
-
-- Which canonical doc points here and when, and what stays behind in that doc's own body: `architecture.md`, `context.md`, `wireframes.md`, `design.md`, `requirements.md`, once each states its own retirement rule
-- Voice, rhythm, and sentence construction: the `write-human` skill
-- Headings, punctuation, word choice, and file references: `markdown.md`
-
-## What a working record looks like
-
-A record works when a reader who has never opened the project can follow it from the file alone:
-
-- What was decided, stated once, without needing the canonical doc that points here
-- What else was considered, and why each alternative lost
-- Which claim rests on a measurement, and what commit that measurement was read against
-
-A record failing these is non-conforming even when it satisfies every shape rule below.
-
-## Folder name
-
-- `canon/decisions/`, resolved the way every tracked surface is: at `canon/decisions/` in a project that has moved, at `.claude/decisions/` in one that has not.
-- Never add `canon/decisions/index.md` to a `CLAUDE.md` `@` import. A log that loads eagerly rebuilds the bloat it exists to absorb. A canonical doc's own pointer is how a reader reaches a record, one file at a time.
-
-## Record filename
-
-- Name each record `<nn>-<slug>.md`, a two-digit zero-padded ordinal followed by a kebab-case slug, the same shape a groundwork track's folder takes.
-- The ordinal is the order the record was written in, which is what lets a listing sort by when a decision landed rather than alphabetically by subject.
-- Never renumber an existing record. A later reader cites it by that name, and a record whose number moved is a record a stale citation can no longer find.
-
-## Frontmatter
-
-- `title` (required): the decision in sentence case
-- `description` (required): one line naming what was decided
-
-## Sections
-
-Use `## Context`, `## Decision`, `## Alternatives`, `## Revisit when`, and `## Measurements`.
-
-- `## Context`: the problem as it stood, stated so a reader needs nothing else open. Restate a fact rather than pointing at where it was found.
-- `## Decision`: what was chosen, and why, in enough detail that a reader can tell it apart from an alternative that sounds similar.
-- `## Alternatives`: each one considered and dropped, with the reason it lost. An alternative with no stated reason reads as a claim nobody checked.
-- `## Revisit when`: one bullet per finding that would reopen the decision. Required when the record came from a groundwork track whose deciding leans carried "Overturned by" lines, which carry over as written. It is optional otherwise, for a decision resting on how an outside tool, an installer, or the model behaves. Skip it for a decision resting on the project's own code.
-- `## Measurements`: skip when the decision cites no number. When it does, state the number and close with the commit it was read against, per Verification anchors below.
-
-## Verification anchors
-
-A record's reasoning stays correct while the numbers it cites move. The anchor records what a measured claim was read against, so a reader can tell a number that was checked and held from one nobody has looked at since.
-
-- Close a `## Measurements` section with a trailing sentence naming the short commit SHA and the ISO date that number was read: `Measured at <short-sha> on <YYYY-MM-DD>.`
-- Anchor on the number alone. A record citing none carries no `## Measurements` section at all.
-- Read an absent section as unchecked rather than as current. A record with no measurements has nothing due a re-read.
-
-## Lifecycle
-
-- Append-only. A written record is never edited to reflect a later reversal.
-- Write a new record when a later decision supersedes an earlier one, naming the record it supersedes. The old record stays as it was written, since it is history rather than a live statement of the current shape.
-- Never auto-loaded. A canonical doc's own history section links to a record by relative path, and a reader reaches it by following that link, not by the folder loading with the session.
-
-## Citation
-
-- Never cite `.canon/`. A record restates what it needs, since a clone without the gitignored records folder resolves nothing there.
-- Cite a same-repository pull request or commit the way `publish.md` fixes for any tracked document.
-
-## Template
-
-```markdown
----
-title: <Decision, in sentence case>
-description: <one line naming what was decided>
----
-
-# <Decision title>
-
-## Context
-
-<The problem as it stood, self-contained.>
-
-## Decision
-
-<What was chosen, and why.>
-
-## Alternatives
-
-- **<Alternative>.** <Why it lost.>
-- **<Alternative>.** <Why it lost.>
-
-## Revisit when
-
-- <The finding that would reopen the decision.>
-
-## Measurements
-
-<The number the decision rests on.> Measured at <short-sha> on <YYYY-MM-DD>.
-```

package/tooling/claude/seeds/canon/decisions/index.md

@@ -1,8 +0,0 @@
----
-title: Decisions
-subtitle: Decision history a project doc points at, never loaded eagerly
----
-
-# Decisions
-
-Decision history a project doc points at, never loaded eagerly