@erclx/canon 4.0.0

package/standards/tasks.md

@@ -0,0 +1,254 @@
+---
+title: Tasks reference
+description: Folder layout, filename convention, readiness groups, and content rules for .claude/tasks/
+---
+
+# Tasks reference
+
+Applies to `.claude/tasks/`. Tracks what is being built and why, at the level of features and outcomes. One file per task.
+
+Update when a task starts, completes, or changes scope. When to open a task at all is project policy, not a shape rule, and lives in `CLAUDE.md`.
+
+The folder is gitignored. Board state changes when work ships rather than when a branch is written, so committing it would put a claim about the future into the diff of an unrelated pull request. The git log records what shipped.
+
+## Scope
+
+Governs the task board under `.claude/tasks/`: folder layout, filenames, frontmatter, file format, origin lines, execution ordering, the backlog beside it, and archiving.
+
+Does not govern:
+
+- The plan file a task cites, its sections, and its answer contract: `plan.md`
+- Phase-label format and which surfaces a label may appear on: `versioning.md`
+- Architectural reasoning that outlives a task: `architecture.md`
+- The pre-compaction handoff sitting in the folder, its filename and its sections: `session.md`
+- When a project opens a task at all, which is project policy rather than a shape rule
+
+## Layout
+
+```plaintext
+.claude/tasks/
+├── index.md              ← generated, never hand-edited
+├── priority.md           ← hand-maintained execution order
+├── backlog.md            ← unordered, what is not being scheduled
+├── session-<slug>.md     ← optional, what a compaction is about to destroy
+├── v09.0-sync-paths.md
+└── v13.0-toolkit-drift.md
+```
+
+One file per task is what keeps the board safe under parallel sessions. Two sessions working different tasks never write the same file, which matters because a gitignored board has no history to recover a clobbered write from.
+
+Siblings sit in the folder without being tasks, and each earns its place by being governed somewhere. `index.md`, `priority.md`, and `backlog.md` are governed here. Every `session-` file is a pre-compaction handoff governed by `session.md`, and each is optional: a project whose sessions never approach a compaction carries none. Anything filtering the folder to tasks skips all of them, so a name outside the set is a task whatever it holds.
+
+`backlog.md` is optional too. 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.
+
+The handoff takes one file per session for the reason a task does. A single shared path puts two sessions closing near each other on one file that neither can watch the other write, and the loser leaves no trace on a board with no history behind it.
+
+`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. That is what a folder catalog is for, and the handoffs are what make it worth stating: a board accumulates one row per session that ever wrote one, with nothing pruning them. 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.
+
+The `claude-tasks` skill creates and archives task files. `claude-docs` marks outcomes `[x]` in an existing file and sweeps the plans those tasks cite. Neither does the other's job.
+
+## 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 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.
+
+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` 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. 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.
+
+```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 why it sits here> |
+```
+
+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 `docs/agents/tasks.md`. 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.
+
+## Filenames
+
+`vXX.Y-<slug>.md`, where the version is the phase label zero-padded to two digits and the slug is kebab-case.
+
+Padding is load-bearing. Index entries sort by filename and nothing else, so a bare `v9.0` sorts after `v15.0` and the catalog reads out of board order. `standards/versioning.md` governs the label itself and permits free renumbering, so expect the occasional rename. Nothing points at a task filename, since a `Plan:` line runs from task to plan rather than the reverse.
+
+## Frontmatter
+
+Every task file carries both fields. The index walker fails the whole folder when one is missing, which surfaces the gap on the next edit.
+
+```yaml
+---
+title: 'v13.0: Detect and close toolkit drift in target projects'
+description: Record what a target installed and report the delta against the toolkit
+---
+```
+
+- `title`: the phase label and the task title, matching the H1. Quote it, since a leading `vX.Y:` reads as a key to a YAML parser.
+- `description`: what the task achieves, in one line. A session reads this in the index to decide whether to open the file.
+
+## File format
+
+Two headings, `## Outcomes` and `## Findings`. Outcomes are future and checkable, findings are past and factual, and as flat bullets at the same indent they are visually identical. A heading separates them at no cost.
+
+Add no third heading. Status stays inline on an outcome rather than becoming an "In progress" section.
+
+Size the outcomes so one pull request closes all of them. A task whose outcomes span two pull requests ships the first half and leaves the rest open, with nothing recording which outcomes the merged work covered, so the board reads as in-progress work that no branch is carrying. Split the task before handing it off rather than after. This is what `## Archiving` below depends on, since a task closes whole or not at all.
+
+Prefix the H1 with the `vX.Y:` phase label, then a short title whose form depends on the task type:
+
+- Feature: an outcome describing what the user can now do
+- Fix: a problem statement describing what is wrong
+- Chore: an imperative describing what is being done
+
+```markdown
+---
+title: 'vX.Y: Title'
+description: One line on what this task achieves
+---
+
+# vX.Y: Title
+
+Plan: [feature-<slug>](../plans/feature-<slug>.md)
+Groundwork: [<slug>](../groundwork/<slug>/)
+Intake: [<slug>](../intake/<slug>/)
+Issue: #NNN
+Pull request: #NNN
+
+Why this task exists and what it depends on.
+
+## Outcomes
+
+- [ ] Outcome: what done looks like
+- [ ] Outcome: what done looks like
+
+## Findings
+
+- What constrains the task, dated where it matters.
+
+> Test strategy: <unit | component | e2e | visual | manual>, what is being verified
+```
+
+## Origin
+
+Every task names where it came from, through a `Plan:`, `Groundwork:`, `Intake:`, or `Issue:` line under the title. Include each only when the file, folder, or issue it names exists.
+
+A task with no origin is either lost context or work nobody decided to do. The invariant runs both ways, and the second direction is the one that bites: a groundwork track, an intake folder, or an open issue that no task points at is work already decided and on its way to being forgotten.
+
+An intake folder answers that direction at folder scope rather than item scope, since one dump dispositions many items and most close without ever becoming a task. What names a folder is every item answered and no task citing it, on the board or in the archive. That is a dump nobody acted on. Counting the archive beside the board is what separates it from one already promoted and shipped, and a check reading the board alone calls every finished folder abandoned.
+
+`Plan:`, `Groundwork:`, and `Intake:` name their target as a markdown link whose text is the file or folder stem, so the line resolves on a ctrl-click the way `priority.md` rows already do. Write the path relative to `.claude/tasks/`, which makes it `../plans/`, `../groundwork/`, and `../intake/`. A path written from the project root renders as a link and resolves to nothing in an editor rooted at the project. `Issue:` stays a bare `#NNN`, since an issue number is not a path and a full URL would write the remote into a gitignored file.
+
+Phase-label format and where labels may appear are governed by `standards/versioning.md`.
+
+`Plan:` points at `../plans/feature-<slug>.md` while the task is open. Once the task ships and the plan is archived, it points at `../plans/archive/feature-<slug>.md`, and at `../../plans/archive/feature-<slug>.md` once the task itself is archived a folder deeper. Retarget both halves of the link rather than dropping it, so a completed task still leads to the reasoning behind it.
+
+A project that archived plans before the folder nested under `.claude/plans/` holds closed tasks pointing at `../plans-archive/`, or at `../.tmp/plans-archive/` from before the durable records left the scratch tree. Each form resolves against the files it names, so leave those pointers where they are. A named route now moves the folder and retargets its pointers together, but no automation runs it, so an unmigrated project keeps holding the old spelling until someone does, and a task retargeted without its plan moving leads nowhere.
+
+One plan per task. A plan cited by two tasks is a misfile rather than a shape to design for, which is why the sweep counts citations before archiving: the count is a guard against the misfile stranding a pointer, not support for the shape.
+
+`Groundwork:` points at `../groundwork/<slug>/`, the folder `claude-groundwork` fills. It names the surface it points at the way `Plan:` does. Use this key alone. `Research record` and `Decision record` are earlier spellings of the same thing and both convert to it.
+
+`Intake:` points at `../intake/<slug>/`, the folder an intake pass fills. Use it rather than `Groundwork:`, because a groundwork track measures one question in depth while an intake dispositions many across a tree, and one key covering both loses which kind of pass produced the task. The line names the folder rather than an item inside it. A task routinely promotes several items at once, so an anchored line would name one and drop the rest, and the item numbers belong in that task's `## Findings`.
+
+`Pull request:` records which pull request carries the task's work, as a bare `#NNN` the way `Issue:` does. It is not an origin, so a task without one is well-formed. `git-pr` writes it when a pull request opens, which is the one step that always runs whether the chain drives it or a person does.
+
+The line is what lets a merge close its own task. Every merge on `main` is a squash carrying the number in its subject, so the number survives where a branch name does not, and `canon tasks archive --pull-request <n>` resolves the task from it. Without the line the board can only be swept blind, and a blind sweep cannot tell a shipped task from an abandoned one. One task, one pull request: two tasks naming the same number refuse to archive rather than both moving.
+
+## What goes in
+
+- Task entries describing observable behavior, one outcome per line
+- A test strategy line naming the mechanism and what it verifies
+- Findings stating what constrains the task, including blockers and dependencies
+- A deviation from the plan's suggestion, in one line naming what moved the pick. The plan is archived at ship and holds the reasoning, so this register carries what shipped.
+
+## What does not go in
+
+- Class names, file paths, function names, or prop names in any entry or title
+- Code-level steps or implementation detail. Behavioral specifics are fine.
+- Architectural reasoning that outlives the task. A finding explains why this task is shaped as it is. A decision the system keeps after the task closes belongs in `.claude/ARCHITECTURE.md`.
+- Narrative of the session that produced the task. A finding states what constrains the task, so what was probed, what it cost, and who decided belongs in the groundwork folder the `Groundwork:` line names. A task with no groundwork folder cuts the narrative rather than relocating it, since the board is not the fallback destination for it.
+- "In progress" or "Blocked" headings. Note status inline on the outcome instead.
+- Sequencing rationale or which version is active. Why this task is planned before its neighbors goes on its row in `priority.md`, in the cell that already carries what it is waiting on. Rationale wider than one row has no home at all, so cut it rather than filing it here.
+
+## Archiving
+
+Never delete a task file. A shipped task moves to `.claude/tasks/archive/` under its own name, and the live index regenerates without it. `canon tasks archive` owns that move, and what it does and what it refuses on are at `docs/agents/tasks.md`.
+
+The archive nests inside `.claude/tasks/` rather than sitting beside it as a flat `.claude/task-archive/`. Nesting is what lets a reader tell the two shapes apart on sight: the flat sibling is what a binary predating this convention still writes, so meeting one names an older checkout rather than a second archive to reconcile against this one.
+
+One destination rather than a per-project choice is what lets the move happen without asking. It mirrors the plans archive at `.claude/plans/archive/`, sitting inside the folder it archives the same way, and it inherits the board's own ignore entry rather than needing one of its own. The cost is that an archived task does not appear in diffs, which is the cost the live board already carries.
+
+Archiving a task does not archive its plan. `claude-docs` owns the plans sweep and moves a plan only when the closing task is its last live citation, so the sweep runs before the archive rather than after it. The sweep finds its work by scanning the live folder, and a task archived first is beyond its reach for good, leaving the plan with no live task citing it and an archived task pointing at a path nothing will retarget.
+
+The `claude-docs` sweep states that ordering in its own body rather than reading it back from a command, which is a duplication accepted with a reason rather than an oversight. A skill reaches a target the moment it merges and the CLI reaches one only when a release publishes, so a body calling a verb the installed `canon` predates gets no record back and sweeps nothing. The two spellings therefore have to agree by hand until a release carries the verb, and the failure they guard against is a plan stranded by the form its citation was written in.
+
+A task with an open outcome stays on the board. Close it, or cut it from the task when the work is being abandoned, so what was dropped is recorded rather than inferred from an archived file. The sweep is gated on the same condition, so archiving around an open outcome also leaves the plan behind.

package/standards/teach.md

@@ -0,0 +1,153 @@
+---
+title: Teach reference
+description: Workspace layout, ordinal naming, frontmatter, and the mission and learning-record formats for a learning workspace
+---
+
+# Teach reference
+
+Applies to a learning workspace at `.claude/teach/<nn>-<topic>/`. One workspace holds one subject studied across sessions, and it carries both halves of what studying produces: the durable reference material a reader consults later, and the disposable lessons a learner works through once.
+
+The folder is gitignored. Its markdown half is written in a format the authoring gates read, so a page promoted out of it later needs no conversion.
+
+## Scope
+
+Governs a learning workspace under `.claude/teach/<nn>-<topic>/`: folder layout, ordinal naming, frontmatter, and the mission and learning-record formats.
+
+Does not govern:
+
+- The frontmatter, entry shape, and ordering of the glossary the workspace holds: the `claude-teach` skill, which carries that reference
+- What a lesson teaches, how it sequences difficulty, and what makes one worth returning to, which belong to the surface driving the workspace
+- Where a durable page goes once it leaves the workspace, which belongs to the routing test the destination surface states
+- One question measured in depth before anyone can plan against it: `groundwork.md`
+- A dump of many findings filed by domain, each carrying its own verdict: `intake.md`
+- Voice, rhythm, and sentence construction: the `write-human` skill
+- Headings, punctuation, word choice, and file references: `markdown.md`
+- When a workspace opens at all, and the procedure that runs one, which belong to the surface driving it
+
+## What a working workspace looks like
+
+A workspace works when a session returning after weeks can resume from the folder alone:
+
+- Which subject is being learned, and what will the learner be able to do when the mission is finished?
+- Which sources stand behind the material, and which were found and never opened?
+- What has the learner already been through, and what did they get wrong?
+- Which pages here are durable reference material, and which are disposable?
+
+A workspace failing these is non-conforming even when it satisfies every shape rule below.
+
+## Folder name
+
+- Name the folder `<nn>-<topic>`, a two-digit zero-padded ordinal followed by a kebab-case topic slug.
+- Take the ordinal from the highest one already present, incremented. A listing then sorts by when each workspace opened rather than alphabetically.
+- Use two digits on the folder and four inside it. A person opens far fewer workspaces than one workspace holds lessons.
+- Never renumber an existing folder. The ordinal is the order it opened, and a later reader cites it by that name.
+
+## Layout
+
+| Path                  | Holds                                                  | Required |
+| --------------------- | ------------------------------------------------------ | -------- |
+| `MISSION.md`          | The subject, the learner's starting point, and success | Always   |
+| `RESOURCES.md`        | Sources read and sources found but not opened          | Always   |
+| `GLOSSARY.md`         | Terms the subject defines, one entry each              | Always   |
+| `NOTES.md`            | Session scratch that belongs to no other file          | Optional |
+| `reference/<slug>.md` | Durable reference pages, the promotable half           | Optional |
+| `learning-records/`   | Numbered records of what the learner was taken through | Optional |
+| `lessons/`            | Numbered lessons, generated and disposable             | Optional |
+| `assets/`             | Files several lessons share, including the stylesheet  | Optional |
+
+Only the markdown half answers to a conformance check: `MISSION.md`, `RESOURCES.md`, `GLOSSARY.md`, `NOTES.md`, `reference/`, and `learning-records/`. A lesson is generated markup that nothing downstream cites, so this standard fixes its filename and its location and says nothing about what it contains.
+
+## Frontmatter
+
+Every markdown file carries `title` and `description`. `MISSION.md` carries one field the others do not.
+
+- `title` (required): what the file covers, in sentence case
+- `description` (required): one line naming what a reader gets from it
+- `date` (required, `MISSION.md` only): the day the workspace opened, as `YYYY-MM-DD`
+
+Date the workspace once rather than every file. A per-file date leaves every other file stale the first time one is edited, and the opening date never rots.
+
+## File naming
+
+- Number a lesson and a learning record `0001` upward, as `<nnnn>-<slug>.html` and `<nnnn>-<slug>.md`. The number is read order and never changes.
+- Name a reference page for its subject alone, with no number. A reference page is looked up rather than worked through, so an ordinal on one implies an order no reader follows.
+- Keep one shared stylesheet under `assets/` and link it from every lesson. A lesson restating its own styles makes a workspace read as a pile of one-offs rather than as one course.
+
+## MISSION.md
+
+Fixes what the workspace is for. Everything else in the folder answers to it.
+
+- A one-line statement of the subject
+- A `## Starting point` section stating what the learner already knows, so difficulty has a floor to sit above
+- A `## Success looks like` section listing specific observable things the learner will be able to do
+- A `## Out of scope` section naming what this workspace deliberately does not cover
+
+Write each success line as something a learner can be asked to do rather than something they will understand. A line nobody can test is a line nothing can report progress against.
+
+## Learning records
+
+One record per session the learner worked through, holding what happened rather than what was taught.
+
+- The lessons covered, by number
+- What the learner retrieved correctly without help
+- What they got wrong, and what the wrong answer was
+- What to revisit, and roughly when
+
+Record the wrong answer rather than the fact of an error. A wrong answer names the misconception, and the count alone names nothing.
+
+## GLOSSARY.md
+
+Required in every workspace, holding one entry per term the subject defines. The glossary reference the `canon:claude-teach` skill carries fixes what an entry looks like, how the file orders and groups them, and which terms it carries, so this standard states only that the file exists and sits at the workspace root. That reference ships with the plugin rather than installing here, because a promoted glossary keeps its shape wherever it lands and no project folder covers every destination. Say so and stop rather than working the shape from memory when the project has no plugin to read it from.
+
+Name the lesson or reference page a term first appears in as that reference requires. A workspace is the case it was written for, so a glossary here has a first appearance to name.
+
+## RESOURCES.md
+
+Splits what was read from what was found.
+
+- List every source that stands behind the material, each with a link
+- List under a leads heading any source found and not opened, and never cite one
+- Say which claims in the workspace rest on which source
+
+A source found and not read is listed as a lead because a link attached to a page nobody opened is worse than no link. Listing it still pays, since it stops a later session searching for what this one already surfaced.
+
+## Conventions
+
+- Write the markdown half in the format the authoring gates read, so a page promoted later needs no conversion.
+- Keep a reference page free of the learner. A page carrying a second person or a quiz is a lesson wearing the wrong extension, and it cannot be promoted.
+- Revise a file the subject has moved under rather than appending a second version narrating the change.
+
+## Anti-patterns
+
+- **The mission with no test.** Success stated as understanding rather than as a task leaves nothing able to say the mission is finished.
+- **The lesson filed as reference.** A page written to be worked through once sits in `lessons/`, and putting it in `reference/` puts disposable output in the half that gets promoted.
+- **The record that counts errors.** A tally of how many were missed carries none of the misconception, which is the only part a later session can act on.
+- **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.
+- **The renumbered folder.** Closing a gap in the ordinals moves every name a reader or a record already cited.
+
+## Template
+
+```markdown
+---
+title: <Subject>
+description: <one line naming what a learner gets from this workspace>
+date: <YYYY-MM-DD>
+---
+
+# <Subject>
+
+<One line stating the subject.>
+
+## Starting point
+
+<What the learner already knows.>
+
+## Success looks like
+
+- <a specific thing the learner will be able to do>
+- <a specific thing the learner will be able to do>
+
+## Out of scope
+
+- <what this workspace deliberately does not cover>
+```

package/standards/versioning.md

@@ -0,0 +1,71 @@
+---
+title: Versioning reference
+description: Phase label vs semver discipline across tasks, PRs, reviews, issues, commits, and tags
+---
+
+# Versioning reference
+
+Two namespaces, kept separate.
+
+## Scope
+
+Governs the two version namespaces, phase labels and semver tags, and which surfaces each may appear on. It is an attribute standard rather than a document-type one, so it applies wherever either namespace is written, and it carries no template because a label has no document to shape.
+
+Does not govern:
+
+- The format of a phase label, which is project-specific by the rule below
+- Task filenames and board layout: `tasks.md`
+- Commit subject, branch name, and pull request title format: `commit.md`, `branch.md`, and `pr.md`
+- Voice, rhythm, and sentence construction in any text carrying a label: the `write-human` skill
+- Punctuation, formatting, and word choice in any text carrying a label: `markdown.md`
+
+## Phase labels
+
+Internal coordination vocabulary used in the task board and chat.
+
+- Format is project-specific.
+- Used to order work and disambiguate streams during planning.
+- Re-numbers freely as scope shifts. Inserting a half-step between two existing labels (a `v1.5` between `v1` and `v2`) is fine.
+- Does not have to map to any external release.
+
+## Semver tags
+
+External release identity used in git tags and release notes. Independent of phase labels.
+
+- Format is semver: `v<major>.<minor>.<patch>`.
+- Tagged only when a real release is cut.
+- Does not have to map to phase labels. A single semver tag may cover work that carried several internal phase labels.
+
+## Where each appears
+
+| Surface                   | Phase labels | Semver tags                         |
+| ------------------------- | ------------ | ----------------------------------- |
+| `.claude/tasks/`          | yes          | no                                  |
+| Chat with the operator    | yes          | no                                  |
+| PR titles                 | no           | only when the PR cuts a release     |
+| PR bodies                 | no           | only when the PR cuts a release     |
+| Review comments           | no           | only when referencing a release     |
+| Issue titles and bodies   | no           | only when referencing a release     |
+| Commit messages           | no           | only when the commit cuts a release |
+| Git tags                  | no           | yes                                 |
+| README and `CHANGELOG.md` | no           | yes                                 |
+
+## Rules
+
+- PR titles describe the user-observable change in conventional-commit form. Do not prefix or suffix with phase labels.
+- Commit subjects do not embed phase labels.
+- Git tags use semver only. Phase labels never become tags.
+- A PR that cuts a release may reference its semver tag in the title or body. Phase labels still do not appear.
+- PR bodies, review comments, and issue text name the change itself, never the internal stream that scheduled it. Describe the work rather than the label it was planned under.
+
+## Pre-publish check
+
+Text bound for a remote is checked for phase labels against the finished draft, before it is sent. A body, comment, or title reaches a reader who has no task board, so a label that survives to publication cannot be resolved by anyone downstream.
+
+The surface publishing the text is the last gate on it. Where no automated check covers that surface, the author performs the check as an explicit step rather than relying on having read this file while drafting.
+
+## Why
+
+Phase labels keep planning conversations efficient. They make `git log`, PR titles, and the tag list unreadable when they leak in. A future reader cannot reconstruct what an internal label meant without the matching task file, which is gitignored.
+
+Semver tags carry meaning independent of conversation state and survive in git history. Keeping the two namespaces apart preserves both.

package/standards/wireframes.md

@@ -0,0 +1,113 @@
+---
+title: Wireframe reference
+description: Shape and content rules for .claude/wireframes/<surface>.md files
+---
+
+# Wireframe reference
+
+Applies to per-surface entries under `.claude/wireframes/`. Skip for `index.md`, which is regenerated by `canon indexes regen`.
+
+A wireframe file captures the spatial layout and interaction intent of one UI surface. It is not an implementation log. The check for any single line: would it still be true if the surface were rebuilt in a different framework? If not, it belongs in `.claude/context/`.
+
+## Scope
+
+Governs per-surface wireframe entries under `.claude/wireframes/`: layout, variants, on-screen copy, and interaction intent.
+
+Does not govern:
+
+- Tokens, typography, spacing, and the rest of the visual system: `design.md`
+- The mechanism behind a surface: `context.md`
+- Voice, rhythm, and sentence construction in wireframe prose: the `write-human` skill
+- Punctuation, formatting, and word choice in wireframe prose: `markdown.md`
+
+## What a working wireframe looks like
+
+A wireframe works when someone can rebuild the surface from it without opening the components:
+
+- What is on screen, and where does it sit relative to everything else?
+- Which states can a visitor reach, and what does each one look like?
+- What does it say, word for word?
+
+A wireframe that fails these is non-conforming regardless of whether it satisfies every section rule below. The fences are the means. These three questions are the test.
+
+## Frontmatter
+
+- `title` (required): sentence case, names the surface (`Header`, `Section nav`, `Footer`).
+- `description` (required): one line on when and where the surface appears.
+
+Both fields feed `.claude/wireframes/index.md` when regenerated.
+
+## Layout
+
+- Draw each surface as an ASCII block inside a `plaintext` fence. One fence per distinct layout.
+- Label regions with `←` annotations. Never use `#` for annotations.
+- Show a region's role, not its styling. `← status pill` reads better than a class name or hex value.
+- Keep the grid honest. The ASCII proportions should match the intended widths, since conveying proportion is the wireframe's job.
+
+## Variants
+
+- Add a second fence only when the layout itself changes across a breakpoint or state. A wider gutter alone is not a new layout.
+- Name each variant by what triggers it (`## Desktop (≥768px)`, `## Empty state`), not by an arbitrary label.
+- One H2 per variant. Do not stack unrelated surfaces in one file. Keep one surface per file, indexed by `index.md`.
+
+## Copy
+
+- Carry UI copy verbatim in the ASCII block or a short list below it. The wireframe is the source of truth for on-screen text.
+- Mark copy that is dynamic or templated so a reader does not treat a placeholder as final text.
+
+## Behavior
+
+- Describe interaction intent: what the visitor does, what changes on screen, what each state looks like.
+- State the rule, not the mechanism. `The rail tracks the active section as the visitor scrolls` is intent. The scroll handler, throttle, and observer margins are not.
+- Keep it to a short list. A Behavior section longer than the layout is a sign implementation detail has leaked in.
+
+## What moves to .claude/context/
+
+Implementation detail that answers how the surface is built belongs in a `.claude/context/` entry, not the wireframe:
+
+- Algorithms, event-handler code, and lifecycle ordering
+- Framework component names, props, and CSS class or token names
+- Pixel-exact spacing, timing constants, and observer thresholds
+- Workarounds and rejected approaches
+
+Reference the context entry from the wireframe by path when a reader needs the mechanism. The wireframe stays answerable on its own for layout and intent.
+
+## Maintenance
+
+- When a surface's layout or interaction changes, update its wireframe file in the same PR. A wireframe showing a defunct layout is worse than none.
+- The Behavior and Copy prose around an ASCII block is prose and follows `markdown.md` and the `write-human` skill. The fenced block itself is not, so a check scoped to prose is the wrong thing to rely on for what sits inside it.
+
+## Template
+
+One H2 per layout variant, each holding its own fence. A surface with a single layout carries one.
+
+````markdown
+---
+title: <Surface name>
+description: <when and where the surface appears>
+---
+
+# <Surface name>
+
+## <what triggers this variant>
+
+```plaintext
++------------------------------------------+
+| <region>                    ← <its role> |
++------------------------------------------+
+|                                          |
+| <region>                    ← <its role> |
+|                                          |
++------------------------------------------+
+```
+
+## Copy
+
+- <on-screen text, word for word>
+- <text the surface templates>: <marked so a reader does not read it as final>
+
+## Behavior
+
+- <what the visitor does, and what changes on screen>
+- <what each reachable state looks like>
+````

package/tooling/astro/configs/astro.config.mjs

@@ -0,0 +1,31 @@
+import react from '@astrojs/react'
+import tailwindcss from '@tailwindcss/vite'
+import { defineConfig } from 'astro/config'
+import path from 'path'
+
+const portOffset = Number(process.env.WORKTREE_PORT_OFFSET) || 0
+
+// Reserved TLD, so an unset ASTRO_SITE is visible in canonical URLs and never resolves.
+const site = process.env.ASTRO_SITE || 'https://set-astro-site.invalid'
+
+export default defineConfig({
+  integrations: [react()],
+  site,
+  server: {
+    port: 4321 + portOffset,
+  },
+  vite: {
+    plugins: [tailwindcss()],
+    resolve: {
+      alias: {
+        '@': path.resolve('./src'),
+      },
+    },
+    server: {
+      strictPort: true,
+    },
+    preview: {
+      strictPort: true,
+    },
+  },
+})