intent-planner 0.13.1

package/templates/en/codex/skills/intent-writeback/rules/writeback-protocol.md

@@ -0,0 +1,139 @@
+# Writeback Protocol (canonical rules for intent-writeback)
+
+The source of truth for `/intent-writeback`'s decisions and procedure. SKILL.md holds only the skeleton of the steps; decisions follow this file. "Canonical deliverables" means intent-tree.md / intent-compass.md / the files under `.intent/packets/` (the packet files and plan.md).
+
+## 1. Target identification (4-tier priority + fallback)
+
+Identify exactly one target packet by first-match from the top. When the target is identified via a fallback (tier 3 or later), announce that fact (which tier identified it) in the user-facing output.
+
+1. **Packet name from the argument**: if a packet is specified by argument, use it as the target.
+2. **The latest row of export-log.md (canonical)**: use the packet name of the latest data row (= the last data row of the `| packet | exported_at | commit |` table) in `.intent/export-log.md`. In the steady state where export-log exists, the target is finalized here.
+3. **"## Source Packet" heading in the drafts (fallback)**: if export-log.md is absent or its latest row cannot be parsed, read the packet name from the "## Source Packet" heading in `.intent/cc-sdd/<packet-slug>/requirements.md`. Adopt that heading only when **exactly one** packet directory exists; if multiple exist, list the heading of each directory as candidates and go straight to 4. This tier is a relief for the transitional period where export-log is not yet established (e.g., right after the first export); in the steady state the target is finalized at 2.
+4. **Text-matching fallback (user confirmation required)**: raise candidates by text-matching the draft bodies against the packet names (frontmatter `name`) in index.md / the packet files under `active/`, then ask the user in natural language and wait for the answer. Never finalize the target without confirmation.
+
+If the target still cannot be identified, present the situation (that it was not found and where you looked), ask the user to specify the write-back target packet, and stop.
+
+**Directory identification rule (packet name → directory)**: the source of truth for identifying a directory from a packet name is "the `## Source Packet` heading in requirements.md inside the directory matches the packet name". Slug computation is a fast path for searching; even if the slug matches, do not identify the directory as that packet's when the heading does not match.
+
+**Archive exception for target resolution**: if the resolved target packet's file is not under `active/` (a preceding supersede, completion already processed, etc.), refer to `archive/` **explicitly** and identify the file by matching the frontmatter `name` (the only explicit exception to the principle of "normally never read `archive/`"). Once identified, report to the user the fact that the packet is done / superseded. For a write-back to an archived packet that is not done, do not reflect into the target packet file; redirect the learnings to intent-tree.md / intent-compass.md / the successor packet (the packet file `superseded_by` points to).
+
+## 2. Learning extraction perspectives (5 kinds, tags 1:1)
+
+Cross-check the target packet's definition (the target packet file), the cc-sdd drafts (including the Intent-derived constraints), and intent-compass.md against the implementation reality (the codebase, tests, and `.kiro/specs/`; all read-only), and extract learnings from the following 5 perspectives. Tags map 1:1 to the perspectives. When reading the implementation reality, also include in the grep cross-check scope the code modules (file names, module names) named by Decision Rules (intent-compass.md), and you may extract a divergence between a Rule's main text and the implementation as an `[invariant-violation]`.
+
+| Tag | Perspective |
+|------|------|
+| `[decision]` | A new decision (a judgment made during implementation that is not written in the packet definition) |
+| `[invariant-violation]` | A discovered invariant violation (a conflict between existing Invariants and the implementation reality) |
+| `[implicit-behavior]` | Implicit behavior not written in the intent (reverse-extracted from the implementation) |
+| `[deferred-resolved]` | A resolved Deferred |
+| `[question]` | A new unresolved Question |
+
+During learning extraction, cross-check against the **Revisit when** field of the Decision Rules in intent-compass.md, and on each learning line that matches a Revisit when condition, append a reference to the corresponding Decision (e.g. `[decision] <a new decision> (Revisit matched: <summary of the corresponding Decision's Context>)`). The note is free text within the learning line; the canonical deltas.md template (§9) is not changed.
+
+## 3. Two-stage protocol
+
+**The scope of the constraint in this §3 is limited to the writeback phase (the stage of extracting learnings back from reality after implementation and returning them to the canonical deliverables).** The drafting skills run **before** implementation — `/intent-compass` (which directly Writes the compass's North Star / Anti-direction / Invariants / Decision Rules) and `/intent-packets` (which directly drafts packet files) — are out of scope of this constraint (their writing canonical directly is the normal, intended behavior). What this constraint forbids is "writing post-implementation learnings into the canonical deliverables directly, bypassing a delta", not pre-implementation drafting.
+
+In the writeback phase, never editing the canonical deliverables directly is the backbone of this skill. Always go through the following two stages.
+
+Note: once you enter the stage of "implementation is complete and you are returning learnings from that reality to the canonical deliverables", that is the entry to the writeback phase. Do not settle for writing Evidence directly into the packet file; go through this protocol (via a delta).
+
+### Stage 1: delta recording (canonical untouched)
+
+- Record the extracted learnings into a **per-packet split file** `.intent/deltas/<packet-slug>.md` as a new entry (Status: pending) (CONTRACT "Split and archive convention for append-only records"; `<packet-slug>` is derived from the target packet name via the existing slug rule — no new numbering). Create the `deltas/` directory if absent. Do not touch the canonical deliverables at this stage at all. Move terminal (promoted/closed) past entries into `.intent/deltas/archive/<year>/` to keep the active surface thin (move all before folding the old file; migration is handled by this slice's migration step).
+- Even if the user approves nothing, the entry remains as pending (automatic rewriting without approval is forbidden).
+
+### Stage 2: approval → per-item promotion
+
+Vary the approval granularity by the kind of learning. Do not ask about everything one item at a time with equal weight (in practice most learnings are records of "the implementation already behaves this way" with no room for yes/no, so asking about every item uniformly turns approval into a ritual).
+
+- **Gated items (explicit approval mandatory)**: the following two kinds affect the canonical criteria and invariants, so always ask the user about each item in natural language and wait for the answer.
+  - `[invariant-violation]` (a discovered invariant violation; the user decides the response policy such as "fix the code / keep it as a record only").
+  - **`[decision]` that changes Decision Rules (the compass ADR)** (those falling under the ADR promotion in §4: replacing or adding an existing Decision, including ones that match a Revisit when).
+- **Default bulk promotion (L3-append kind)**: learnings other than the above (a `[decision]` / `[implicit-behavior]` / `[deferred-resolved]` that only appends to intent-tree.md L3, and `[question]` transcription into Open Questions) are presented with their reflection targets as a list, and **after asking the user to name any item they want to hold back, are promoted in bulk if none is named**. Do not ask for a per-item yes/no.
+- On either path, "automatic rewriting without approval is forbidden" (the backbone of §3's opening) is preserved because every item is already recorded as a delta in Stage 1 and the user is given one chance to hold items back. Items the user holds back are treated as declined and given a §5 two-value tag.
+- Reflect the approved or bulk-promoted items into the canonical deliverables, and record `Status: promoted (<promotion date>)` and the reflection targets in the delta entry.
+- Finalizing the state: **approving one or more items and reflecting them into the canonical deliverables → `promoted`**. **Declining every item as "rejected" → `closed`**. Both are terminal states. If items remain undecided including on-hold ones, keep pending.
+
+## 4. ADR promotion rules (promotions that change Decision Rules)
+
+A promotion that changes the criteria (Decision Rules) fully complies with the existing ADR form of intent-compass.md.
+
+- **Add a new entry**: **Context** (the question and situation) / **Decision** (the option taken) / **Why** (the criteria) / **Alternatives considered** (a summary of the alternatives examined and why they were rejected) / **Consequences** (connection to Invariants and Anti-direction) / **Revisit when** (the conditions for revisiting; if they cannot be determined, explicitly record "undetermined"). **The Why field is mandatory** (never omit it).
+- Put a **superseded note** on the old entry being replaced (append to the old entry that it is superseded, with a reference to its replacement).
+- Move the old entry carrying the superseded note **with its 6 fields intact** (no replacement with a summary) into the retired Decision Rule's **per-rule file** `.intent/compass-archive/<rule-slug>.md` (CONTRACT "Split and archive convention for append-only records"; `<rule-slug>` is derived from the retired Decision Rule's identifier via the existing slug rule — no new numbering; re-superseding the same rule collects into the same file). Create the `compass-archive/` directory if absent. Do not delete the old entry (move only; the 6 fields stay byte-unchanged). Active Decision Rules entries stay directly written inside intent-compass.md as before (no pointer indirection to another file).
+- **Do not introduce a custom Supersedes field** (do not create a dedicated field on the new entry side; the note goes on the old entry side).
+- Old 4-field entries recorded before the introduction of the 6-field format (those without Alternatives considered / Revisit when) remain valid; do not treat the missing fields as an error, flag them, or rewrite them.
+
+## 5. Final updates of declined-item tags (writeback's responsibility)
+
+- Always put one of the two tags on learnings that were not promoted: **rejected (no re-proposal)** | **on-hold (re-propose at the next writeback)**.
+- On-hold items are re-proposed at the next writeback run. The finalizing operation of **reflecting the re-proposal result (promote / confirm rejection / keep on hold) into the tag of the corresponding declined item of the old entry is writeback's responsibility**. `/intent-improve` only nudges the user to deal with on-hold items and never performs the final tag update.
+
+## 6. Digesting [question]
+
+- A `[question]` learning is considered digested once transcribed into the Open Questions of intent-tree.md.
+- Record the transcription target (intent-tree.md Open Questions) as the reflection target in the promotion record.
+
+## 7. Completion as one sequence of operations (mark done, move to archive, regenerate index)
+
+Once the write-back of the target packet is complete (after the delta's terminal state is finalized), perform the packet's completion as the following **fixed-order sequence of operations** (never leave a done packet lingering under `active/`).
+
+1. Fill in `state: done`, `closed_at` (completion date), and `spec_refs` in the frontmatter of the target packet file. `spec_refs` is the corresponding spec/feature name(s); raise candidates by cross-checking against the specs in progress under `.kiro/specs/` and finalize the entry with user confirmation.
+2. Move the packet file to `archive/<year of closed_at>/` (never delete; move only).
+3. Regenerate `index.md`: build the `| packet_id | name | state | summary |` table in ascending `packet_id` order from the frontmatter of all packet files under `active/` only (when `active/` is empty, the header-only table is the canonical form).
+
+If a done packet remains under `active/` due to an interruption or the like, the consistency check of `/intent-status` reports it as a lingering violation.
+
+## 8. Presenting past entries (repeated write-backs)
+
+- **Reading cross-reads in split form (CONTRACT "split / archive discipline for append-only records"; the same discipline as `intent-overview`'s `aggregate-sources.md` and `intent-status`'s decision-table footnote 10)**: when reading past entries of `deltas` / `export-log`, cross-read in the order the split form `.intent/<rec>/*.md` set (source of truth if present; natural-key ascending) → read-fallback to the old `.intent/<rec>.md` (the generated mirror) if absent. When the split form and the old single mirror coexist, treat **the split form as the source of truth** and do not double-count the mirror. archive (`.intent/<rec>/archive/`) is read as history (not mixed into the active tally). This reading is a path separate from writing (the split writes in §4), and the missed-writeback cross-check and the past-entry listing return the same result before and after the split (behavior-preserving).
+- At startup, always present the list of past delta entries of the target packet (including declined items with the "on-hold" tag; collected via the split-form cross-read above).
+- Writing back the same packet again (after re-export / re-implementation) appends a **new entry** without rewriting existing entries (history is preserved).
+- The mechanical check for "does a corresponding delta exist" is valid **only for the first cycle**. From the second cycle on, the user decides whether a write-back is needed after being presented the list of past entries.
+- Even after writeback completes, the target packet's drafts (`.intent/cc-sdd/<packet-slug>/`) are **never deleted** (they persist per packet). Enumerate missed write-backs by cross-checking all rows of export-log (split-form cross-read) × the surviving `.intent/cc-sdd/<packet-slug>/` drafts × deltas (split-form cross-read).
+
+## 9. Canonical deltas.md template (the source of truth)
+
+The following is **the source of truth** of the canonical deltas.md template; the scaffold (the initial content of the distributed `.intent/deltas.md`) is its copy. When changing the heading structure, always change here first.
+
+- In environments without `.intent/deltas.md` (existing users), create it anew from this template at the first run.
+- **Never overwrite an existing deltas.md** (non-destructive). On existing files, only append entries and update Status and tags.
+
+```markdown
+# Intent Deltas
+
+> Recorded by `/intent-writeback`, referenced by `/intent-status` and `/intent-improve`. The canonical deliverables (intent-tree.md / intent-compass.md / the packet files and plan.md under `.intent/packets/`) are updated after the fact only through these deltas.
+
+## How this file operates
+
+- Write-back is two-staged: `/intent-writeback` first records learnings here as a delta (it never edits the canonical deliverables directly), and only the items the user approves are promoted into the canonical deliverables.
+- One write-back of one packet = one entry. Writing back the same packet again (after re-export / re-implementation) appends a new entry (history is preserved). The mechanical check for "does a corresponding delta exist" is valid only for the first cycle; from the second cycle on, the user decides whether a write-back is needed by reviewing the list of past entries.
+- Draft retention (per-packet directories): the drafts under `.intent/cc-sdd/<packet-slug>/` persist per packet (untracked by Git, local-only). Completing a write-back does not delete the drafts. The export history is recorded in `.intent/export-log.md` (one row per export with packet name, datetime, and commit), and missed write-backs of previously exported packets are enumerated by cross-checking all rows of export-log.md × the surviving `.intent/cc-sdd/<packet-slug>/` drafts × this file.
+
+## State semantics
+
+- `pending`: recorded, not yet promoted.
+- `promoted` / `closed` are terminal states. Approving one or more items and reflecting them into the canonical deliverables → `promoted`; declining every item as "rejected" → `closed`.
+- Declined items require one of the two tags: "rejected (no re-proposal) | on-hold (re-propose at the next writeback)". Only on-hold items become re-proposal targets at the next `/intent-writeback` run (and review targets for `/intent-improve`), and the final tag update (promote / confirm rejection / keep on hold) is done by `/intent-writeback`.
+- A `[question]` learning is considered digested once transcribed into the Open Questions of intent-tree.md (record the transcription target in the promotion record's reflection target).
+
+## Delta: <packet-name> — <ISO 8601 date>
+
+- Status: pending | promoted (<promotion date>) | closed (<close date>)
+- Source: latest row of export-log.md | Source Packet in .intent/cc-sdd/<packet-slug>/ | specified by the user
+
+### Learnings
+
+- [decision] <a new decision>
+- [invariant-violation] <a discovered invariant violation>
+- [implicit-behavior] <implicit behavior not written in the intent>
+- [deferred-resolved] <a resolved Deferred>
+- [question] <a new unresolved Question>
+
+### Promotion record (when promoted / closed)
+
+- Reflected into: a new entry in intent-compass.md Decision Rules (with a superseded note on the old entry) / intent-tree.md L3 / the target packet file (under active/) / the Deferred section of plan.md (with a resolution note)
+- Declined: <learnings not promoted> — rejected (no re-proposal) | on-hold (re-propose at the next writeback)
+```

package/templates/en/intent/README.md

@@ -0,0 +1,118 @@
+# Intent Planning Workflow
+
+This directory is a lightweight Intent Planning workflow for large refactors and architecture changes.
+
+Intentionally, it is neither a CLI nor a full IDD state machine. It exists so that, before implementation, the human and Claude align on "the overall intent" and "a unified design policy" at good moments, and to prevent Claude from escaping into locally-optimal quick fixes. It complements the step just before cc-sdd creates a spec for an individual feature.
+
+## Purpose
+
+Before implementation, clarify the following.
+
+1. Intent Tree (`intent-tree.md`)
+2. Intent Compass (`intent-compass.md`; superseded Decision Rules are moved into `compass-archive.md`)
+3. Packet Plan (`packets/` — the packet files under `active/` plus `plan.md` and `index.md`; 1 packet = 1 file, and completed packets move to `archive/`)
+4. cc-sdd requirements / design / tasks drafts (per-packet `cc-sdd/<slug>/` directories; local drafts untracked by Git, except the README)
+
+## Workflow
+
+1. Run `/intent-discover`
+2. Review `intent-tree.md` (the mode and the designer-questions delegation are also confirmed)
+3. Run `/intent-compass`
+4. Review `intent-compass.md`
+5. Run `/intent-packets`
+6. Review `packets/` (`plan.md` and the packet files under `active/`)
+7. Run `/intent-export-cc-sdd`
+8. Review the cc-sdd deliverables before proceeding to implementation
+
+## Lifecycle (keep growing the intent)
+
+The workflow above is the "planning" phase. After export, the intent is not disposable; keep growing it through the following cycle.
+
+- Plan: `/intent-discover` → `/intent-compass` → `/intent-packets` → `/intent-export-cc-sdd`
+- Implement: implement with cc-sdd
+- Maintain: `/intent-writeback` (feed learnings back per packet), and `/intent-improve` at milestones (re-align the whole)
+- Anytime: `/intent-status` (where you are and the next move), `/intent-validate` (verification before export)
+
+Learnings from `/intent-writeback` are recorded into `deltas.md` as deltas (the canonical deliverables are never edited directly), and `/intent-status` and `/intent-improve` refer to them.
+
+### When to use which skill
+
+| Skill | Timing | Role |
+|--------|-----------|------|
+| `/intent-status` | Anytime (when unsure) | Recommend a summary of where you are plus exactly one "next move" (read-only) |
+| `/intent-validate` | Before export (recommended) | Report contradictions, coverage gaps, and boundary inconsistencies across deliverables with severity (read-only) |
+| `/intent-writeback` | After a packet's implementation is done | Record the learnings gained from the implementation into `deltas.md`, and promote only the approved items into the canonical deliverables |
+| `/intent-improve` | At milestones (e.g. after implementing several packets) | Re-align `.intent/` with the implementation reality on the three axes of completeness / correctness / coherence |
+
+For the four planning-phase skills (`/intent-discover`, `/intent-compass`, `/intent-packets`, `/intent-export-cc-sdd`), see "Workflow" above.
+
+## Mode (the Intent-working algorithm)
+
+How to work out the Intent is switchable as a "mode". The selected mode is recorded in `mode.md`, and each command reads it to operate with a consistent strategy. Mode definitions live in `modes/`, and new modes can be added (see `modes/README.md`).
+
+`mode.md` also records the designer-questions delegation (designer-questions: on / off) as an axis orthogonal to the mode. At the entry point, `/intent-discover` explains what the flow can ask on your behalf and confirms whether you want it. When on, the common additional confirmations (L1 measurement criteria, walking skeleton, screen rough) and the normative checks of `/intent-validate` become active, and the development purpose (purpose: poc / product) is also confirmed — when poc, the hypothesis / falsification criteria / GO-NO-GO confirmations are added. When off, the only increment is that single opt-in question.
+
+## Enforcement (writeback-miss checks, optional)
+
+An optional layer that mechanically detects missed `/intent-writeback` runs. **The default is off**, and nothing changes unless you configure it. Switch it by directly editing the "Enforcement (user-managed)" section of `mode.md` (`off` = default, no checks / `remind` = warnings only / `gate` = stops export / push).
+
+Two things are checked.
+
+- **Neglected pending deltas (the main check)** — deltas recorded in `deltas.md` that remain unapproved and unpromoted
+- **Staleness (experimental)** — the state where the number of commits changing anything outside `.intent/` since the last writeback (or export) exceeds the threshold (`enforcement-threshold`, default: 5). Unrelated commits are counted too, so false positives remain. Paths can be excluded from the count via `enforcement-exclude`. Starting with `remind` is recommended
+
+The checks take effect in three places: before export in `/intent-export-cc-sdd`, as warnings in `/intent-status`, and in the pre-push hook placed by the installer's `--enforce`. All judgments are made by the read-only script `scripts/intent-check.mjs` (it never creates, modifies, or deletes files). Even when gate stops you, escape hatches remain: an explicit instruction to continue, or `git push --no-verify`. Enforcement only forces the execution of the procedure; it does not guarantee the correctness of what is written back.
+
+### Claude Code SessionStart hook (optional)
+
+If you want writeback-miss warnings injected into the agent's context at session start, manually add the following to `.claude/settings.json` (intent-planner never writes this automatically).
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          { "type": "command", "command": "node .intent/scripts/intent-check.mjs" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Caveats (known limitations)
+
+- In nvm / volta environments, GUI git clients may not have node on their PATH; in that case the pre-push hook check is skipped (a one-line notice is printed to stderr)
+- In environments using `core.hooksPath` (husky etc.), `.git/hooks` is never invoked, so the placed pre-push hook has no effect
+- In environments where `.git` is a file, such as git worktrees and submodules, hook placement via `--enforce` fails
+- To use enforcement in an environment set up with an older scaffold, manually add the Enforcement section to `mode.md` (copy the section from the latest template)
+
+## Drift-watch (drift monitoring, optional)
+
+Another **optional cross-cutting layer** alongside enforcement. As implementation proceeds after the intent is set, the software tends to "stop being the software you intended" (architectural drift); this layer catches that by name before it drifts away completely. It is **not a mode** (a mode is exclusive — only one is active at a time; drift-watch is an independent `off` | `on` switch).
+
+**The default is off**, and nothing changes unless you configure it. Switch it to `on` by directly editing the "Drift-watch (user-managed)" section of `mode.md`.
+
+When on, `/intent-discover` runs a terrain diagnosis of the Intent Tree, and `/intent-export-cc-sdd` shows compass-matching warnings at the export waterline. **Both are warnings only and never stop you** (a separate concept from enforcement's `gate`; since false positives are assumed, there is no stopping value). Detections are recorded locally in `.intent/drift-log.md` (nothing is ever sent externally; it stays within `.intent/`).
+
+The basis is `.intent/drift-patterns.md` (a catalog of drift patterns). The distributed seed is not exhaustive; the premise is that **you grow it by adding the drifts you actually hit in your own work** as patterns. Aggregation (the improvement report) adds no new command — it rides on the light summary in `/intent-status` and the pattern×outcome cross-tabulation in `/intent-improve`.
+
+## Rules for Agents
+
+### Planning Phase (when running intent-* skills)
+
+- Do not change application code during the Intent Planning phase.
+- Do not propose local refactors that do not support a parent intent.
+- Each packet must always reference a parent intent.
+- Each task must preserve the invariants.
+- When intent is unclear, do not edit code; write it into Open Questions.
+- Treat inferred intent as provisional until a human reviews it.
+
+### Implementation Phase (Agent Contract — for agents implementing packets)
+
+1. Treat Invariants as hard constraints.
+2. Treat Decision Rules as effective unless explicitly marked superseded.
+3. Do not produce an implementation that falls under an Anti-direction.
+4. When a packet contradicts the Compass, stop implementing and confirm with the human.
+5. When the code reality contradicts the intent, record it as a delta (`/intent-writeback`); do not silently rewrite the intent.

package/templates/en/intent/cc-sdd/README.md

@@ -0,0 +1,28 @@
+# cc-sdd Export Drafts
+
+> `/intent-export-cc-sdd` writes per-packet drafts under this directory. Everything except this README is NOT tracked by Git (local-only). The readers are the user handing drafts to cc-sdd, plus `/intent-writeback`, `/intent-status`, and `/intent-validate`. The authority for the draft format is the export skill's rules (map-cc-sdd); no scaffold templates live here.
+
+## Structure
+
+```
+.intent/cc-sdd/
+├── README.md          # this note (tracked by Git)
+└── <packet-slug>/     # generated per packet by /intent-export-cc-sdd (untracked)
+    ├── requirements.md
+    ├── design.md
+    └── tasks.md
+```
+
+The directory name (slug) is derived deterministically from the packet name (see map-cc-sdd for the rule and collision handling).
+
+## Role of the 3 drafts
+
+- **requirements.md** — the condensed Project Description passed to cc-sdd's `/kiro-spec-init`. Always includes the headings `## Source Packet` (exact transcription of the packet name), `## Parent Intent`, and `## Invariants`.
+- **design.md** — oversight-prevention hints (bullets) for when cc-sdd generates the design. Not the main body.
+- **tasks.md** — intent-derived constraints (parent intent / invariants / anti-direction) first, followed by check items for cc-sdd's tasks generation.
+
+## Git-untracked policy
+
+- Drafts under the packet directories are local-only and not tracked by Git (only this README is tracked). By design, this prevents team merge conflicts and draft loss by overwriting.
+- The history of exports lives in the Git-shared `.intent/export-log.md` (1 export = 1 line). That log is also the canonical source for resolving the "current packet".
+- Drafts are not deleted after writeback; they remain available for cross-checking missed writebacks (export-log × remaining drafts × deltas.md).

package/templates/en/intent/compass-archive/README.md

@@ -0,0 +1,9 @@
+# compass-archive/ (split form)
+
+compass-archive is the record that retires superseded Decision Rules, so write it split into **per-superseded-rule files (rule-unit)** `compass-archive/<rule-slug>.md`. Re-superseding the same rule collects into the same file (the rule is the natural key).
+
+- The `<rule-slug>` is derived from the retired Decision Rule's identifier via the existing slug rule (`intent-packets/rules/packet-format.md`). Do not use sequential numbering (a central counter like `0001`).
+- Retirement happens when writeback / improve supersedes a Decision Rule. **Move the 6 fields (Context / Decision / Why / Alternatives considered / Consequences / Revisit when) + the successor reference verbatim (byte-unchanged)** — do not summarize or alter them (record content is immutable).
+- Since this directory is itself the archive role, the `archive/` subdirectory is a further per-year refuge when needed.
+
+> This README is a **restatement** of the rule. The single source of truth is CONTRACT.md "Split & archive discipline for append-only records". Consult CONTRACT for placement decisions.

package/templates/en/intent/compass-archive.md

@@ -0,0 +1,7 @@
+# Compass Archive
+
+> `/intent-writeback` and `/intent-improve` move Decision Rules entries that became superseded here, appending them at the end with all 6 fields intact. The reader is a human, consulting this only when needed. Existing lines are never modified.
+
+Format example (append at the end in this exact 6-field form, with a superseded note + successor reference):
+
+- **Context**: (the question and situation) / **Decision**: (the option taken) / **Why**: (the criteria) / **Alternatives considered**: (the alternatives considered and why rejected) / **Consequences**: (connection to Invariants and Anti-direction) / **Revisit when**: (the condition for revisiting) — superseded: (reference to the successor entry)

package/templates/en/intent/constraint-library.md

@@ -0,0 +1,32 @@
+# Constraint Library (the constraint ledger you grow)
+
+> A ledger for accumulating and reusing the constraints (Anti-direction / Invariant) you use repeatedly, inside this project's `.intent/`. When `/intent-compass` surfaces drafts, it lists the constraints you have accumulated here alongside the bundled `constraint-starters.md`. **Editing is done by a human; the skill only reads and never auto-modifies.** Writing an adopted constraint into this ledger is also done by a human (or with explicit human approval).
+
+## How to use this ledger
+
+- **This is a file you grow.** As you repeat development in the same domain, constraints accumulate — "I always make this an Anti-direction / Invariant." Append them here and reuse them.
+- **It stays within this project.** This ledger is placed only under this repo's `.intent/`, and is never shared across projects (so that even for work where assets cannot leave, constraints do not leak outside the project). Reinstalling or upgrading does not overwrite what you wrote here.
+- **It is canonical (human-edited).** The surfacing skill references this ledger read-only and never rewrites it automatically.
+- **This is a static document.** It never queries an external service or database when used.
+
+## Entry schema
+
+Append constraints you use repeatedly with the schema below. Make `id` a unique kebab-case key.
+
+```markdown
+## id: <kebab-case identifier key>
+- name: <short name>
+- domain: <code | non-code>
+- fits when: <for what kind of work or material you want this constraint to apply>
+- constraint:
+  - Anti-direction: <the direction to avoid>
+  - Invariant: <the invariant to keep>
+- origin: <where you learned this constraint / why it is one of your defaults (optional)>
+```
+
+- Constraints accumulated here appear as candidates alongside the bundled catalog when `/intent-compass` surfaces drafts (surfacing stops at candidates; a human decides whether to adopt).
+- The bundled `constraint-starters.md` (conventions the developers maintain and ship) and this `constraint-library.md` (constraints you grow) are separate files.
+
+---
+
+<!-- Below this line, append your repeatedly-used constraints (following the entry schema above). -->

package/templates/en/intent/constraint-starters.md

@@ -0,0 +1,58 @@
+# Constraint Starters (catalog of constraint starting points)
+
+> Read by `/intent-compass` (primary touchpoint) and `/intent-discover` (terrain diagnosis lane) as **draft candidates** when writing Anti-direction / Invariants. It is the source set for matching bundled domain conventions against your context to surface "this case is probably this." **Surfacing is a read-only draft; transcription into the compass happens manually after a human picks what to adopt** (the AI does not auto-transcribe). Constraints you personally reuse are grown in a separate file, `constraint-library.md`.
+
+## How to read this catalog
+
+- **This is not exhaustive.** The conventions listed here are only a starting point (2 seeds, one each for code / non-code). Later surfacing only lists conventions that fit the context as **candidates**; you decide whether to adopt them.
+- Each convention is identified by `id` (kebab-case). `domain` distinguishes code vs non-code, `fits when` describes "for what kind of work it helps," and `starter` holds the Anti-direction / Invariant candidates.
+- **This is a supplement, not a replacement.** The compass's Anti-direction/Invariant derivation (impact list → Invariants, premortem → Anti-direction) stays as is; this only injects draft candidates ahead of it.
+- **This is a static document.** It never queries an external service, online lookup, or database when used. It also makes no external call to "fetch the latest conventions." It stays within the bundled static content plus contextual completion in later slices.
+- **This is a separate catalog from the existing drift catalog (drift-patterns) and context-cost catalog (context-cost-cues).** Because what it accumulates differs (reusable constraint conventions), it is a separate file, and it never touches the drift log's (drift-log) records or aggregation.
+
+## Provenance and accuracy discipline (quality of bundled conventions)
+
+- **Every convention must carry a source (`source` field).** Record the basis (a primary-source URL, etc.) and the retrieval date; do not bundle conventions of unknown provenance. This is the guardrail against pushing wrong or stale conventions as "this case is probably this."
+- **Accuracy review**: When adding or updating a convention, confirm the source exists and is still valid (do not attach guessed or fabricated sources).
+- **Update policy**: When a source goes stale (recommendation changed, retracted, etc.), update the source or revisit the convention itself.
+- **License**: When quoting from a source, respect the source's license and terms of use.
+
+## How to write a convention
+
+Append a new convention with the schema below. Make `id` a unique kebab-case key. `source` is required (do not add a convention without a source).
+
+```markdown
+## id: <kebab-case identifier key>
+- name: <short name>
+- domain: <code | non-code>
+- fits when: <for what kind of work or material this convention helps. A cue the compass/discover matches against context>
+- starter:
+  - Anti-direction: <the anti-direction candidate to surface in that situation>
+  - Invariant: <the invariant candidate. If material-dependent, the compass concretizes it from context>
+- source: <basis (primary-source URL, etc.) and retrieval date. Required>
+```
+
+- `fits when` is written as a matching cue, not a strong rule of "if this matches it must be this convention" (false positives are assumed; candidates are narrowed, not pushed).
+- `starter` is **not a confirmed value to drop straight into** the compass's Anti-direction/Invariants — it is a candidate a human picks.
+
+---
+
+## id: sql-injection-placeholder
+
+- name: SQL injection prevention (always use placeholders)
+- domain: code
+- fits when: A web app or similar that builds SQL or queries a database using values that include user input. When you see queries being built by string concatenation.
+- starter:
+  - Anti-direction: Do not embed user input into SQL by string concatenation. Do not execute a dynamically assembled query string as-is.
+  - Invariant: User-derived values must always be passed via placeholders (parameterized queries). Never concatenate values as part of SQL syntax.
+- source: OWASP SQL Injection Prevention Cheat Sheet (https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html, retrieved 2026-06-21)
+
+## id: slide-deck-structure
+
+- name: Presentation deck structure (claim first, one message per slide)
+- domain: non-code
+- fits when: Building a presentation deck, slides, or a proposal. When you see a tendency to cram in information or hold the conclusion until the end.
+- starter:
+  - Anti-direction: Do not cram multiple claims onto one slide. Do not start from a list of facts with the conclusion hidden until the end.
+  - Invariant: Keep one slide = one message. Each slide leads with its claim (conclusion) and supports it with evidence.
+- source: Barbara Minto "The Pyramid Principle" (conclusion-first, MECE structure) / Garr Reynolds "Presentation Zen" (one message per slide), retrieved 2026-06-21

package/templates/en/intent/context-cost-cues.md

@@ -0,0 +1,55 @@
+# Context Cost Cues (catalog of context-eating situations)
+
+> Read by `/intent-discover` and `/intent-improve` (when `drift-watch: on`). **These are cues to make you notice situations that eat context; they do not deny or correct you.** Installing many skills or loading full content can be a legitimate choice that improves accuracy. **Nothing is recorded to any log** (consumption is not measurable, and recording it would intrude on privacy such as your settings and skill setup). This is a file you grow by appending the types you actually hit in your own project.
+
+## How to read this catalog
+
+- **This is not exhaustive.** The types listed here are only a starting point (4 seeds). The premise is that you append the context-eating situations you actually hit in your own project as types and grow this file over time.
+- Each type is identified by its aggregation key (`id`). The more types you add, the wider the range over which you can notice "this might be eating context".
+- **This is awareness, not a norm.** A type "matching" is not a confirmation of waste. Installing many skills or loading full content can be a deliberate, legitimate choice. When a type matches, it only **makes you notice** "this might be eating context", and leaves the judgment of waste-or-not to you. It does not say "fix it".
+- **Nothing is recorded to any log.** Consumption cannot be measured, and what eats context legitimately differs per person, so recording it would intrude on privacy. The cue stays a read-only suggestion.
+
+## How to write a type
+
+Append a new type with the schema below. Make `id` a unique kebab-case aggregation key.
+
+```markdown
+## id: <kebab-case aggregation key>
+- name: <short name>
+- symptom: <cue about the subject / how it is progressing; a weak cue discover or improve matches against the subject>
+- If this is unintentional:
+  - Instead: <a light alternative to recall if it was working unintentionally (thin entry point / JIT pull / limited input); an optional choice, not a command>
+```
+
+- Write `symptom` as a cue for matching, not as a strong decision condition meaning "if this matches it is definitely waste" (keeping it a weak cue avoids fixation).
+- "If this is unintentional" is an **optional light alternative** to recall when this type is suspected. Do not use imperatives ("fix it", "stop it"), and do not deny a deliberate high-cost choice.
+
+---
+
+## id: full-compass-load
+
+- name: Full compass load
+- symptom: You may be reading the whole of intent-compass.md (the decision-criteria document) when you only need one point. A way of progressing where you load the entire document into context just to check a single Invariant / Decision Rule.
+- If this is unintentional:
+  - Instead: there is a lighter alternative of pulling the needed Decision Rule / Invariant JIT by heading (reading only that section from a thin entry point). If you genuinely need the whole document, leave it as is.
+
+## id: whole-tree-read
+
+- name: Whole intent-tree read
+- symptom: You may be reading all of intent-tree.md every time when you only need one of L0–L3. A way of progressing where you load the entire tree into context when you only want to reference a specific outcome or capability.
+- If this is unintentional:
+  - Instead: there is a lighter alternative of reading only the layer you need by name, rather than pasting the whole tree into a fixed-load context. If you need the full overview, leave it as is.
+
+## id: steering-bloat
+
+- name: Fixed-load context bloat
+- symptom: You may be bloating the fixed context that gets loaded every time with generated steering or reference documents. A way of progressing where the always-loaded set grows each time you add a responsibility, so context swells linearly.
+- If this is unintentional:
+  - Instead: there is a lighter alternative of keeping the fixed load thin and offloading details to references, pulling them only when needed. If you are sure that context is always needed, leave it as is.
+
+## id: redundant-reread
+
+- name: Redundant re-read
+- symptom: You may be re-reading a file you just read or edited, even though its content has not changed. A way of progressing where you load the same content into context multiple times in a short interval.
+- If this is unintentional:
+  - Instead: there is a lighter alternative of using what you just read/edited as is and skipping the re-read. If you want to confirm a possible change (e.g. from a concurrent edit), leave it as is.

package/templates/en/intent/deltas/README.md

@@ -0,0 +1,11 @@
+# deltas/ (split-form active surface)
+
+deltas is a **packet-derived** record, so write it split into **per-packet files** `deltas/<packet-slug>.md`. Different packets touch different files, so tail-append conflicts are eliminated by construction.
+
+- Keep only the currently-referenced deltas here (the active surface), kept thin.
+- Move terminal (no-longer-updated) entries into `deltas/archive/<year>/`.
+- The `<packet-slug>` in the filename follows the existing packet slug rule (`intent-packets/rules/packet-format.md`). Do not use sequential numbering (a central counter like `0001`).
+
+> This README is a **restatement** of the rule. The single source of truth is CONTRACT.md "Split & archive discipline for append-only records". Consult CONTRACT for placement decisions.
+
+The existing single file `../deltas.md` may remain (it coexists with the new split form). Do not put real entries in the active surface; entries are generated in split form by writeback/discover.

package/templates/en/intent/deltas.md

@@ -0,0 +1,34 @@
+# Intent Deltas
+
+> Recorded by `/intent-writeback`, referenced by `/intent-status` and `/intent-improve`. The canonical deliverables (intent-tree.md / intent-compass.md / the packet files and plan.md under `.intent/packets/`) are updated after the fact only through these deltas.
+
+## How this file operates
+
+- Write-back is two-staged: `/intent-writeback` first records learnings here as a delta (it never edits the canonical deliverables directly), and only the items the user approves are promoted into the canonical deliverables.
+- One write-back of one packet = one entry. Writing back the same packet again (after re-export / re-implementation) appends a new entry (history is preserved). The mechanical check for "does a corresponding delta exist" is valid only for the first cycle; from the second cycle on, the user decides whether a write-back is needed by reviewing the list of past entries.
+- Draft retention (per-packet directories): the drafts under `.intent/cc-sdd/<packet-slug>/` persist per packet (untracked by Git, local-only). Completing a write-back does not delete the drafts. The export history is recorded in `.intent/export-log.md` (one row per export with packet name, datetime, and commit), and missed write-backs of previously exported packets are enumerated by cross-checking all rows of export-log.md × the surviving `.intent/cc-sdd/<packet-slug>/` drafts × this file.
+
+## State semantics
+
+- `pending`: recorded, not yet promoted.
+- `promoted` / `closed` are terminal states. Approving one or more items and reflecting them into the canonical deliverables → `promoted`; declining every item as "rejected" → `closed`.
+- Declined items require one of the two tags: "rejected (no re-proposal) | on-hold (re-propose at the next writeback)". Only on-hold items become re-proposal targets at the next `/intent-writeback` run (and review targets for `/intent-improve`), and the final tag update (promote / confirm rejection / keep on hold) is done by `/intent-writeback`.
+- A `[question]` learning is considered digested once transcribed into the Open Questions of intent-tree.md (record the transcription target in the promotion record's reflection target).
+
+## Delta: <packet-name> — <ISO 8601 date>
+
+- Status: pending | promoted (<promotion date>) | closed (<close date>)
+- Source: latest row of export-log.md | Source Packet in .intent/cc-sdd/<packet-slug>/ | specified by the user
+
+### Learnings
+
+- [decision] <a new decision>
+- [invariant-violation] <a discovered invariant violation>
+- [implicit-behavior] <implicit behavior not written in the intent>
+- [deferred-resolved] <a resolved Deferred>
+- [question] <a new unresolved Question>
+
+### Promotion record (when promoted / closed)
+
+- Reflected into: a new entry in intent-compass.md Decision Rules (with a superseded note on the old entry) / intent-tree.md L3 / the target packet file (under active/) / the Deferred section of plan.md (with a resolution note)
+- Declined: <learnings not promoted> — rejected (no re-proposal) | on-hold (re-propose at the next writeback)

package/templates/en/intent/drift-log/README.md

@@ -0,0 +1,11 @@
+# drift-log/ (split-form active surface)
+
+drift-log is an **event-derived** record, so write it split into **date+slug files** `drift-log/<date>-<slug>.md`. Different events touch different files, so tail-append conflicts are eliminated by construction.
+
+- Keep only the currently-referenced events here (the active surface), kept thin.
+- Move terminal (no-longer-updated) entries into `drift-log/archive/<year>/`.
+- The `<slug>` in the filename follows the existing slug rule (`intent-packets/rules/packet-format.md`). Do not use sequential numbering (a central counter like `0001`).
+
+> This README is a **restatement** of the rule. The single source of truth is CONTRACT.md "Split & archive discipline for append-only records". Consult CONTRACT for placement decisions.
+
+The existing single file `../drift-log.md` may remain (it coexists with the new split form). The 9-key schema (record contents) is unchanged. Do not put real entries in the active surface; entries are generated in split form by the drift-record writer.

package/templates/en/intent/drift-log.md

@@ -0,0 +1,41 @@
+# Drift Log
+
+> The hooks of `/intent-discover`, `/intent-export-cc-sdd`, and `/intent-improve` append one entry per detected drift. The only writers are these three hooks; the readers are `/intent-status` (a light summary) and `/intent-improve` (a `pattern × outcome` cross-tabulation). When `drift-watch: off` (the default), nobody writes here.
+>
+> **How to read this**: read `missed=0` as "a suspicion of missing records," not as "evidence it worked." Keeping only the moments it worked (prevented / caught) in the tally is confirmation bias. This file is designed on the premise that the moments it did not work (missed / false-positive / not-applicable) are recorded just as evenly.
+
+## How this file operates
+
+- **append-only**: entries are appended only. Never rewrite or delete a past entry (to avoid creating an asymmetry in the world-line anchor).
+- **outcome is a draft / user-verdict is the verdict**: `outcome` is estimated and drafted by drift-watch. `user-verdict` is confirmed by the user (the same separation as canonical / inferred in the Intent Tree). Even if the user has not judged it, it stays `unjudged` and remains a target for recording and tallying.
+- **world-line anchor (Layer 1)**: each entry carries `recorded_at` (the time it was recorded) and `commit` (the world-line it was recorded on) from the start. Adding them to past entries after the fact creates an asymmetry, so they are recorded from the start. Immutability is delegated to git, and this file is kept as a "projection of the present."
+- **no validity period**: because drift is an event, not a state, it has no valid-time fields such as `valid_until`.
+
+## Entry format
+
+Each entry carries the following 9 keys as a fixed-order Markdown list. The sample below, wrapped in `<!-- -->` (an HTML comment), is a fill-in template and is not included in real entries.
+
+<!--
+### drift-log entry
+- pattern: <a drift-patterns id | uncatalogued:<short name>>
+- stage: <discover | export | improve>
+- packet: <packet name | ->
+- mechanism: <compass-anti-direction | compass-invariant | pattern-catalog | packet-scope-overflow | none>
+- outcome: <prevented | caught | missed | false-positive | not-applicable>
+- user-verdict: <valid | false-alarm | unjudged>
+- recorded_at: <ISO 8601>          # transaction time (the time it was recorded)
+- commit: <short hash | ->         # world-line anchor (Layer 1). - when unavailable
+- note: <1-2 lines>
+-->
+
+## The 5 outcome values (structural avoidance of confirmation bias)
+
+The "worked" family and the "did not work" family are enumerated symmetrically. We do not physically create a "field that only records effective."
+
+| Worked | Did not work |
+|---|---|
+| `prevented` (prevention succeeded at discover) | `missed` (could not prevent it, it got through) |
+| `caught` (capture succeeded at export) | `false-positive` (it was a false alarm) |
+| | `not-applicable` (not present in the terrain; a swing and a miss) |
+
+Tallying assumes a `pattern × outcome` cross-tabulation. Read `missed=0` as "a suspicion of missing records," not as "it worked."