@erclx/canon 4.0.0

package/standards/markdown.md

@@ -0,0 +1,137 @@
+---
+title: Markdown reference
+description: Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, file references, banned words, and frontmatter wording
+---
+
+# Markdown reference
+
+Applies to markdown reference docs, READMEs, and inline documentation in repos. Every rule here is a fact a scan can settle rather than a judgment, so no surface yields any of them. A surface stating its own voice claims that yield from the voice guidance and formats and spells by this file regardless.
+
+## Scope
+
+Governs what a check can decide about a markdown file: headings, paragraph and list structure, code spans and fences, the form a date takes, punctuation, emphasis, file references, the closed-set word and spelling bans, what prose may claim about its sources, and the wording of a catalog title and description. It is an attribute standard rather than a document-type one, so it applies over documents whose shape another standard sets, and it carries no template because these rules are written across every document and have no shape of their own.
+
+The two frontmatter fields it reaches are `title` and `description`. They are named here rather than in the statement above, since a backticked token in a scope statement's first sentence is published as the standard's jurisdiction.
+
+The split with the voice guidance is what reads the rule rather than what the rule covers. Every ban below ships as data `canon markdown audit` and the installed audit hook both read, so a violation is measured on every run. Cadence, rhythm, and information density are judgments a reader settles, and those travel in the `canon:write-human` skill, which a markdown edit routes to.
+
+Does not govern:
+
+- Voice, rhythm, sentence construction, and information density, which the `write-human` skill carries
+- What sections a document has, or what belongs in each: the standard for that document type
+- Which frontmatter fields a document carries, which is that standard's own subject. This file governs the wording of a `title` and a `description` and nothing else about them.
+- The text inside a fenced block, which follows the conventions of its own language rather than these
+- Phase-label and semver discipline: `versioning.md`
+- The scan that applies these bans to finished text on its way out: `publish.md`
+- Whether a pull request or issue number is backticked, which turns on where the text is published rather than on the text: `publish.md`
+
+## Headings
+
+- H1 for document title, H2 for main sections, H3 for subsections
+- Use sentence case for all headings (H1, H2, H3)
+- Proper nouns and product names retain their casing in headings
+- Past roughly 40 rendered lines with no heading of any level breaking them, add a subheading at the seam. Measure the longest such run rather than everything under one `##`, and exclude fenced code blocks. The number is a checkpoint, not a cap.
+- Count rendered lines rather than source lines, wrapping each source line at 80 columns and summing the heights. Source lines undercount a file authored one line per bullet, where a block of fifteen paragraph-bullets occupies fifteen lines and renders past sixty. A checkpoint another standard states counts the same unit, so a file measured one way never sits beside a run measured another.
+- Exempt a block whose lines are all list items at one level averaging under roughly 130 characters. A flat list of short peers is already navigable, and a subheading dropped into it splits a set that belongs together. Bullet count says nothing on its own, since a catalog of one-liners and a stack of paragraphs reach the same count and read nothing alike, so weight is what decides.
+- Mixing prose with that list, or nesting levels inside it, ends the exemption at any weight.
+- Exempt a block whose lines are all table rows, at any length. The peer list above is exempt because it is already navigable, and a table because the remedy does not exist: a subheading dropped inside one splits the table rather than the run, so no edit short of rewriting it as a list clears the checkpoint.
+- Prose either side of the table ends that exemption, since the block has a seam and a heading breaks it there.
+- Break a run on a bold section marker holding its line alone, the way a heading breaks one. A document whose template separates sections with `**Risks:**` rather than `## Risks` has written the seam a reader lands on, and reading only the heading reported every such file at its full length whatever it carried.
+- Require the marker to start at column zero and to be the whole line. `**Risks:**` breaks a run, a bold phrase opening a sentence stays emphasis, and an indented one stays a label inside its list item.
+- Break a colon-less marker on either of two signals, since no one test separates every marker from a sentence set in bold. A label that is one whole code span breaks at any width, which is how a bold line holding only a backticked path reads as the file heading it is. Anything else breaks at 20 characters or fewer, which reaches `**Testing**` and leaves a bold sentence as prose.
+
+## Paragraphs and lists
+
+- Use prose by default. Reserve bullets for discrete, unrelated items.
+- Keep paragraphs to four sentences or fewer. Split longer blocks at the next logical boundary.
+- Past roughly 700 characters in one paragraph, folding in the lines that wrap it, split at the next logical boundary as well. A paragraph written as two long sentences satisfies the sentence cap above and still asks the reader to hold too much at once. This number sits well above the bullet checkpoint because a paragraph is read straight through and a bullet is scanned.
+- Keep bullets tight. Past roughly 400 characters in one top-level bullet, counting the lines that continue it and excluding any bullet nested under it, the overflow belongs in prose. The number is a checkpoint rather than a cap, and a bullet reading well past it means the number is wrong rather than the rule.
+- Collapse a stack of bullets narrating one subsystem into a single `###` subsection carrying one narrative. Splitting a heavy bullet into three light ones satisfies the checkpoint above and leaves the reader no better off, and subdividing a block does not lighten the bullets inside it, so the two rules answer different defects.
+- Use dashes (`-`) not asterisks (`*`) for bulleted lists
+- Do not end single-sentence or fragment bullets with a period. Use periods when a bullet has two or more sentences.
+- For key path lists, use colon format: `- \`src/\`: description`. Never use an em dash.
+- Do not introduce a list with a "Here are the X:" or "The following X:" lead-in
+
+## Code and identifiers
+
+- Wrap commands, API names, file paths, and code identifiers in backticks
+- Use a language identifier on all fenced code blocks (`markdown`, `typescript`, `plaintext`). Never use a bare ` ``` `
+- In ASCII tree diagrams, use `←` for inline annotations. Never use `#`.
+
+## Dates
+
+- Write a date as `YYYY-MM-DD` wherever one appears, in frontmatter, in prose, and in a filename. Never a month name, a slash-separated form, or a two-digit year.
+
+## Punctuation
+
+- Do not use em dashes (`—`) or semicolons (`;`). Rewrite or restructure the sentence to avoid them.
+- Do not use parenthetical asides in prose (`the config (which is optional) controls...`). Split into its own sentence or drop it. Parentheses in rule definitions for grouping examples are fine.
+
+## Language
+
+- Use American English spelling. Prefer `-ize` over `-ise`, `-or` over `-our`, `-er` over `-re` (`organize`, `analyze`, `summarize`, `recognize`, `behavior`, `color`, `center`)
+- Do not use marketing buzzwords (`seamless`, `robust`, `powerful`, `revolutionary`, `enhanced`, `allows`, `leverage`)
+- Do not use vague qualifiers (`simply`, `just`, `easily`, `quickly`, `very`, `really`)
+- Open a sentence with its subject and action, not filler (`Note that`, `Basically`), a hollow connective (`That being said`, `It's worth noting`), or a gerund windup (`Leveraging the API...`). Substantive transitions that carry a real relationship are fine.
+- Do not use the negative parallelism pattern (`It's not X, it's Y`, `not because X, but because Y`)
+- Do not pad verb phrases or delay the action. Write the shortest form (`in order to` → `to`, `ensure that X is set` → `set X`, `By doing X, you can Y` → state Y directly).
+- Do not address the reader as a participant (`Let's`, `Here's`, `Here are`). State the content directly.
+- Commit to a position. Do not hedge in clusters (`It might be worth considering`) or use false balance (`While X is true, Y is also important`). Recommend, or state the tradeoff.
+- Do not inflate significance. State what a thing does rather than calling it `a major milestone` or `a turning point for the field`.
+- Do not name a person, company, or product to borrow its authority. Name a source only where the claim turns on who made it.
+- Do not attribute a claim to an unnamed authority (`experts say`, `studies show`, `it is widely believed`). Name the source or cut the claim.
+- Do not introduce a fact, name, date, or citation the source does not carry when rewriting existing text. A rewrite changes wording and never claims.
+
+The word bans and the character bans sit under one file because one command reads both. `canon markdown audit` ships them as package data, so a project that installed no standards is measured the same as one that did, and this section states them for a reader rather than for the parser.
+
+## Frontmatter descriptions
+
+When frontmatter carries a short `title` or `description` used for catalog display:
+
+- `title`: sentence case, identifies the file uniquely against its siblings in the same catalog. Proper nouns retain their casing. No trailing period.
+- `description`: sentence case, names the specific topics covered so a reader can decide whether to open the file. Lead with concrete subjects, strip filler like "guide to", "overview of", or "documentation about". No trailing period, no leading article (`the`, `a`).
+- Do not mechanically reuse the H1 as the description.
+
+## Emphasis and dividers
+
+- Do not over-format with excessive bold, italic, or header usage
+- Do not use horizontal rules or dividers (`---`) in body content. The `---` delimiters of a YAML frontmatter block at the top of the file are allowed.
+
+## Links and file references
+
+- Use descriptive anchor text for links. Avoid `click here` or `read more`.
+- Wrap file references in backticks by default. Use a labeled markdown link (`[label](path)`) only on rendered-for-human surfaces (`README.md`, `docs/`) and in an index file, whose rows exist to be followed. Never repeat the path verbatim as the label.
+
+## Examples
+
+Each pair shows a banned pattern and its fix.
+
+```markdown
+Bad: See [.claude/context/retrieval.md](.claude/context/retrieval.md) for the retrieval flow.
+Good: See `.claude/context/retrieval.md` for the retrieval flow.
+```
+
+```markdown
+Bad: Read [docs/development.md](docs/development.md) before contributing.
+Good: Read the [development guide](docs/development.md) before contributing.
+```
+
+```markdown
+Bad: In order to configure the server, you'll need to ensure that the port is set.
+Good: Set `port` in the server config.
+```
+
+```markdown
+Bad: It's not just a cache. It's a system for intelligent memory management.
+Good: The cache is an LRU store. It evicts the least-recently-used entry when full.
+```
+
+```markdown
+Bad: Leveraging the retry mechanism, developers can build more resilient integrations.
+Good: Use the `retry` option for failed webhooks. Set `maxRetries` to 3.
+```
+
+```markdown
+Bad: It might be worth considering whether to enable caching.
+Good: Enable caching for read-heavy endpoints. Skip it for writes.
+```

package/standards/memory.md

@@ -0,0 +1,144 @@
+---
+title: Memory reference
+description: Filename and type prefix, frontmatter, the body shape per type, links between entries, and the lifecycle from write to retire
+---
+
+# Memory reference
+
+Applies to a memory entry at `.claude/memory/<type>-<slug>.md`. One file holds one rule or one fact, written at the end of the session that produced it and read by a session that holds none of it. Which surface owns a given fact is settled before an entry is written at all, and that routing is project policy rather than a shape rule.
+
+The folder is gitignored and unbacked. Nothing recovers a deleted entry, which is why the retire step below is a move rather than a cleanup.
+
+## Scope
+
+Governs a memory entry under `.claude/memory/<type>-<slug>.md`: the filename and its type prefix, the frontmatter, the body shape each type carries, links between entries, and the lifecycle from the first write to retirement.
+
+Does not govern:
+
+- The per-domain entry a domain fact is routed to instead of memory: `context.md`
+- The feature plan a session executes, and its answer contract: `plan.md`
+- The task file tracking what is being built: `tasks.md`
+- Voice, rhythm, and sentence construction: the `write-human` skill
+- Headings, punctuation, word choice, and file references: `markdown.md`
+- Which facts a project captures at all, and where the folder sits, which are project policy
+
+## What a working entry looks like
+
+An entry works when a session holding none of the conversation that produced it can act on the rule from the file alone:
+
+- What is the rule or the fact, stated in one line?
+- What happened in a session to earn it, so a later reader can tell whether it still holds?
+- When does it fire next, and what does the reader do at that moment?
+- Does another surface already own this, which would make the entry a duplicate of something sessions trust more?
+
+An entry failing these is non-conforming even when it satisfies every shape rule below.
+
+## Types
+
+Four types, and the type decides both the filename prefix and the body shape.
+
+| Type        | Holds                                                                | Fires on                                    |
+| ----------- | -------------------------------------------------------------------- | ------------------------------------------- |
+| `feedback`  | a correction or a confirmed approach governing how the agent works   | explicit correction, or the same slip twice |
+| `project`   | a decision, constraint, or measured fact not derivable from the code | first disclosure                            |
+| `user`      | role, expertise, responsibilities, or working preferences            | first disclosure                            |
+| `reference` | a pointer to an external system, repository, or channel              | first disclosure                            |
+
+Hold a feedback entry to the higher bar. A first-occurrence slip is noise, and a folder that records every one of them buries the rules that were paid for.
+
+Write no entry for a fact another surface already owns. A fact about a domain belongs in that domain's entry, where sessions working the domain already read it, and the same fact in memory sits in a folder nothing opens. Memory keeps the residue, which is whatever the ownership test leaves rather than any one type.
+
+## Filename
+
+- Name the file `<type>-<slug>.md`, with `<type>` one of the four above and `<slug>` kebab-case naming the rule rather than the incident.
+- Write one rule per file. Two rules under one slug cannot be retired or promoted separately, and one of them always outlives the other.
+- Keep the prefix and the `category` field the same fact in two spellings. A prefix outside the four types reads as a fifth type to anything grouping the folder, and it silently belongs to none.
+
+## Frontmatter
+
+Every entry carries all three fields.
+
+```yaml
+---
+title: A scope glob wide enough for a correct run can be wide enough for every wrong one
+description: Omit a declaration key whose only passing value admits the whole tree
+category: Project
+---
+```
+
+- `title` (required): the rule stated as a line a reader can act on, in sentence case.
+- `description` (required): one line naming what the entry settles, so a reader scanning the catalog decides whether to open it.
+- `category` (required): the type in sentence case, which is what groups the catalog.
+
+Never write the filename stem as the `title`. The stem is a slug, and an entry titled with it reads as an unwritten file in every catalog that renders the field.
+
+Quote a `description` opening with a backtick or a colon. An unquoted one fails to parse and takes the whole folder's catalog with it.
+
+## Body
+
+A `feedback` or `project` body carries three parts in this order. Blank lines between them are optional and the three parts are not.
+
+- The rule or the fact, stated in one or two sentences as something to do rather than something that happened.
+- A `**Why:**` line naming the session signal that earned it. This is what a later reader tests the rule against when the tree has moved.
+- A `**How to apply:**` line naming the next moment the rule fires and what to do then.
+
+A `user` or `reference` body is a single sentence and carries neither marker. There is no rule to apply and no signal to date, so the two lines would be filler.
+
+Capture the pattern rather than the recovery. What was tried, what failed, and who noticed belong to the session that is ending, and a body carrying them is a story where the next reader needs an instruction.
+
+## Links
+
+Link a related entry as `[[name]]`, where `name` is the target's filename stem without the extension. Link freely: the folder is flat and the links are the only structure it has.
+
+- Place links inside the body part they support, not in a list of their own at the end.
+- A link naming an entry nobody has written yet is legal, and it marks a rule worth writing rather than a defect.
+- A bracketed token inside a code span is not a link. Backticked syntax from another language routinely reads as one.
+
+## Lifecycle
+
+- Check the folder for an entry on the same topic before writing a new one, and update that entry in place when one exists. Two entries on one rule disagree the moment either is edited.
+- Rewrite an entry the tree has moved under rather than appending a second passage narrating the change. A reader cannot tell which of two claims is current.
+- Never delete an entry. Retire one by moving it to an archive under its own name, because the folder is unbacked and a bulk judgment has no undo behind it.
+- Treat the folder as a holding pen rather than a destination. An entry whose rule belongs on a durable surface is promoted there and retired here, and the rest is what the pen is for.
+
+The catalog is generated from sibling frontmatter rather than authored. Never hand-edit it, since the next regeneration discards whatever was added by hand.
+
+## Collecting a review receipt
+
+A review of the pen writes a receipt recording what it proposed per entry and what was decided. The receipt is collected once every item on it has resolved, and it is held while any item is still pending, since a pending item is decision state the next round reads back.
+
+Fold the declines before the receipt goes. A promoted entry survives in its target and in git and a retired one survives in the archive, so the one thing a receipt uniquely holds is the record that a rule was considered and turned down.
+
+- Fold into the entry the item was about, and only into that entry. A decline whose proposed target was another surface still lands here.
+- Fold a `feedback` or `project` entry alone. The decline belongs in the `**Why:**` line, which is what a later reader tests the rule against.
+- Fold nothing into a `user` or `reference` entry. Its body is one sentence carrying neither marker, and such an entry is declined for having no in-repo target, which its type already states. Writing that on the entry restates the type and breaks the body shape.
+- Record the decline by rewriting the entry, never by appending to it, per the lifecycle rule above.
+
+Which surface runs the collection is project policy. More than one may, so a collector finding no receipt has been beaten to it rather than misconfigured.
+
+## Anti-patterns
+
+- **The domain fact filed as memory.** It reads as a capture and lands in the one folder no session opens while working that domain.
+- **The incident narrative.** A body recounting what went wrong states no rule, so the next reader has to infer one and infers a different one.
+- **The entry titled with its own slug.** Every catalog rendering the field shows a filename where the rule should be.
+- **The duplicate written beside the original.** Two entries on one topic drift, and nothing says which is current.
+- **The first-occurrence capture.** A folder recording every slip buries the rules that repeated.
+- **The entry deleted on retire.** The folder has no history, so the judgment that discarded it cannot be reviewed or reversed.
+
+## Template
+
+```markdown
+---
+title: <the rule, stated as a line a reader can act on>
+description: <one line naming what the entry settles>
+category: <Feedback|Project|User|Reference>
+---
+
+<the rule or fact, in one or two sentences, as something to do>
+
+**Why:** <the session signal that earned it, with the measurement where one exists>
+
+**How to apply:** <the next moment it fires, and what to do then> See [[related-entry]].
+```
+
+A `user` or `reference` entry carries the same frontmatter and a single sentence in place of the three parts.

package/standards/plan.md

@@ -0,0 +1,172 @@
+---
+title: Plan reference
+description: Filename and slug, required sections, the suggested-and-answer contract, and the lifecycle from the live folder to the archive
+---
+
+# Plan reference
+
+Applies to a feature plan at `.claude/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 unbacked. Nothing recovers a deleted plan, which is why the archive step below is a move rather than a cleanup.
+
+## Scope
+
+Governs a feature plan under `.claude/plans/feature-<slug>.md`: the filename, the required sections, what each holds, the suggested-and-answer contract, and the lifecycle from the live folder to the archive.
+
+Does not govern:
+
+- 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`
+- The task file a plan is linked from, and the origin line pointing back at it: `tasks.md`
+- The transform from a branch name to a slug: `slug.md`
+- Voice, rhythm, and sentence construction: the `write-human` skill
+- Headings, punctuation, word choice, and file references: `markdown.md`
+- When a plan is written at all, and whether a short one goes to a file or to the conversation, which belong to the surface driving it
+
+## What a working plan looks like
+
+A plan works when a session holding none of the conversation that produced it can execute from the file alone:
+
+- What is being built, and which files does it change?
+- Which decisions are already settled, and which are still open?
+- For each open decision, what happens when nobody answers it?
+- What is likely to go wrong, and where does the work collide with something already in flight?
+
+A plan failing these is non-conforming even when it satisfies every shape rule below.
+
+## Filename and slug
+
+- 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.
+- 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.
+
+A plan carries no frontmatter. Its filename is the whole of its identity, so a folder of plans is read by name rather than by a generated catalog.
+
+## Sections
+
+The document opens with `# Feature: <short title>` and one paragraph stating what is being built and why now. The sections below follow in this order.
+
+| Section               | Holds                                                                     | Required      |
+| --------------------- | ------------------------------------------------------------------------- | ------------- |
+| `## Summary`          | three to five one-line bullets: the goal, the deliverables, the trade-off | Always        |
+| `**Constraints:**`    | durable rules the work must respect                                       | When supplied |
+| `**Files to touch:**` | each file with a one-line reason                                          | Always        |
+| `**Risks:**`          | conflicts, coupling, and the tricky spots                                 | Always        |
+| `**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 four 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.
+- 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.
+- 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.
+
+- 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.
+- 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.
+
+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.
+
+- 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.
+
+### Risks
+
+- Name the collision rather than the category. A risk a reader cannot act on is padding.
+- Where the work establishes a resource with more than one consumer, list the consumers and mark each one read or write. A policy stated over that resource has to hold for the writers and not only for the consumer that prompted it.
+
+## The suggested-and-answer contract
+
+Every question carries a `- Suggested:` line and an empty `- Answer:` slot below it.
+
+```markdown
+1. <question>
+   - Suggested: <pick>, <reason or tradeoff>
+   - Answer:
+```
+
+An execution that deviates rewrites the suggestion into the form below, leaving the slot as it found it.
+
+```markdown
+1. <question>
+   - Suggested: overridden at execution to <pick>, <the measurement that moved it>
+   - Answer:
+```
+
+- A blank `- Answer:` means accept the suggestion at execution time. That default is what makes the plan decision-ready in one pass, with no separate round to collect answers.
+- Never ship a question without a suggestion. A bare question defers the judgment the plan exists to supply, and it arrives at the executing session as a stop.
+- State the pick in one line with its reason or its main tradeoff. List an alternative only where it changes the pick.
+- 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.
+- 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.
+
+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.
+
+## Lifecycle
+
+- Write the plan before implementation starts, and treat it as the scope of the run that executes it.
+- 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 `.claude/plans/archive/` when the work it describes ships. Never delete it, because the plan is where the rejected alternative is written down and nothing else records it. The archive nests inside `.claude/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.
+- 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
+# Feature: <short title>
+
+<One paragraph on what is being built and why now.>
+
+## Summary
+
+- <one-line bullet covering the goal>
+- <one-line bullet covering the main deliverables>
+- <one-line bullet covering the key decision or trade-off>
+
+**Constraints:**
+
+- Measured against `<commit>` on <YYYY-MM-DD>
+- <the work in flight, its file set, and which of the two acts the constraint forbids>
+- <durable rule the work must respect>
+
+**Files to touch:**
+
+- `<path/to/file>`: <reason>
+
+**Risks:**
+
+- <conflict, coupling, or tricky spot>
+
+**Questions:**
+
+1. <question>
+   - Suggested: <pick>, <reason or tradeoff>
+   - Answer:
+```

package/standards/pr.md

@@ -0,0 +1,139 @@
+---
+title: Pull request reference
+description: Pull request title and body conventions
+---
+
+# Pull request reference
+
+## Scope
+
+Governs a pull request title and body: their format and the sections the body carries.
+
+Does not govern:
+
+- Commit subject format, which shares the title form: `commit.md`
+- Branch naming: `branch.md`
+- Whether a phase label or a semver tag may appear in a title or body: `versioning.md`
+- Voice, rhythm, and sentence construction in pull request prose: the `write-human` skill
+- Punctuation, formatting, and banned words in pull request prose: `markdown.md`
+
+## Title
+
+- Format: `<type>(<scope>): <subject>`
+- Casing: lowercase for `<type>`, `<scope>`, and first word of `<subject>`
+- Length: 72 characters maximum
+
+## Content
+
+- Use imperative mood for all content (`add`, `fix`, `refactor`)
+- Do not start with "This PR," "This commit," "Included are," or "I have"
+- Do not use buzzwords (`seamless`, `robust`, `game-changer`, `enhanced`)
+- Do not describe historical behavior or unchanged code. Describe new behavior only.
+- Do not include future promises or speculative documentation
+- Do not explain obvious changes (formatting, renaming variables)
+- Do not duplicate commit messages verbatim
+
+## Sections
+
+- `## Summary`: 1-2 sentences following `<Action Verb> <Direct Object> to <Result>`, expand for clarity if needed
+- `## Key Changes`: name actual files, functions, or modules (e.g., `AuthService.verify()` not "auth handler"). Always use bullet points, never prose.
+- `## Technical Context` (optional): 1-2 lines of architectural reasoning explaining why, not what
+- Omit Technical Context for docs, config, or trivial changes
+- Use bullet points for multiple reasons, one sentence for a single reason
+- `## Testing` (optional): specify exact commands or test cases run
+- Omit Testing for docs, config, or trivial sync changes
+- Use checkboxes, never prose. See Testing discipline for which box gets ticked.
+- `## For the reviewer` (optional): what the reviewing session should confirm, one bullet per request
+- Visuals: include only when they clarify architecture, UI, or complex logic flows
+
+## Testing discipline
+
+- Run the check before writing its line. A `- [ ]` reports a check that has not run rather than one that is planned.
+- Tick the box and state the observed result. `- [x] npm test passes, 42 tests` beats `- [ ] run npm test`.
+- Quote the count or output the run reported, never a figure carried from elsewhere.
+- A ticked box describes the tree as it stands, not as it stood when it was written. A later commit that removes or replaces what it names makes the box false, and the branch that made that commit corrects it in the same pass, the same as any other stale claim in the body.
+- Leave a box unchecked only when a human is required, and name which human and why on the same line.
+- Human-only covers visual or aesthetic judgment, anything needing credentials or a live third-party service, anything needing a second machine or a fresh OS, and judgment about whether a boundary or an abstraction reads correctly. The agent runs everything else.
+- What makes a human required is a capability the agent lacks, never the cost of the run. Authorizing a spend is the operator's and performing the run is not, so an arm the repository ships a harness for gets driven once the operator has cleared the spend, and the box records what it returned.
+- A tool refusal that actually fired is a capability gap, and the line says which refusal rather than naming the cost behind it. A refusal predicted and never met is not one.
+- A live agent session is not a human. A box reading `needs a live session driving the skill` names the thing writing the description, so that run is owed rather than blocked.
+- Put a request for the reviewer under `## For the reviewer`. It is a request rather than unfinished testing, so it never appears as an unchecked Testing box.
+
+## Formatting
+
+- End every bullet point with a period
+
+## Examples
+
+### Template
+
+```markdown
+## Summary
+
+<Action Verb> <Direct Object> to <Result>.
+
+## Key Changes
+
+- <Verb> <specific component/file/function> (<reason if non-obvious>)
+- <Verb> <specific component/file/function>
+
+## Technical Context
+
+- <Architectural reasoning explaining why, not what>
+
+## Testing
+
+- [x] <Command run> <observed result>
+- [x] <Edge case verified> <what was observed>
+- [ ] <Human-only check> (<which human, why>)
+
+## For the reviewer
+
+- <What the reviewing session should confirm>
+```
+
+### Correct
+
+```markdown
+## Summary
+
+Update auth middleware to enforce jwt expiration checks. # imperative + direct object + result
+
+## Key Changes
+
+- Add `verifyExpiration()` to `src/auth/validators.ts`. # specific function + file path
+- Refactor `AuthService.authenticate()` to handle 401 codes. # named component + clear change
+
+## Technical Context
+
+- Migration to stateless session management for horizontal scalability. # why, not what
+
+## Testing
+
+- [x] `npm run test:auth` passes, 42 tests. # command run + observed result
+- [x] Expired token rejected with a 401 against a local server. # edge case + what happened
+- [ ] Staging smoke test (release owner, needs staging credentials). # unchecked + which human + why
+
+## For the reviewer
+
+- Confirm the 401 and 403 split reads correctly for the public API. # a request, not a test result
+```
+
+### Incorrect
+
+```markdown
+## Summary
+
+This PR updates the authentication system to be more robust. # "This PR" opener + buzzword
+
+## Key Changes
+
+- Updated auth middleware files # vague, no specific component, no period
+- The old system used to check tokens differently # describes historical behavior
+
+## Testing
+
+- Tested manually # no specific command or case
+- [ ] `npm run test:auth` # unchecked box for a check the agent can run
+- [ ] The reviewing session confirms the error split reads correctly # a reviewer request, belongs under `## For the reviewer`
+```