@erclx/canon 4.122.0 → 4.124.0

package/src/tasks/validate.ts

@@ -18,7 +18,7 @@ const ORDERING_FILE = 'priority.md'
 const BACKLOG_FILE = 'backlog.md'
 
 /**
- * The readiness headings `standards/tasks.md` fixes. The names are the
+ * The readiness headings `standards/board.md` fixes. The names are the
  * contract rather than a suggestion, so a board grouping under names of its own
  * reads as carrying no group at all and the run refuses instead of reporting a
  * clean board it never parsed.

package/standards/board.md

@@ -0,0 +1,136 @@
+---
+title: Board reference
+description: Readiness groups, row cells, and ordering for priority.md, the unordered backlog.md beside it, and the generated index under .canon/tasks/
+---
+
+# Board reference
+
+Applies to `.canon/tasks/priority.md`, `.canon/tasks/backlog.md`, and `.canon/tasks/index.md`, the three files beside the tasks that say which one runs next. Update `priority.md` when a task is filed, planned, dispatched, or blocked, and `backlog.md` whenever the board is swept.
+
+## Scope
+
+Governs the board files under `.canon/tasks/`: the readiness groups and their columns in `priority.md`, row order and the reason each row states, the backlog beside it, and the generated index.
+
+Does not govern:
+
+- The task files the rows link to, their filenames, format, origin lines, and archiving: `tasks.md`
+- The plan a `## Run now` row cites and the file set it declares: `plan.md`
+- The pre-compaction handoff sitting in the same folder: `session.md`
+
+## What a working board looks like
+
+A board works when a session reading it alone can answer:
+
+- Which task can a worker be handed now, and which files would it collide on?
+- What is each blocked task waiting on, and what would clear it?
+- Which task gets planned next, and what is it ranked against?
+
+A board failing these is non-conforming even when it satisfies every shape rule below.
+
+## The files
+
+`canon tasks list` reports each task's readiness from `priority.md` and `backlog.md`, so a reader never infers it from the folder.
+
+`backlog.md` is optional. A project small enough that every task it holds would be planned soon carries none, and the ordering rules below then describe the whole board.
+
+`index.md` is generated from sibling frontmatter. The folder is gitignored, so the whole-repo index walk skips it and a hook passing the changed path regenerates it instead. Never hand-edit it.
+
+The catalog is the one reader that filters nothing, so it carries a row per sibling alongside the tasks, handoffs included. Anything reading the catalog as the backlog therefore does its own filtering, and a reader that takes every row as a task reports the handoffs as queued work.
+
+## Ordering
+
+`priority.md` carries execution order and what each task is waiting on. The generated index sorts by filename and says nothing about order, so without this file board state gets reconstructed by hand every session. Why a row sits where it does inside its group is stated on the row itself, in the column that already carries what the task is waiting on, one line per row.
+
+That cell is the only home sequencing rationale has. Rationale spanning several rows, why one group of work runs before another, is carried by nothing and reaches a later session only through whoever remembers it. Naming the gap is deliberate: a second document holding it would be the version-sequencing surface this board replaced, and a row already states what it waits on, which is the part of the reasoning a reader acts on.
+
+Group tasks by readiness rather than by status, one row per task, under the columns each group fixes below. Keep it to links and blockers: tables, plus at most one sentence per section. A paragraph in `priority.md` is a defect whatever it says. Stating the shape this way is what lets a single diff fail, since a size cap only trips after the fact and every addition looks defensible on its own.
+
+### Readiness groups
+
+Readiness is three groups under fixed headings, `## Run now`, `## Up next`, and `## Needs a plan`, in that order. The names are the contract rather than a suggestion, because a board grouped by readiness under names of its own satisfies every other rule here and still reads as empty to anything counting rows under a heading. Add no fourth group. A task belongs to exactly one, and the tests are read in order.
+
+- `## Run now`: a written plan covers every open outcome, and the task carries no reason it cannot start. A collision against the files something already running touches is one such reason, and the `Touches` column is what states it. A worker is handed a task from this group alone.
+- `## Up next`: a written plan exists, and the task carries a stated reason it cannot start. The `Waiting on` column names that reason.
+- `## Needs a plan`: everything else. The task has no plan, or the plan it carries no longer describes the work.
+
+Each group fixes its own columns, which follow from the test above it rather than from preference. Neither half of the `## Run now` test is checkable without the file set and the plan sitting beside the task.
+
+A `Touches` cell is copied from its plan's own list, so it states what the branch sets out to write rather than a bound on it, and a branch outgrows it while the row still reads as it did at dispatch. Correct the cell from the branch rather than from the plan once one is running, since the plan is the prediction that already went stale and only the diff says what was written. `canon tasks plan-reach <plan>` reads that diff against every live plan and every cell in this group, and the row's owner is the one who writes the correction: a worker never edits this board.
+
+### Row order
+
+Row position inside `## Needs a plan` is the order those tasks get planned in, top first. The three tests answer whether a task can start, which is mechanical, and none of them answers which task is worth starting, which is a judgment no column holds. Position is where that judgment is recorded, so the top row is the answer to what to plan next and a reader needs no other surface to get it. The other two groups take the same reading, and it costs them little, since a group holding what is already planned is short by construction.
+
+Position alone carries it, and no rank column exists. A number beside each row is a second thing to keep in step with the order it duplicates, and the file is edited by one session at a time, so the order the rows are written in is already unambiguous. State on each row why it sits where it does, in the same cell that carries what it is waiting on. A position with no stated reason is re-derived from memory by the next session, which is the failure the ordering replaces rather than moves.
+
+### The waiting-on cell
+
+The `Waiting on` column under `## Up next` carries that reason in one of three forms. `## Needs a plan` states no file set at all, because a task with no plan has no bounded one to state. A group with no rows keeps its heading and its header row.
+
+Under `## Up next` a collision names the file held by the task already running, a sibling task names that task, and an external condition names both the condition and what would satisfy it. Naming what would satisfy it is what separates a blocked row from one nobody has examined, so a cell stating a condition with no way out of it fails the test. The header text is the contract the way the group names are, because anything reading the cell resolves the column by header rather than by position.
+
+Under `## Needs a plan` the cell carries two halves and each takes one clause: what the task needs before it can be planned, then why it sits at this position. The second clause is comparative, and it names what the row is ranked against in one of two forms: a sibling row, or the class of rows it sits in. The row `leads`, `heads`, `opens`, `closes`, `trails`, `precedes`, `follows`, or `outranks` whichever it names, or `sits under`, `above`, or `below` it. Either form puts something other than this row in the clause, which is what makes the position readable by anyone but its author.
+
+Why the task matters is not that claim, and it is what the cell drifts into. A reason naming no other row ranks against nothing, so every row reads defensible on its own and the order records when each was filed. The comparison replaces that reason rather than joining it, since the cell still takes two clauses and no third one is licensed by naming a rival in the second. A cell running past that is the paragraph this file already deletes, arriving one row at a time rather than all at once, and the group is where it costs the most, since it holds the rows nobody has read recently and is the longest group on any board that needs a backlog at all.
+
+`canon tasks validate` reads that clause back, so a cell phrased comparatively and unusually reports as unranked. The vocabulary above is the whole of what it recognizes, and widening it is a change to the check rather than something the cell may decide for itself.
+
+```markdown
+---
+title: Priority
+description: One line on what the board covers
+---
+
+# Priority
+
+## Run now
+
+| Task                            | Touches                 | Plan                                 |
+| ------------------------------- | ----------------------- | ------------------------------------ |
+| [vXX.Y <slug>](vXX.Y-<slug>.md) | <what the task touches> | [<slug>](../plans/feature-<slug>.md) |
+
+## Up next
+
+| Task | Touches | Waiting on |
+| ---- | ------- | ---------- |
+
+## Needs a plan
+
+| Task                            | Waiting on                                                                        |
+| ------------------------------- | --------------------------------------------------------------------------------- |
+| [vXX.Y <slug>](vXX.Y-<slug>.md) | <what it needs before it can be planned, and which row or class it ranks against> |
+```
+
+The tests live here so the board does not carry them. Writing them as a sentence under each heading produces the paragraph the rule above deletes, and a criterion with no home gets restated from memory every time the board is touched.
+
+## The backlog
+
+A task sits on the board when it would plausibly be planned within the next few waves, and on `backlog.md` otherwise. The call is a judgment, so restate it whenever the board is swept rather than making it once: a backlogged task rises when the work in front of it lands or the world changes under it, and a board row falls to the backlog when it stops being near-term.
+
+A mechanical test over age or origin was the alternative and neither predicts what gets picked next, which is the judgment the ordering exists to carry. Leaving everything on the board is the other alternative, and it is what produces a group too long to rank, where the ordering means nothing because nobody can hold the whole list in one reading.
+
+What the split buys is that the board is short enough for its order to be read, and what it costs is a second surface to keep. That trade only pays while the backlog stays honest about what it is, which is why it carries no order, no groups, and no readiness claim.
+
+Nothing is deleted. A backlogged task keeps its file, its findings, and its frontmatter, and the backlog row is a pointer at that file. The folder is gitignored and has no history behind it, so a row dropped without landing somewhere readable is gone with nothing to recover it from.
+
+The backlog is a flat list of links under one heading, sorted by filename. Sorting mechanically is what keeps it from reading as a queue: the order is the same order the index already sorts in, so no position on it means anything.
+
+```markdown
+---
+title: Backlog
+description: One line on what the backlog holds
+---
+
+# Backlog
+
+Unordered. Nothing here is scheduled, and a task rises to `priority.md` when it becomes near-term.
+
+- [vXX.Y <slug>](vXX.Y-<slug>.md)
+- [vXX.Y <slug>](vXX.Y-<slug>.md)
+```
+
+Add no fourth readiness group in place of this file. The three group names are the contract, and a backlog is a separate surface rather than a group because it makes no readiness claim at all: it says nobody has scheduled the task, which is a fact about attention rather than about whether the work can start.
+
+## Validation
+
+`canon tasks validate` reads the board against the tree, and what it checks, what it refuses on, and what it reports are at `canon docs tasks-validate`. Run it when the readiness claim is made rather than on a schedule, since the board is gitignored per-machine scratch and no shared moment exists to hang it on.

package/standards/commit.md

@@ -54,6 +54,11 @@ Does not govern:
 - No backslash escaping or internal double quotes
 - No conversational filler or introductory phrases
 
+## Trailers
+
+- Do not add a `Co-authored-by` trailer crediting Claude or Anthropic, by name or by address
+- The `commit-msg` hook refuses a commit carrying one, so remove the line and commit again
+
 ## Examples
 
 ### Correct

package/standards/groundwork.md

@@ -5,9 +5,9 @@ description: Folder layout, ordinal naming, reserved numbering, frontmatter and
 
 # Groundwork reference
 
-Applies to a groundwork track at `.canon/groundwork/<nn>-<slug>/`. A track measures one question that has to be settled before anyone can plan against it. The numbering inside the folder is the table of contents, so a reader opens the folder and knows where to start and what follows without an index maintained inside each file.
+Applies to a groundwork track at `.canon/groundwork/<nn>-<slug>/`. A track measures one question that has to be settled before anyone can plan against it. The numbering inside the folder is its table of contents.
 
-The folder is gitignored, and backed wherever a records remote is configured: `canon records push` and `canon records pull` protect it against the machine being lost there, refusing with `no-remote` where no remote is set, and neither protects against a compaction dropping a session's reasoning before anyone has pushed. No check reaches its contents, so every rule here holds only while a session reads it, and the handoff file has to be self-contained.
+The folder is gitignored, and backed by `canon records push` wherever a records remote is configured. Nothing backs it against a compaction dropping a session's reasoning before a push, so the handoff file has to be self-contained.
 
 ## Scope
 
@@ -26,8 +26,8 @@ Does not govern:
 
 - Name the folder `<nn>-<slug>`, a two-digit zero-padded ordinal followed by a kebab-case slug.
 - The ordinal marks a folder per track, opened once and worked over time, distinct from a file addressed by name, one already carrying its own sorting prefix, or one deliberately overwritten.
-- Claim the ordinal through `canon records ordinal groundwork <slug> --claim`, which reads the highest one already present across both `.canon/groundwork/` and `.canon/intake/` and creates the folder in the same atomic act, closing the race a read-then-create sequence leaves open between two sessions opening at once. A listing then sorts by when each folder opened rather than alphabetically, and the count includes both kinds because the two share one creation-order line.
-- With neither folder holding an entry, the first one opened takes `01`. Do not read this off the numbering inside a track, which starts at `00` on a large one and disagrees with intake's own first file.
+- Claim the ordinal through `canon records ordinal groundwork <slug> --claim`, which reads the highest one across both `.canon/groundwork/` and `.canon/intake/` and creates the folder in one atomic act, so two sessions opening at once never share a number. The two kinds share one creation-order line.
+- With neither folder holding an entry, the first one opened takes `01`, whatever number a track's own files start at.
 - Never renumber an existing folder. The ordinal is the order it opened, and a later reader cites it by that name.
 
 ## What a working track looks like
@@ -43,19 +43,15 @@ A track failing these is non-conforming even when it satisfies every shape rule
 
 ## Frontmatter and dating
 
-Every file carries `title` and `description`. `README.md` carries one field the others do not.
-
 - `title` (required): the track subject in sentence case
 - `description` (required): one line naming what the track measures
 - `date` (required, `README.md` only): the day the folder opened, as `YYYY-MM-DD`
 
-Carry the opening date as a frontmatter field rather than a sentence in the body. A date written into prose is readable by a person and by nothing that walks the folder, and the two spellings drift once both are permitted. State it once and remove the body sentence rather than leaving the pair in place.
-
-Date the folder once rather than every file. A per-file date leaves every other file stale the first time one is edited, while the opening date never rots. The checkable half is the commit each measurement was taken against, which the file holding that measurement names.
+Carry the opening date as a frontmatter field rather than a sentence in the body, since nothing that walks the folder reads prose. Date the folder once rather than every file, because a per-file date goes stale on the first edit. The checkable half is the commit each measurement was taken against, which the file holding that measurement names.
 
 ## Reserved numbers
 
-Five slots carry a fixed meaning. The rest are free, which is what lets the middle of a folder follow its subject.
+Five slots carry a fixed meaning, and the rest are free.
 
 | Number       | Holds                                           | Required                    |
 | ------------ | ----------------------------------------------- | --------------------------- |
@@ -66,9 +62,9 @@ Five slots carry a fixed meaning. The rest are free, which is what lets the midd
 | `07`         | Handoff, self-contained                         | To close                    |
 | `08`         | Spikes: method, result, and cost per experiment | Tracks that run experiments |
 
-A folder missing `06` and `07` is live. That is the only status marker, and no separate tracking is needed.
+A folder missing `06` and `07` is live, and that is its only status marker.
 
-`08` sits after the closing files because it is an appendix. It holds evidence rather than a topic, so folding it into the `02` to `05` range buries it, and a track closes with or without one.
+`08` sits after the closing files because it is an appendix of evidence rather than a topic, and a track closes with or without one.
 
 ## README.md
 
@@ -82,11 +78,7 @@ Orients. Holds no findings.
 - A `## Source citation` section stating the rule below, so a returning session picks it up from the folder
 - The phase stated out loud in the first three lines, in the form `Groundwork phase. Nothing here is a feature plan.`
 
-The file map is how a returning reader re-enters. After the decision, it is the highest-value thing in the folder.
-
-Every claim about a source outside the project carries a link to it, wherever the claim appears in the folder. A sentence asserting that a vendor documents something reads the same whether it came from a fetched page or from recall, and a later reader can neither check it nor tell the two apart.
-
-A source found and not read is listed as a lead and is never cited. That half is what keeps the rule from producing citation theater, because a link attached to a page nobody opened is worse than no link. Listing it still pays, since it stops a later pass re-searching for what this one already surfaced.
+Every claim about a source outside the project carries a link to it, wherever the claim appears in the folder. Without one, a later reader cannot tell a fetched page from recall. A source found and not read is listed as a lead and is never cited, since a link to a page nobody opened is worse than no link. Listing it stops a later pass re-searching for it.
 
 Where the track supersedes an earlier plan or an earlier folder, name it and say not to go looking for it. Without that, the old reasoning keeps circulating.
 
@@ -94,13 +86,13 @@ Where the track supersedes an earlier plan or an earlier folder, name it and say
 
 Facts before opinion. Verified measurement only, taken during this pass.
 
-- Never carry a figure from a previous session without re-measuring. Stale ratios survive a sunset that invalidates them, and every number built on one is quietly wrong.
+- Never carry a figure from a previous session without re-measuring, since every number built on a stale one is quietly wrong.
 - Mark an inference as an inference where one is unavoidable.
 - Measure only what an open question needs. A number with no question attached is the mechanism by which the groundwork becomes the work.
 
 ## 00-scope.md
 
-Written when the subject is large enough to run away. Holds constraints, risks, the open question list, and the downstream surfaces a decision would touch. A small track skips it and carries its questions inside the topic files.
+Written when the subject is large enough to run away. Holds constraints, risks, the open question list, and the downstream surfaces a decision would touch. A small track skips it.
 
 ## 06-decision.md
 
@@ -111,7 +103,7 @@ Closes the folder. Everything above it is input.
 - The items to do
 - What was considered and dropped
 
-The dropped list pays off later. It is what stops a future session re-proposing something already rejected.
+The dropped list is what stops a future session re-proposing something already rejected.
 
 ## 07-next-session.md
 
@@ -119,30 +111,28 @@ Written to survive a compaction that loses the conversation. It repeats facts he
 
 ## 08-spikes.md
 
-Evidence by experiment, sitting beside the evidence by measurement that `01-current-state.md` holds. Optional, and most tracks never open it, because measuring what is already there settles most questions.
+Evidence by experiment, beside the evidence by measurement `01-current-state.md` holds. Optional, since measuring what is already there settles most questions.
 
 Each spike carries four things:
 
-- The open question it answers, named by file and number. A spike attached to no question is the same runaway the current-state file is capped against.
-- The method, stated fully enough for a later reader to re-run it. Name the fixture and where it lived, the exact command, and how many repetitions were run. An arm pointed at a fixture inside the project measured the project, so the fixture location is part of whether the result stands.
-- The result, and which question it closes. A spike that settles nothing is still recorded, so a later pass does not pay to learn the same thing twice.
-- The measured cost, and the caveats bounding what the result proves.
-
-Cost is a report rather than a limit, and it is what makes the next spike estimable before anyone commits to it. Record it even when it comes to a single read.
+- The open question it answers, named by file and number. A spike attached to no question is a runaway.
+- The method, stated fully enough for a later reader to re-run it. Name the fixture and where it lived, since an arm pointed at a fixture inside the project measured the project, plus the exact command and the repetition count.
+- The result, and which question it closes. Record a spike that settles nothing too, so a later pass does not pay for it twice.
+- The measured cost, even for a single read, and the caveats bounding what the result proves. Cost is a report rather than a limit, and it makes the next spike estimable.
 
-Start a spike against a sample and scale up only once the sample shows the method works. Bound the sample on all three of input size, duration, and spend, since fifty minutes of audio is a runtime and a bill before it is a file size, and three minutes of it usually shows whether the pipeline runs at all. The same holds for a dataset, an image set, or a batch of queries. Record the sample's bounds and the figure for the full input in the spike, so a reader can tell what the result was measured on and what the scale-up costs. The rule reaches only a track, since that is the surface that reads this standard, and nothing checks that a spike ran small first, so it holds only while a session reads it.
+Start a spike against a sample bounded on input size, duration, and spend, and scale up only once it shows the method works. Record the sample's bounds beside the figure for the full input.
 
-A spike also leaves files behind, and they split on whether a later reader needs the file to check a claim rather than on whether it is markdown or re-runnable. A file a reader opens to verify how a result was produced or what it showed lives inside the track. A file that is only bulk input, such as a large fixture or a copied asset, stays outside it wherever the surface driving the spike puts it. Three subfolders inside the track carry the first kind, and none takes a number, since numbering is the read order over the files a reader opens in sequence and these are reached from the claim that cites them instead:
+A file a reader opens to verify how a result was produced or what it showed lives inside the track, and bulk input such as a large fixture stays outside it. Three unnumbered subfolders carry the first kind, since a reader reaches them from the citing claim rather than in read order:
 
 - `evidence/`: what a run produced and the record cites, being a recording, a render, or a frame pulled from one, beside the file citing it.
-- `scripts/`: the arm scripts and harnesses a spike ran. An arm script is re-runnable, and it is also what a reader opens to check the method, so this refines the earlier split, which sorted on re-runnable alone, and does not contradict it.
+- `scripts/`: the arm scripts and harnesses a spike ran, which a reader opens to check the method.
 - `clones/`: checkouts and copies of outside material a claim rests on, kept small enough to hold in the folder. A checkout too large to keep is cited by its address and commit instead.
 
-`spikes/`, `web/`, and `research/` were considered and folded into these, so do not reopen them. A spike's files sit under the three above, and a fetched page belongs in `clones/`. The `web/` case is the arguable one, since a screenshot of a reference site could sit apart, and it folds into `evidence/` because that is where a cited artifact already lives.
+Open no other subfolder: `spikes/`, `web/`, and `research/` fold into these three, with a fetched page in `clones/` and a reference-site screenshot in `evidence/`.
 
-Reach for a test harness the project already carries before building one. A track needing an experiment no existing harness can express has found a finding, and it belongs in the folder rather than in a new abstraction.
+Reach for a test harness the project already carries before building one. An experiment no existing harness can express is a finding for the folder, not a new abstraction.
 
-One method error is worth naming, because it is made rather than imagined. Counting matches in a transcript overstates whether a file was read, since an instruction naming a path puts that path in the transcript whether or not anything opened it. The check is the tool call.
+Never count transcript matches to show a file was read. An instruction naming a path puts it in the transcript whether or not anything opened it, so the check is the tool call.
 
 ## Open questions
 
@@ -158,7 +148,7 @@ Every open question carries a lean, wherever it appears. A bare numbered list ha
 - On a measurement rather than a judgment, write `- Leaning: none, needs measuring` and drop the overturn line. A guess at a number is worse than an admission.
 - Mark each question open or answered, and repeat the open ones at the end of the file they belong to. That gives the decision file its agenda for free.
 
-A lean is weaker than the suggestion a plan file carries. It records the current read on a question still open by definition, not a decision to accept by default at execution time.
+A lean is weaker than a plan's suggestion: it records the current read on an open question, not a decision to accept at execution time.
 
 ## Conventions
 
@@ -170,9 +160,8 @@ A lean is weaker than the suggestion a plan file carries. It records the current
 
 - **The groundwork becomes the work.** Gathering expands until the measuring costs more than the change it justifies. Cap it, and drop any thread with no question attached.
 - **Deciding by omission.** Closing a track while an unresolved question quietly fails an outcome. Resolve it or record it as knowingly accepted.
-- **Recording a constraint discovered while defending a decision.** Check a constraint against the alternative design before writing it down, or a fact about the current shape gets written up as inherent to the problem.
+- **Recording a constraint discovered while defending a decision.** Check it against the alternative design first, or a fact about the current shape reads as inherent to the problem.
 - **A plan written before the groundwork.** Every track that has done this had to supersede the plan it wrote.
-- **The date left in the body.** A frontmatter field and a sentence both claiming the opening date resolve to whichever a reader happens to hit, and only one of them is readable by a walker.
 
 ## Template
 

package/standards/index.md

@@ -8,6 +8,7 @@ subtitle: Reference docs for consistent authoring across the toolkit and target
 Reference docs for consistent authoring across the toolkit and target projects.
 
 - [Architecture reference](architecture.md): Shape and content rules for canon/ARCHITECTURE.md
+- [Board reference](board.md): Readiness groups, row cells, and ordering for priority.md, the unordered backlog.md beside it, and the generated index under .canon/tasks/
 - [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
@@ -35,7 +36,7 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Slug reference](slug.md): Transform from a git branch name to a slug, and the three responses to an empty result
 - [Snippet reference](snippets.md): Snippet reference and authoring conventions
 - [Standard reference](standard.md): Shape and content rules for authoring a standard
-- [Tasks reference](tasks.md): Folder layout, filename convention, readiness groups, and content rules for .canon/tasks/
+- [Tasks reference](tasks.md): Folder layout, filename convention, file format, origin lines, and archiving for task files under .canon/tasks/
 - [Teach reference](teach.md): Workspace layout, ordinal naming, frontmatter, and the mission and learning-record formats for a learning workspace
 - [Versioning reference](versioning.md): Phase label vs semver discipline across tasks, PRs, reviews, issues, commits, and tags
 - [Wiki reference](wiki.md): Folder split, frontmatter, naming convention, and sourcing for a wiki reference page

package/standards/plan.md

@@ -7,7 +7,7 @@ description: Filename and slug, required sections, the suggested-and-answer cont
 
 Applies to a feature plan at `.canon/plans/feature-<slug>.md`. One file holds one concern, written before implementation starts and read by whatever executes it, so it has to carry the scope without the conversation that produced it.
 
-The folder is gitignored, and backed wherever a records remote is configured: `canon records push` and `canon records pull` protect it against the machine being lost there, refuse with `no-remote` where it is not, and protect nothing against a plan deleted before anyone has pushed. That is why the archive step below is a move rather than a cleanup.
+The folder is gitignored, and backed by `canon records push` wherever a records remote is configured. Nothing backs a plan deleted before a push, which is why the archive step below is a move rather than a cleanup.
 
 ## Scope
 
@@ -39,7 +39,7 @@ A plan failing these is non-conforming even when it satisfies every shape rule b
 
 - Name the file `feature-<slug>.md`, with `<slug>` two to four kebab-case words naming the concern.
 - Write one concern per file. A request spanning two independent concerns takes two plans rather than one bundling both, since a bundled plan cannot be executed by two sessions or abandoned by half.
-- A staged batch is a concern of its own and takes its own file rather than a `**Batch N**` sub-heading inside one plan's `**Files to touch:**`. `canon tasks plan-branch` derives one branch from one plan filename, so every batch sharing a file has nothing left to open a pull request against once an earlier batch merges under that name. State a batch's dependency on the ones before it in its own `**Constraints:**`.
+- A staged batch is a concern of its own and takes its own file rather than a `**Batch N**` sub-heading inside one plan's `**Files to touch:**`. One plan filename derives one branch, so batches sharing a file have nothing to open a pull request against once the first merges. State a batch's dependency on the ones before it in its own `**Constraints:**`.
 - Derive the slug from the concern rather than from a branch, because the plan is written before the branch exists.
 - Give the branch that executes the plan the same slug. A later surface finds the plan from the branch name and finds nothing when the two spellings differ.
 
@@ -60,33 +60,29 @@ The document opens with `# Feature: <short title>` and one paragraph stating wha
 | `**Questions:**`      | numbered open decisions, each with a suggestion and an answer slot        | Always        |
 
 - Write each marker as the table gives it. `Summary` opens the prose a reader scans, so it takes an H2, and the six that follow are labels over lists rather than sections of prose.
-- A section written in the other spelling is still that section. `## Risks` and `**Risks:**` name one thing, and a plan carrying either has stated its risks, so neither reads as an omission. Write the table's form in a new plan and leave an existing plan's spelling alone.
-- Both spellings break a depth run, so `canon markdown audit` reads either as the seam it is and reports a plan for a section that genuinely runs long rather than for its whole body. The markdown standard states the rule.
+- A section written in the other spelling is still that section, since `## Risks` and `**Risks:**` name one thing. Write the table's form in a new plan and leave an existing plan's spelling alone. Either spelling breaks a depth run.
 - Write `None identified.` under a required section with nothing to report rather than dropping the marker. A dropped section and an unconsidered one read identically.
 - Aim `## Summary` at a person scanning the plan, not at the session executing it. The other sections carry what execution needs.
 - Give every `**Files to touch:**` entry a backticked path and something said about it. A bare path states scope and not intent, and the reason is what an executing session checks its edit against. Lead with the path or lead with a label carrying the path, whichever reads better for the entry.
-- Separate the two halves with a colon, and keep every path the entry declares ahead of it. What sits before the colon is the entry's subject and reads as a target, so both sides of a rename belong there and a file merely cited by the reason does not. A reason is free to name another path, and one entry that did was read as declaring a file its branch never wrote.
-- Read the list as what the branch sets out to write rather than as a bound on it. The ship chain writes past it on nearly every branch, since the sync skills refresh whichever context entry and public doc the change reaches, and no planner can name those before the change exists. `canon tasks plan-reach <plan>` reads the branch back against this list and every other live plan, ahead of the pull request.
+- Separate the two halves with a colon, and keep every path the entry declares ahead of it. What sits before the colon reads as a target, so both sides of a rename belong there and a file merely cited by the reason does not.
+- Read the list as what the branch sets out to write rather than as a bound on it, since the doc syncs at ship write past it on nearly every branch. `canon tasks plan-reach <plan>` reads the branch back against this list and every other live plan.
 - State every count and every claim about the tree as measured during the pass that wrote the plan. A figure carried in from a summary or an earlier session is the most common way a plan ships the wrong scope.
 - Prefer a short plan over a padded one. A section filled to look thorough costs the reader the same attention as one that matters.
 
 ### Constraints
 
-A constraint naming a surface to leave alone forbids two different acts, and it says which. A constraint carrying only the surface leaves the executing session to guess.
+A constraint naming a surface to leave alone says which of two acts it forbids, rather than leaving the executing session to guess.
 
-- Forbid conforming that surface to whatever shape the change introduces. This is what a scope constraint means, and it keeps the branch from growing a second concern.
+- Forbid conforming that surface to whatever shape the change introduces, which keeps the branch to one concern.
 - Never forbid retargeting a pointer the change breaks. A rename, a split, or a deletion that leaves a citation behind ships a dangling reference, so repairing it is required work rather than scope creep.
-- Decide both acts for every surface the constraint names. Carving the distinction out for one file and leaving its siblings under the bare wording ships one correct call beside one broken reference.
+- Decide both acts for every surface the constraint names, not for one file among its siblings.
 
-A constraint measured against work in flight expires when that work merges, and a plan is read some time after it is written. Stamp the block with what it was measured against so a reader can test whether it still holds.
+A constraint measured against work in flight expires when that work merges, so stamp the block with what it was measured against.
 
-- Give the stamp its own leading bullet, written as Measured against `<commit>` on <YYYY-MM-DD>. One stamp covers the whole block however many tracks the constraints below it name, since a plan is written against the tree once.
-- Stamp the commit and not the track names. The constraint already names each track by its work and its file set, so a second list of names is a second place to keep in step. A date alone does not separate two plans written the same afternoon on either side of three merges, which is why the commit is the part a reader tests against.
-- Re-test a stamped constraint before honoring it with `git fetch origin main --quiet && git log <commit>..origin/main --oneline -- <the paths the constraint names>`. Any commit it reports means the track landed and the constraint is dead. Fetch inside the same command, since a remote-tracking ref left behind reports fewer merges than have landed and reads a dead constraint as live, which is the failure the stamp exists to remove.
-- Scope the log to the paths rather than reading every subject. A squashed merge carries a pull request number while the constraint names its track by work and file set, so an unscoped log leaves the reader matching subjects.
-- Read an unstamped constraint as unverified rather than as live. There is no commit to anchor the log against, so confirming one costs the open pull request list against the named paths, which is the work a stamp removes. Every plan written before this rule carries an unstamped block, which is why the default sits here rather than in a sweep over the live folder.
-
-A dead constraint fails silently in the expensive direction. A session honoring one ships the dangling citation the change created and reports success, where a session crossing a live constraint collides visibly and is caught.
+- Give the stamp its own leading bullet, written as Measured against `<commit>` on <YYYY-MM-DD>. One stamp covers the whole block.
+- Stamp the commit rather than the track names or a date alone. The constraint already names each track, and a date does not separate two plans written on either side of a merge.
+- Re-test a stamped constraint before honoring it with `git fetch origin main --quiet && git log <commit>..origin/main --oneline -- <the paths the constraint names>`. Any commit it reports means the track landed and the constraint is dead. Fetch in the same command and scope the log to the paths, since a stale remote-tracking ref reads a dead constraint as live and a squashed subject names no track.
+- Read an unstamped constraint as unverified rather than as live, and confirm it against the open pull request list for the named paths.
 
 A constraint naming a `.canon/ready/` folder is a third shape beside the two above. It makes that folder's files the verbatim source for the paths this plan's `**Files to touch:**` lists, per `ready.md`, so the executing session copies those paths rather than authoring them.
 
@@ -104,8 +100,8 @@ A constraint naming a `.canon/ready/` folder is a third shape beside the two abo
 ### Review focus
 
 - Name each input or state that would break the change if the implementation got it wrong, one bullet each, with what the change must do there.
-- Write it for the reviewer rather than the builder. The session writing the plan understood the risk before any diff existed, and this section is where that understanding reaches the review pass.
-- Keep it apart from `**Risks:**`. A risk is something the work might collide with, and a focus item is something the finished diff must be shown to handle, so a reviewer confirms the second and the executing session plans around the first.
+- Write it for the reviewer rather than the builder, since this section is where the planner's understanding of the risk reaches the review pass.
+- Keep it apart from `**Risks:**`. A risk is something the work might collide with, and a focus item is something the finished diff must be shown to handle.
 
 ## The suggested-and-answer contract
 
@@ -131,32 +127,22 @@ An execution that deviates rewrites the suggestion into the form below, leaving
 - Write `- Suggested: needs your call, <why>` where the answer turns on preference rather than on a technical default. Fabricating a default there hides an open question behind an accepted answer.
 - Never fill an `- Answer:` slot on behalf of the person who owns it. Recording the pick as the suggestion is what the suggestion line is for.
 - Rewrite the `- Suggested:` line to the pick execution made when it deviates from an unanswered question, and leave the slot blank. The prohibition above reaches the answer line alone, so the suggestion line is where a deviation goes.
-- Open the rewritten text with `overridden at execution to <pick>,` and follow it with the measurement that moved the pick. The phrase is fixed, because a suggestion carrying a number is the ordinary shape of an authored one and says nothing about who wrote it.
+- Open the rewritten text with `overridden at execution to <pick>,` and follow it with the measurement that moved the pick. The fixed phrase is what tells an override from an authored suggestion, which routinely carries a number too.
 - Take a deviation from an answered question back to whoever answered it rather than rewriting either line. A filled slot is a decision already made, and a suggestion rewritten under one leaves the plan holding two picks with no default resolving them.
 - Answer in place when a question is settled in conversation, so the file and the decision do not disagree.
 
-The fixed phrase is what a later reader tells an override by, and the measurement alone is not, since an authored suggestion routinely carries a number of its own and a reader meeting one learns nothing about who put it there. The plan is archived at ship, so the same deviation takes one line in the open task's `## Findings` naming what shipped. That is one fact in two registers, the plan holding why the pick moved and the task holding what the tree now has, rather than two records to keep in step.
+The plan is archived at ship, so the same deviation takes one line in the open task's `## Findings` naming what shipped. The plan holds why the pick moved and the task holds what the tree now has.
 
-This contract inverts the one an intake folder keeps, where an empty slot means unread and acceptance is typed out. A plan is written and read in one sitting with every question already surfaced, so silence is a usable default here and is not one there. Both files state the inversion, since a contract read on only one side of a boundary is the one that gets applied to the wrong document.
+This contract inverts the one an intake folder keeps, where an empty slot means unread and acceptance is typed out. A plan is written and read in one sitting with every question already surfaced, so silence is a usable default here and is not one there.
 
 ## Lifecycle
 
-- Write the plan before implementation starts, and treat it as the scope of the run that executes it.
+- Write the plan before implementation starts, and treat it as the scope of the run that executes it. A subject that has to be measured before anyone can plan against it takes a measurement track first.
 - Keep every plan at one root. A plan copied into each parallel working tree forks, and the copies answer the same question differently.
 - Amend the plan in place when a decision changes mid-flight. Do not append a second passage narrating the change, which leaves a reader to work out which of two answers is current. An execution-time deviation from a suggestion is one such amendment, and the contract above fixes which line takes it.
-- Move the plan to `.canon/plans/archive/` when the work it describes ships or is declined. Never delete it, because the plan is where the rejected alternative is written down and nothing else records it. The archive nests inside `.canon/plans/` rather than sitting beside it as `.claude/plans-archive/`, so an older layout is a flat sibling by that name and a current one is not.
+- Move the plan to `.canon/plans/archive/` when the work it describes ships or is declined. Never delete it, because the plan is where the rejected alternative is written down. A flat `.claude/plans-archive/` sibling is the older layout.
 - Write the plan in the same session that opens the task it serves. The session executing it later inherits reasoning it would otherwise re-derive.
 
-## Anti-patterns
-
-- **The plan written before the measuring.** A subject that has to be measured before anyone can plan against it belongs in a measurement track, and every plan that skipped that step had to be superseded.
-- **The bundled plan.** Two concerns under one slug cannot be split later without rewriting both halves.
-- **The question with no suggestion.** It reads as thoroughness and lands as a blocked run.
-- **The answer filled in by the author.** A slot holding the writer's own pick destroys the only signal that anyone else agreed.
-- **The deviation recorded off the plan.** The reasoning lands in a pull request description no later reader of the plan opens, and the archived plan reads as though its suggestion held.
-- **The count carried in.** A figure quoted from an earlier session survives the change that invalidated it, and the scope built on it is quietly wrong.
-- **The plan deleted on ship.** The considered-and-dropped reasoning goes with it, and the next session re-proposes what this one rejected.
-
 ## Template
 
 ```markdown

package/standards/readme.md

@@ -147,85 +147,16 @@ See the [contributing guidelines](CONTRIBUTING.md).
 
 ### Correct
 
-````markdown
-# Auth SDK
-
-Lightweight authentication library for Node.js with OAuth2 and JWT support.
-
-## Features
-
-- OAuth2 provider integration (Google, GitHub, Azure)
-- JWT token generation and validation
-- Session management with Redis support
-- TypeScript support with full type definitions
-
-## Installation
-
-```bash
-npm install auth-sdk
+```plaintext
+Lightweight authentication library for Node.js with OAuth2 and JWT support.  # one line naming what it is
+## Quick start                                                               # sentence case, a runnable snippet follows
+[MIT](LICENSE)                                                               # links the license file
 ```
 
-## Quick start
-
-```javascript
-import { AuthClient } from 'auth-sdk'
-
-const client = new AuthClient({
-  provider: 'google',
-  clientId: process.env.CLIENT_ID,
-})
-
-const user = await client.authenticate(code)
-```
-
-## Documentation
-
-Visit [docs.auth-sdk.dev](https://docs.auth-sdk.dev) for full API reference.
-
-## Support
-
-- Report bugs via [GitHub Issues](../../issues)
-- Community support on [Discord](https://discord.gg/example)
-
-## License
-
-[MIT](LICENSE)
-````
-
 ### Incorrect
 
-````markdown
-# Auth SDK
-
-This is a seamless and powerful authentication library that allows developers to easily integrate robust OAuth2 functionality.
-
-## Why Use This?
-
-Basically, this library is just amazing and will revolutionize how you handle auth.
-
-## Installation
-
-Simply run the following command to install:
-
-```bash
-npm install auth-sdk
+```plaintext
+## Why Use This?                                 # title case, and a pitch rather than a feature list
+Simply run the following command to install:     # filler qualifier before the command
+Copyright (c) 2026 Example Corp                  # license text inline rather than linked
 ```
-
-## API Documentation
-
-### AuthClient Class
-
-#### Constructor
-
-constructor(options: AuthOptions)
-
-[...full API docs inline, should link to external docs...]
-
-## License
-
-MIT License
-
-Copyright (c) 2026 Example Corp
-
-[...full license text, should reference LICENSE file...]
-````

package/standards/requirements.md

@@ -14,7 +14,7 @@ Governs the product-scope document at `canon/REQUIREMENTS.md`: problem, goals, n
 Does not govern:
 
 - Rationale for a technical choice: `architecture.md`
-- Execution order across the work the scope generates: `tasks.md`
+- Execution order across the work the scope generates: `board.md`
 - Per-domain structure and narrative: `context.md`
 
 ## What goes in
@@ -40,7 +40,7 @@ Use `## Problem`, `## Goals`, `## Non-goals`, `## MVP features`, `## Tech stack`
 
 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.
 
-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`, which orders them by readiness, so a section here states what is wanted and never when it lands.
+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.
 
 ## Distribution