@erclx/aitk 0.58.0 → 0.60.0

package/standards/groundwork.md

@@ -16,6 +16,7 @@ Governs a groundwork track under `.claude/groundwork/<slug>/`: folder layout, re
 Does not govern:
 
 - A dump of many findings filed by domain, each carrying its own verdict: `intake.md`
+- The feature plan a closed track feeds, and the contract its answer slots keep: `plan.md`
 - The task file a closing track writes, and the origin line pointing back at the folder: `tasks.md`
 - Voice and word choice: `prose.md`
 - Headings, punctuation, and file references: `markdown.md`

package/standards/index.md

@@ -14,6 +14,8 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Groundwork reference](groundwork.md): Folder layout, reserved numbering, frontmatter and dating, required file contents, and conventions for a measurement track
 - [Intake reference](intake.md): Folder layout, reserved index number, frontmatter and dating, the item template, the answer contract, and retrieval
 - [Markdown reference](markdown.md): Headings, paragraph and list structure, code spans, punctuation, emphasis, and file references
+- [Memory reference](memory.md): Filename and type prefix, frontmatter, the body shape per type, links between entries, and the lifecycle from write to retire
+- [Plan reference](plan.md): Filename and slug, required sections, the suggested-and-answer contract, and the lifecycle from the live folder to the archive
 - [Prose reference](prose.md): Voice, language, and frontmatter wording for reference markdown
 - [Publish reference](publish.md): Scan run against finished text leaving through a channel no automated check covers
 - [Readme reference](readme.md): Readme voice, structure, and content conventions

package/standards/intake.md

@@ -16,6 +16,7 @@ Governs an intake folder under `.claude/intake/<slug>/`: folder layout, the rese
 Does not govern:
 
 - One question measured in depth before anyone can plan against it: `groundwork.md`
+- The feature plan a promoted item feeds, and the inverted answer contract it keeps: `plan.md`
 - The task file promoting an item onto the board, and the origin line pointing back at the folder: `tasks.md`
 - Voice and word choice: `prose.md`
 - Headings, punctuation, and file references: `markdown.md`

package/standards/memory.md

@@ -0,0 +1,131 @@
+---
+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 and word choice: `prose.md`
+- Headings, punctuation, 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 in practice is feedback about how to work.
+
+## 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.
+
+## 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,145 @@
+---
+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 and word choice: `prose.md`
+- Headings, punctuation, 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.
+- 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.
+
+### 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:
+```
+
+- 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.
+- Answer in place when a question is settled in conversation, so the file and the decision do not disagree.
+
+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.
+- 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.
+- 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 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:**
+
+- <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/tasks.md

@@ -15,6 +15,7 @@ Governs the task board under `.claude/tasks/`: folder layout, filenames, frontma
 
 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`
 - Sequencing across versions and why the order is what it is: `roadmap.md`
 - Architectural reasoning that outlives a task: `architecture.md`

package/tooling/claude/seeds/CLAUDE.md

@@ -73,11 +73,8 @@
 
 - Write all memory files to `.claude/memory/`, not `~/.claude/projects/`
 - A fact about a domain goes to that domain's `.claude/context/` entry, not to memory. `claude-memory-capture` routes it there and `claude-docs` folds it in. Memory keeps only what no context entry owns.
-- Save a feedback memory only when the same mistake happens twice in the session, or when the user explicitly corrects you. First-occurrence slips are noise.
-- Keep feedback memories to 3 lines: the rule, a one-line Why, and a one-line How to apply. Capture the pattern, not the recovery narrative.
-- Before creating a new memory file, check for an existing one on the same topic. Update rather than duplicate.
-- Give every entry `title`, `description`, and a sentence-case `category`. Never hand-edit `.claude/memory/index.md`. A hook regenerates it from sibling frontmatter.
-- Never delete a memory entry. `claude-memory-review` moves a retired one to `.claude/.tmp/memory-archive/`.
+- Never delete a memory entry. Retire one by moving it to `.claude/.tmp/memory-archive/`. A bulk retire runs through the shell, where no file edit fires a path-scoped rule, and the folder is gitignored with nothing to recover from.
+- Follow `.claude/standards/memory.md` for the filename and type prefix, the frontmatter, the body shape each type carries, and the lifecycle. Run `aitk records validate memory` to check the pen against it.
 
 ## Scratch