intent-planner 0.13.1

package/templates/en/claude/skills/intent-packets/rules/packet-format.md

@@ -0,0 +1,207 @@
+# Packet file format
+
+The **single canonical source** for the packet file format, ID rule, state transitions, and the index regeneration procedure (`.intent/packets/active/<packet_id>.md` and `.intent/packets/archive/<year>/<packet_id>.md`). Skills that create, update, or move packets — and skills that read packets — follow these rules.
+
+## Frontmatter schema (12 fixed keys)
+
+Each packet file starts with a YAML frontmatter (`---` delimited). The keys are **fixed to these 12**: `packet_id` / `name` / `state` / `created_at` / `updated_at` / `closed_at` / `parent_intents` / `spec_refs` / `superseded_by` / `summary` / `depends_on` / `mode`.
+
+```yaml
+---
+packet_id: pkt-20260612-auth-session-k3p9   # Immutable. Matches the file name. Trailing segment is a session-specific rand. For packet-to-packet references only
+name: "Auth session cleanup"           # Canonical packet name. Matching key for export-log / Source Packet / deltas / slug derivation
+state: implementing                    # draft | ready | implementing | verifying | done
+created_at: 2026-06-12T05:00:00Z       # Creation timestamp (ISO 8601)
+updated_at: 2026-06-12T05:00:00Z       # Last-updated timestamp (ISO 8601). Equal to created_at on creation; the moment of update on content change
+closed_at: ""                          # Filled in when done (date). Leave empty if unknown at migration
+parent_intents: [L1-2, L2-3]           # References into the tree
+spec_refs: []                          # Finalized at writeback completion
+superseded_by: ""                      # Successor packet_id when superseded
+summary: "Clean up auth sessions"      # Source of the one-line summary in the index
+depends_on: []                         # List of packet_ids this packet depends on (default []). For packet-to-packet references only
+mode: standard                         # Mode confirmed at draft time (fixed at draft time; never retroactively updated)
+---
+```
+
+- `state` takes one of 5 values: `draft | ready | implementing | verifying | done` (see "State value domain"). Superseded is **not a state** but a separate axis expressed by filling in `superseded_by` (see "State transitions and placement").
+- `depends_on` is a list of the `packet_id`s of the packets this packet depends on (default `[]`). Like `superseded_by`, **packet-to-packet references use `packet_id`** (never `name`). It holds only dependencies declared by a human; tools do not infer or compute dependencies.
+- **`mode` is the provenance record of the mode that was confirmed at the time the packet was drafted**. The value is a mode name (e.g. `standard` / `deep` / `quick`). The intent-packets skill resolves the mode at draft time using the CONTRACT.md fallback rule (mode.local.md → mode.md → standard) and stamps the resolved value. **Fixed at draft time** (DR13) — never retroactively update an existing packet's `mode` even if the local mode changes after drafting. If the mode is absent or undetermined, record the default `standard` and do not stop. **Backward compatibility**: an existing packet without `mode` is treated as a missing field; continue without stopping and do not auto-complete on every read. Not stamped in tree / compass / plan (DR11).
+- **`updated_at` is the packet's last-updated timestamp (ISO 8601)**. It is the canonical field that a writer skill (intent-packets / writeback etc.) stamps at the moment it changes the packet. The stamping discipline is:
+  - **On creation, initialize it equal to `created_at`** (never `—` or empty).
+  - **Record the moment of a content update** into `updated_at` (stamp the current time at that moment in ISO 8601).
+  - **Do not stamp on a re-run that involves no content change (idempotent)**. Do not advance the timestamp without a change.
+  - The stamping responsibility belongs to the writing phase (intent-packets / writeback etc.); the read-only verification layer (intent-validate) **only reads** `updated_at` and never rewrites it.
+  - **Backward compatibility**: an existing packet without `updated_at` is treated as a missing field; do not force an immediate bulk migration. The reader makes the absence explicit as "unfilled / unobserved" and does not fill it in by guessing (lazy completion, isomorphic to absent `depends_on` = "no dependencies"). The next writer flow that updates the packet appends it as a differential edit (non-destructive).
+- **Keep undetermined keys with empty values** (never omit the key itself — for determinism of index regeneration and checks). `depends_on` keeps `[]` even when there are no dependencies; do not omit the key.
+- **Summary maintenance norm**: a skill that updates a packet's body must also keep the frontmatter `summary` in sync.
+
+## How name and packet_id are used
+
+- **`name` is the canonical packet name (the matching key)**. The export-log `| packet |` column, the `## Source Packet` heading of cc-sdd drafts, the Delta headings in deltas, and the cc-sdd slug derivation all use `name`. Never use `packet_id` for any of these.
+- **`packet_id` is reserved for the file name (`<packet_id>.md`) and packet-to-packet references such as `superseded_by`**.
+
+### Mutability of name
+
+- After the first export (the moment a row lands in the export-log), `name` is **immutable**. Treat a rename as a supersede (create a successor packet + replace the old packet).
+- Renaming before export is allowed as a differential update (even then, `packet_id` and the file name do not change).
+
+### Resolving a name to a file
+
+1. Match the `name` column of `index.md`, or the frontmatter `name` under `active/`, to identify the file.
+2. If it is not in `active/`, reference `archive/` **explicitly** (an explicit exception to the principle "archive/ is normally not read").
+
+## ID rule
+
+- Format: `pkt-<YYYYMMDD>-<slug>-<rand>`. The date part is the **creation date** (obtained via the shell). The trailing `<rand>` is a **session-specific short random token** (see below) that guarantees IDs never collide even across concurrent sessions; it is part of the immutable identifier.
+- `<rand>` is 4 characters of lowercase ASCII letters and digits (`[a-z0-9]`), generated via the shell at creation time (e.g. `LC_ALL=C tr -dc 'a-z0-9' < /dev/urandom | head -c 4`). If it cannot be generated, do not fill in a guessed value; notify the user and stop (same discipline as when the date cannot be obtained).
+- The slug is derived from `name` by the rule in the next subsection. The next subsection is a **verbatim copy** of map-cc-sdd (the slug rule of the cc-sdd export); when changing it, revise both at the same time (the cc-sdd output directory name is derived from the same `name` by the same rule, so the two coincide).
+
+### Slug rule (deterministic)
+
+Derive the directory name (slug) from the packet name **deterministically** in the following order. The same packet name always yields the same slug.
+
+1. Apply NFC normalization.
+2. Trim leading/trailing whitespace.
+3. Lowercase ASCII uppercase letters.
+4. Replace whitespace and path-dangerous characters (`/ \ : * ? " < > |`) with `-`.
+5. Collapse consecutive `-` into one.
+6. Strip leading/trailing `-`.
+
+- Non-ASCII characters (Japanese etc.) are preserved as-is.
+- If the result is an empty string, use `unnamed-packet` as the slug and notify the user.
+
+### Collision avoidance (concurrent sessions)
+
+- The trailing `<rand>` ensures that creating a **different packet** with the same slug on the same day never yields a colliding ID. Even when **concurrent (parallel) sessions** cannot read each other's unsaved packets, the independently generated `<rand>` values differ, so the IDs differ. The old approach of reading existing packets and then assigning a numbered suffix (`-2`, `-3`, …) is not used, because parallel sessions cannot see each other and so cannot prevent the collision that way.
+- If, at creation time, a generated ID happens to match an existing file (in `active/` or `archive/`), never silently overwrite: regenerate `<rand>`, assign a different ID, and notify the user of the packet-name → ID mapping.
+- `packet_id` and the file name (`<packet_id>.md`) are **immutable** (they do not change on rename, state change, or move). Once fixed, `<rand>` — as part of the ID — does not change either.
+- **Backward compatibility**: legacy IDs without `<rand>` (`pkt-<YYYYMMDD>-<slug>`) remain valid. Do not force an immediate bulk migration; leave existing packet IDs as-is (a rename is treated as a supersede).
+
+## State value domain
+
+`state` is one of 5 values distinguishing the stage of progress. The values are mutually exclusive, and a packet is in exactly one stage. State is a **declarative state record**, not a management mechanism (state machine) with transition rules, guards, or automatic progression.
+
+| state | Meaning | Placement | Evidence | depends_on |
+|-------|---------|-----------|----------|------------|
+| `draft` | Drafting / undetermined | `active/` | Not required | Optional |
+| `ready` | Ready to start (dependencies resolved, awaiting implementation) | `active/` | Not required | Declaring it presumes all dependencies are `done` |
+| `implementing` | Under implementation | `active/` | Provisional in-progress records allowed | — |
+| `verifying` | Implemented, awaiting verification (Evidence undetermined) | `active/` | Being collected (mark as undetermined) | — |
+| `done` | Evidence obtained / complete | `archive/<year>/` | **Presumed finalized** | — |
+
+- The only terminal value is `done`. Finalizing `state=done` presupposes that the `## Evidence` section has finalized verification results (a declarative order of "human/check confirms → record → done", not an automatic transition).
+- Changes to the stage of progress are recorded declaratively, and their finalization rests on a human or a check gate (not finalized by AI self-report alone).
+
+### Backward-compatible migration (from the old `draft | active | done`)
+
+| Old state | New state | Rationale |
+|-----------|-----------|-----------|
+| `draft` | `draft` | Same |
+| `active` | `implementing` | Safe-side default for a started packet (loses the least information; can later be re-declared `ready`/`verifying`) |
+| `done` | `done` | Same |
+
+- Why `active → implementing` is the default: the old `active` covered both "started" and "ready to start", so we err on the safe side (treat as in progress) to prevent "treated as done while not finished".
+- Migration is **presented as a differential update proposal** and recorded after user confirmation. It does not destroy or delete existing packets (**move only**).
+- **Handling missing `depends_on`/`## Evidence`**: even if an existing packet lacks the `depends_on` key or the `## Evidence` section, do not force an immediate bulk migration. The reader treats absent `depends_on` as "no dependencies (equivalent to the empty set)" and absent `Evidence` as "unfilled" (do not fill in by guessing). The next create/update flow that touches the packet appends `depends_on: []` as a differential edit (non-destructive lazy completion).
+
+## State transitions and placement
+
+- Superseded is **not a state** but a separate axis: fill in `superseded_by` with the successor `packet_id`, not the state.
+- Placement mapping:
+  - `draft | ready | implementing | verifying` → `active/`
+  - `done` or `superseded_by` filled in → `archive/<year>/`
+- Writing the state and moving the file are one combined operation (never leave a done packet lingering in `active/`; lingering is subject to status's integrity checks).
+- **No deletion**: packet files are only moved, never deleted.
+
+## Body section structure
+
+Right after the frontmatter, place a `# <name>` heading (recommended), followed by the sections below (inheriting the structure of the current packet definition section).
+
+- `## Parent Intent` — The L0 / L1 / L2 / L3 this packet supports.
+- `## Why` — Why this packet is needed.
+- `## Scope` — What is included.
+- `## Non-scope` — What is not included.
+- `## Expected Behavior` — The behavior observable after completion.
+- `## Decisions` — Decision slots under constraints (the ④-centered slots of the completeness schema). Place it **after `## Expected Behavior` and before `## Safety / Invariants`**. **The canonical source of the slot value domain (`finalized value | undetermined (with reason) | not applicable`), the 4 statuses, the firing conditions, and the slot IDs is `decision-slots.md`** (read that catalog as the single reference; this section is its projection). **Required section** (unlike the optional sections below, it is always kept as the container that closes the common-core slots; if no slots are seeded, keep an empty section and do not fill in by guessing).
+- `## Safety / Invariants` — The constraints to uphold. **The canonical source of packet-specific invariants** (never write them into the compass; the compass holds only project-universal invariants).
+- `## Validation` — How to verify (**plan**). Tests, manual check, log check, type checking, etc.
+- `## Evidence` — What was verified (**result**). Place it right after `Validation` (plan) and before `Rollback`. Each entry can include "the verified result, the date performed, the corresponding check-axis ID (the stable kebab-case ID in `validate-checks.md`), and the source (intent-validate / drift-watch / human confirmation)".
+- `## Rollback` — How to revert on failure.
+- `## Out of scope` — **Optional (recommended)**. State what is not done (non-goals) to prevent over-implementation. If unfilled, the section may be omitted.
+- `## Verification protocol` — **Optional (recommended)**. Holds the tests to write first, the existing tests to protect, and the tests for additional failure modes to add. Downstream trace links (realized-by / verified-by) may also be held here optionally. If unfilled, the section may be omitted.
+- `## cc-sdd Mapping` — How to convert this packet into cc-sdd's requirements / design / tasks.
+
+### `## Decisions` (separating human-fixed from agent-discretion)
+
+`## Decisions` is the section that holds decision slots under constraints, and it carries the following two zones internally (keep them distinguished).
+
+- **Human-fixed (finalized values / visible rules)**: visible design rules that a human fixed up front. Slots with the value domain `finalized value`. The agent does not overturn these rules.
+- **Agent-discretion zone (deferred / undetermined)**: the area where local exploration inside the rules is delegated to the agent. Slots with the value domain `undetermined (with reason)` (`undetermined (deferred)`) correspond to this. For `undetermined`, also note the reason, the caveat for downstream, and the revisit condition (Revisit when).
+
+```markdown
+## Decisions
+### Human-fixed (finalized values / visible rules)
+- `decision-authz` answered: the only actor allowed to execute is the admin role
+### Agent-discretion (deferred / with revisit condition)
+- `decision-idempotency` undetermined: the retry approach is at implementation discretion. Revisit when: it becomes an externally exposed API
+```
+
+- The canonical source of the slot value domain, status, firing conditions, and slot IDs is `decision-slots.md`. This section is its projection; do not redefine the value domain or IDs here.
+- For a slot whose close-site is an existing section (`## Validation` / `## Expected Behavior` etc.), do not duplicate the value here; place only a reference noting "closed in the existing section" (no duplicate definition).
+- If no slots are seeded, **keep an empty section** (do not fill in by guessing); do not omit the section itself.
+
+### Section grading (required / optional)
+
+- **Required**: only `## Decisions` (the container that closes the common-core slots). Keep it as an empty section even when no slots are seeded.
+- **Optional (recommended)**: `## Out of scope` / `## Verification protocol` and the downstream trace links (realized-by / verified-by). If unfilled, the section **may be omitted** (maintaining the lightweight philosophy that avoids packet bloat and decision fatigue).
+- The frontmatter stays **fixed at 12 keys** and is not changed. The addition of these sections is **body sections only** and does not grow the frontmatter (trace links are also held in the body, not as new frontmatter keys).
+
+### Distinguishing `## Validation` (plan) and `## Evidence` (result)
+
+`Validation` is "how it is intended to be verified (plan)", and `Evidence` is "the actual result of verification (reality)"; the two are **not mixed**.
+
+```markdown
+## Evidence
+- 2026-06-15 — `unit: auth-session expiry test` green / `invariant-conflict` not applicable
+  - Check axes: invariant-conflict, l3-intent-mismatch
+  - Source: intent-validate (human confirmation: NN)
+```
+
+- Each entry can include the verified result, the date performed, the check-axis ID (kebab-case), and the source.
+- If there is no result, **keep an empty section** and do not fill in unfilled entries by guessing.
+- Evidence is recorded based on check results (intent-validate / drift-watch) or human confirmation rather than AI self-report, in a form whose source can be traced.
+- **`state=done` presupposes that Evidence has finalized verification results** (done with empty Evidence is a contradictory state).
+
+### Non-code degrade of the validation vocabulary (optional; canonical)
+
+The validation vocabulary in `## Validation` / `## Rollback` is written assuming code deliverables. When packing non-code deliverables (documents, business, research) with packets, you may apply the following read-throughs (this is an **optional degrade**, and this is the **canonical** definition of the read-through vocabulary — the non-code mode refers to this definition).
+
+- `testable` → "decidable by review viewpoints / acceptance criteria"
+- `rollback` → "version control / revert"
+- `behavior-preserving` → "do not break the meaning / agreements of existing deliverables"
+- (6) standalone completeness (termination judgment), "the user / caller" → "the reader / recipient" (for non-code deliverables, it means the packet's completed form is a coherent boundary that is not half-baked as seen by the reader / recipient)
+
+- This degrade is **optional** and does not make the code-assuming vocabulary mandatory (code deliverables keep using the original vocabulary).
+- Applying the degrade does **not skip the packets step**. Non-code work still goes through packets and retains the decision-slot seeding (C3) in `## Decisions` (it only re-reads the vocabulary; it does not bypass packets).
+
+## index.md regeneration procedure
+
+`.intent/packets/index.md` is a generated artifact and must not be hand-edited. A skill that changed the canonical (anything under packets/) regenerates it at the end of its run by the following procedure.
+
+1. Read **only the frontmatter** of every packet file under `active/` (do not read the bodies — deterministic).
+2. Build the `| packet_id | name | state | summary |` table in **ascending** `packet_id` order (`depends_on` is not emitted as an index column — for determinism and to avoid table bloat; the read-only side reads `depends_on` directly from the `active/` frontmatter).
+3. If `active/` is empty (or absent), the canonical form is the table with the header only.
+
+## Read-only consumer contract
+
+Read-only skills such as intent-status / intent-overview **only read** the following interfaces defined by this canonical source, and do not modify the packet canonical.
+
+- **`state` (5-value domain)**: `draft | ready | implementing | verifying | done`. Used to judge the stage of progress.
+- **`depends_on` (list of packet_ids)**: blocked status is derived read-only as "there is a packet in `depends_on` that is not `done` = blocked". The derived result is not written back to the packet. It does not auto-launch the next step or auto-determine ordering based on dependencies.
+- **`## Evidence` section**: verified results, date performed, check-axis ID, source. Material for the "degree of finalization of evidence" in progress.
+
+**Backward-compatible reading discipline (do not fill in by guessing)**:
+- Absent `depends_on` → read as "no dependencies (empty set)".
+- Absent/empty `## Evidence` → make it explicit as "unfilled / unobserved" and do not complete it.
+- Old `state: active` → read as "in progress (equivalent to `implementing`)".
+- When a new field or new section is unfilled or absent, make that location explicit as "unfilled / unobserved".

package/templates/en/claude/skills/intent-packets/rules/walking-skeleton.md

@@ -0,0 +1,35 @@
+# Walking Skeleton Check
+
+The procedure for confirming whether the top-priority packet spans the primary user journey end to end (i.e., is a walking skeleton). Used at the priority presentation (Step 4) of `/intent-packets`, only when designer-questions in `.intent/mode.md` is `on`. All dialogue is conducted as confirmation with the user (the means of confirmation follows the SKILL.md conventions).
+
+## Applicability
+
+- Read `designer-questions` in `.intent/mode.md`. Apply this procedure to the Step 4 priority presentation only when it is `on`.
+- **When designer-questions is not recorded as on (off or unrecorded), do not apply this procedure and do not change the existing Step 4 behavior** (notification for the unrecorded case follows the `.intent/mode.md` conventions).
+- **Do not reference purpose.**
+
+## Procedure
+
+1. **E2E verdict**
+   - Read the top-priority packet's Scope and Expected Behavior, and judge whether it spans the primary user journey end to end (input → processing → observable output).
+   - Ground the verdict in the packet's descriptions. A packet that stops at an intermediate layer (processing only, UI only, etc.) is judged "does not span".
+
+2. **Present the verdict and rationale, and confirm**
+   - Present the verdict (spans end-to-end / does not span) and its rationale to the user, and confirm.
+   - State the rationale in plain language: describe what this packet (the unit of work handed to cc-sdd) builds and what runs end to end after completion, so the rationale is readable without knowing the field names.
+
+3. **Propose remedies (when judged "does not span")**
+   - Propose how to make the first packet a walking skeleton, in one of the following forms:
+     - **Reordering proposal**: reorder the priorities so that a packet spanning E2E comes first.
+     - **Merge proposal**: merge the Scopes of multiple packets to create a packet that spans E2E.
+   - If the user intentionally defers the walking-skeleton conversion, accept that as a choice (do not silently drop it — record it; see step 4).
+
+4. **Record the confirmation result**
+   - Record in the "Walking Skeleton" section of `.intent/packets/plan.md`: **Top-priority packet** (packet name) / **E2E verdict** (spans end-to-end / does not span) / **Confirmation result** (what the user confirmed).
+   - For an intentional deferral, also record it together with the reason under the Deferred section.
+   - **Non-destructive append for older scaffolds**: if `plan.md` lacks a "Walking Skeleton" section, append the section while preserving the existing recorded content, then record.
+
+## Discipline
+
+- The confirmation result is referenced by intent-validate. Do not omit the record.
+- Do not change code.

package/templates/en/claude/skills/intent-release-note/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: intent-release-note
+description: An outward projection skill that reads the git commit history read-only, text-matches each commit against intent (packet name / parent intent / deltas / milestones) to thicken the "why it changed," and derives a release note under `.intent/release-note/` in a format (changelog-style / github-releases-style). It never modifies git or the canonical intent (read-only). Unmatched commits are kept as thin lines, surfacing the gap between intent and reality.
+allowed-tools: Read, Glob, Grep, Bash, Write
+argument-hint: <git range / format> (default range = latest tag..HEAD; `<from>..<to>` may be given; if no format is given, the default (changelog) is used and the output states which format was generated)
+---
+
+# intent-release-note Skill
+
+## Core Mission
+- **Success Criteria**:
+  - Read the git log of the given range (default = latest tag..HEAD; `<from>..<to>` may be given via argument, with fallback) **read-only** (no commit / tag creation / push).
+  - **Text-match** each commit against intent (packet name / parent intent / deltas / milestones) and, for matched ones, attach the "why (for which intent it changed)."
+  - List unmatched commits as thin changelog lines, **surfacing the gap between intent and reality** (do not silently drop them).
+  - Derive output under `.intent/release-note/` following a format (select `rules/format-changelog.md` / `rules/format-github-releases.md` by argument) by full replacement.
+  - Change neither the canonical intent (intent-tree / compass / packets) nor the git state (INV16 / INV17).
+
+## Execution Steps
+
+### Step 1: Range interpretation (fix the range)
+- When the user runs `/intent-release-note`, first interpret the range argument per `rules/source-scope.md`.
+- The default (no range given) is **latest tag..HEAD** (find the latest tag with `git describe --tags --abbrev=0` and use `<tag>..HEAD`). If `<from>..<to>` is given, use it.
+- If there is no latest tag and the default cannot be resolved, **fall back** to the full history and note this in the output (Fail-Soft). An invalid range argument is an explicit error and does not generate a release note.
+- Once the range is fixed, proceed to Step 2 (the range is uniquely determined by argument + default + fallback, not dependent on interactive completion).
+
+### Step 2: Read-only reading of the git log
+- Per the **read-only allowlist** in `rules/source-scope.md`, read the commits of the fixed range read-only.
+- Only read-only `git log` / `git tag` (listing) / `git describe` / `git rev-list` / `git rev-parse` / `git show` may be used.
+- **Never invoke writing operations** (`git commit` / `git tag <name>` creation / `git push` / `git checkout` / `git switch` / `git reset` / `git restore` / `git merge` / `git rebase` / `git cherry-pick`, etc.) (INV16).
+- Read each commit's hash, subject, body, author, and date as material.
+
+### Step 3: Text-matching commits against intent (propose candidates, do not assert)
+- **Text-match** each commit against intent. The priority of matching material is (1) packet name → (2) parent intent → (3) deltas → (4) milestones. Match the contents under `.intent/` (`packets/` / `intent-tree.md` / `intent-compass.md` / `deltas.md` / `milestones.md`) and the commit messages, **within what is mechanically observable from files**.
+- For a commit that text-matches any of them, attach the "why (for which intent it changed)." When multiple apply, take the highest-priority material.
+- Matching follows the same temperature as the existing `intent-status`: **carry no machine scoring, threshold, or new discriminator** (AD23), and when confidence is low, **propose as a candidate rather than asserting** (unmatched is the norm; tolerate false detections).
+- Commits that match none are **kept as thin changelog lines** (do not silently drop them; AD22).
+
+### Step 4: Format mapping (state the format if default)
+- Fix the format per `rules/format-select.md`. With argument `changelog` / `github-releases`, or the default (changelog) if unspecified, and **state in the output which format was generated**.
+- Hand the chosen format's output-structure rule (`rules/format-changelog.md` or `rules/format-github-releases.md`) the matched material from Step 3 (matched commits with their "why" + unmatched commits as thin lines) and assemble it.
+- Do not hardcode the target format into the body (delegate to rules; AD24). The output structure itself is the format-* rule's responsibility; this SKILL owns git reading, matching, and delegation.
+
+### Step 5: Derived Write (full replacement into `.intent/release-note/`)
+- Write the assembled release note to `.intent/release-note/release-note.md` by **full replacement** (derived, regenerable).
+- Confine the write destination to under `.intent/release-note/`. Change neither the canonical intent (intent-tree / compass / packets) nor the git state (INV16 / INV17).
+- When the target range contains no commits, state in the output that it is empty and change neither the canonical files nor git.
+
+## Output Description
+- At the top of the output, show the target range (with a note if it fell back) and the format (stating it if the default was used).
+- The body follows the chosen format's output structure (changelog-style = per-kind categories / github-releases-style = narrative + change list) (the layout of `rules/format-*.md`).
+- List intent-matched commits with a "why" and unmatched commits as thin lines, so that the gap is readable.
+
+## Safety & Fallback
+- **Read-only ownership boundary**: git is only read (only the Step 2 allowlist). Do not commit / create tags / push / change the working tree or refs (INV16).
+- **Derived-output ownership boundary**: writes go only under `.intent/release-note/`. Do not rewrite the canonical intent (INV17).
+- **Matching ownership boundary**: text-matching only (no machine scoring; AD23). Do not drop the gap (keep thin lines; AD22).
+- **Format ownership boundary**: delegate the output structure to `rules/format-*.md` and do not hardcode it into the body (AD24). Do not change the format-* output structure (fixed at the seam).
+- **Error cases**: no tag → fallback + note. invalid range → explicit error, do not generate. empty range → state empty. In all cases, change neither git nor the canonical files.

package/templates/en/claude/skills/intent-release-note/rules/format-changelog.md

@@ -0,0 +1,40 @@
+# Format Mapping: Changelog-Style (Keep a Changelog layout)
+
+The output structure used by the `intent-release-note` skill (added in a later packet) to assemble the git commit history and the intent-matching result into a **Keep a Changelog-style release note**. SKILL.md owns the procedure (reading git, matching intent); "which material goes under which heading and in what order" is defined by this rule.
+
+## Responsibility boundary (a structure definition, not reading or matching)
+
+- This rule is a **format mapping (output structure definition)**. It only defines the section layout, categorization, and ordering of the release note.
+- Procedures such as reading the git log, matching commits to intent (packet name / parent intent / deltas), and interpreting the range are **SKILL.md's responsibility**; this rule does not perform them (in this seam SKILL.md is not yet present; this rule is placed ahead as a container).
+- The **judgment** of attaching a "why (for which intent)" to matched commits and leaving unmatched commits as thin lines (surfacing the gap) belongs to SKILL.md. This rule only defines **which structure that result is poured into**.
+- That the output goes to a derived directory (`.intent/release-note/`, git-untracked, read-only) and never rewrites the canonical intent or git is the skill's invariant; this rule provides only the structure under that premise.
+
+## Basic stance (classify changes and stack them chronologically)
+
+The changelog style is a layout that **sorts the changes of one release (or one range) by category**. The reader is assumed to want to quickly grasp "what was added, changed, fixed, and removed in this version." Therefore:
+
+- Under a version (or range) heading, distribute changes into category buckets by kind.
+- Each entry is by default a concise single line; for entries tied to intent, append a brief "why" (the wording is prepared by SKILL.md; this rule places it under the relevant Added/Changed category).
+- Do not invent changes absent from the material for the sake of layout (leave unmatched commits as thin lines).
+
+## Structure (top to bottom)
+
+| Order | Section | What goes here |
+|---|---|---|
+| 1 | Heading (version / range and date) | Identifies the target range (default: previous tag..HEAD) and the generation date |
+| 2 | Added | Commits that constitute new features / additions |
+| 3 | Changed | Commits that change or improve existing behavior |
+| 4 | Fixed | Commits that are bug fixes |
+| 5 | Removed | Commits that remove a feature or element |
+| 6 | Other (uncategorized / unmatched changes) | Commits that cannot be categorized above or are not tied to intent, kept as thin lines (surfacing the gap) |
+
+- Categories (2–5) follow the standard Keep a Changelog categories. Omit any category heading that has no matching commits (do not create empty headings).
+- Section 6 is the bucket that keeps unmatched / uncategorizable commits as a thin single line **without silently dropping them**. Omit it if there is no material.
+- The "why" note on each entry is the matching result SKILL.md attached; place it as-is within the relevant category (this rule does not re-match).
+
+## Invariants
+
+- Do not re-read or modify git or the canonical intent (reading and matching belong to SKILL.md; writes belong to SKILL.md's Write into the derived directory).
+- Do not break the structure that classifies changes into per-kind categories (the core of the changelog-style layout).
+- Place both the "why" of intent-matched commits and the thin lines of unmatched commits without dropping either (do not erase the gap).
+- Do not add changes or background absent from the material for the sake of layout.

package/templates/en/claude/skills/intent-release-note/rules/format-github-releases.md

@@ -0,0 +1,41 @@
+# Format Mapping: GitHub-Releases-Style (GitHub Releases layout)
+
+The output structure used by the `intent-release-note` skill (added in a later packet) to assemble the git commit history and the intent-matching result into a **GitHub Releases-style release note**. SKILL.md owns the procedure (reading git, matching intent); "which material goes under which heading and in what order" is defined by this rule.
+
+## Responsibility boundary (a structure definition, not reading or matching)
+
+- This rule is a **format mapping (output structure definition)**. It only defines the section layout, how highlights are surfaced, and the ordering of the release note.
+- Procedures such as reading the git log, matching commits to intent (packet name / parent intent / deltas), and interpreting the range are **SKILL.md's responsibility**; this rule does not perform them (in this seam SKILL.md is not yet present; this rule is placed ahead as a container).
+- The **judgment** of attaching a "why (for which intent)" to matched commits and leaving unmatched commits as thin lines (surfacing the gap) belongs to SKILL.md. This rule only defines **which structure that result is poured into**.
+- That the output goes to a derived directory (`.intent/release-note/`, git-untracked, read-only) and never rewrites the canonical intent or git is the skill's invariant; this rule provides only the structure under that premise.
+
+## Basic stance (the release story on top, details below)
+
+The GitHub-releases style is a layout that **reads one release top-to-bottom as a narrative**. The reader is assumed to first grasp "what is good about this release (highlights)" and then descend into the change list if needed. Therefore:
+
+- Put the release title and a short summary (the gist of this release) at the very top.
+- Surface a few noteworthy changes as "Highlights" first, together with the intent-tied "why."
+- Place the exhaustive change list after the highlights (as skippable detail).
+- Do not invent outcomes absent from the material for the sake of layout (leave unmatched commits as thin lines in the change list).
+
+## Structure (top to bottom)
+
+| Order | Section | What goes here |
+|---|---|---|
+| 1 | Release title | A title identifying the target range (default: previous tag..HEAD) (tag name, version, etc.) |
+| 2 | Summary (the gist of this release) | A short summary of what this release as a whole achieved |
+| 3 | Highlights | A few noteworthy changes, surfaced first with the intent-tied "why" |
+| 4 | What's Changed | An exhaustive list of changes in the range; intent-tied ones carry a "why," unmatched ones are thin lines (surfacing the gap) |
+| 5 | Contributors (if any) | Contributors within the range, only when the material (git author) is available |
+
+- Sections 1–4 are the base structure. Do not reorder them (the title → summary → highlights → change list "narrative" order is the core of the GitHub-releases-style layout).
+- For sections 3 (Highlights) and 4 (What's Changed), place what SKILL.md judged "noteworthy" during matching into Highlights and the rest into the change list (this rule does not re-match).
+- In section 4, keep unmatched commits as a thin single line **without silently dropping them**.
+- Omit section 5 if the material (git author) is unavailable (do not create empty headings).
+
+## Invariants
+
+- Do not re-read or modify git or the canonical intent (reading and matching belong to SKILL.md; writes belong to SKILL.md's Write into the derived directory).
+- Do not break the title → summary → highlights → change list "narrative" order (the core of the GitHub-releases-style layout).
+- Place both the "why" of intent-matched commits and the thin lines of unmatched commits without dropping either (do not erase the gap).
+- Do not add outcomes or background absent from the material for the sake of layout.

package/templates/en/claude/skills/intent-release-note/rules/format-select.md

@@ -0,0 +1,32 @@
+# Format Selection (interpret the format argument, delegation rule)
+
+The source of truth by which the `intent-release-note` skill interprets the user-specified format argument and delegates to the corresponding output-structure rule. SKILL.md owns only the procedure and reporting format; "which format argument delegates to which output-structure rule" is defined by this rule. This rule carries **only the delegation rule** and does not carry the output structure itself (sections, categories, ordering); that is the responsibility of `format-changelog.md` / `format-github-releases.md` and is not duplicated here (AD24).
+
+## Posture (do not hardcode format in the body; delegate to rules)
+
+Do not hardcode the target format into the SKILL.md body. The format choice is interpreted in this rule, and the assembly of the chosen output structure is delegated to the corresponding format rule. To add a format, add an output-structure rule and a single row to this rule's delegation table.
+
+## Interpreting and delegating the format argument
+
+Interpret and delegate the format argument the user gave to `/intent-release-note` as follows.
+
+| Format argument | Delegate to (output-structure rule) | Layout |
+|---|---|---|
+| `changelog` (or a synonymous specification) | `rules/format-changelog.md` | Keep a Changelog style (per-kind categories) |
+| `github-releases` (or a synonymous specification) | `rules/format-github-releases.md` | GitHub Releases style (narrative + change list) |
+| Unspecified (default) | `rules/format-changelog.md` (default format) | Use the default and **state in the output which format was generated** |
+
+- If the format argument uniquely determines the format, perform no interactive completion (do not depend on prompting the user back; uniquely determine via the default).
+- The default format (when unspecified) is `changelog`; at the top of the output, state which format was used, e.g. "format = changelog (default)."
+
+## Responsibility split after delegation
+
+- This rule: determine which format to use and hand the corresponding format rule the "material" (the matched commit set = matched commits with their "why" + unmatched commits as thin lines).
+- Delegate (format-* rule): pour the received material into that format's output structure (sections, categories, ordering). Do not read git or match (that is SKILL.md's responsibility).
+
+## Invariants
+
+- Do not write the output structure (sections, categories, ordering) in this rule (that is the format-* responsibility; no duplication).
+- Do not hardcode the target format into the SKILL.md body (select and delegate in this rule; AD24).
+- When the default format is used, always state in the output which format was generated.
+- Do not bring custom machine scoring or thresholds into format selection (only the plain interpretation of the argument and the default).

package/templates/en/claude/skills/intent-release-note/rules/source-scope.md

@@ -0,0 +1,42 @@
+# Source Scope Interpretation (git range interpretation, read-only)
+
+The source of truth by which the `intent-release-note` skill interprets the user-specified range (git range) and reads the commits in that range read-only. SKILL.md owns only the procedure and reporting format; "how to interpret the range and which read-only git commands to read with" is defined by this rule. This rule only **reads** the git history; it never modifies the git state (commit / tag / branch / working tree) or the canonical `.intent/*.md` (writes go only under `.intent/release-note/`, and that is SKILL.md's responsibility).
+
+## Posture (no custom parser; read git and interpret)
+
+Range interpretation and commit reading carry no custom parser, schema, or index; they read the output of read-only git commands directly. No new structure is introduced; git's commit messages, tags, and dates are treated as material as-is.
+
+## Range interpretation (argument + default + fallback)
+
+Starting from the range argument the user gave to `/intent-release-note`, the target range is interpreted as follows.
+
+| Input | What it means | Resolution |
+|---|---|---|
+| No range given | Use the default range | **latest tag..HEAD** (from the latest reachable tag to HEAD). Find the latest tag with `git describe --tags --abbrev=0` and target `<tag>..HEAD` |
+| `<from>..<to>` given | Use the explicit range | Target the given `<from>..<to>` as-is |
+
+- If the argument uniquely determines the range, perform no interactive completion (do not add unnecessary questions; do not depend on prompting the user back, and uniquely determine via default + fallback).
+
+## Error cases (Fail-Soft and explicit error)
+
+| Situation | Behavior |
+|---|---|
+| No latest tag exists and the default range cannot be resolved | **Fallback**: target the full history (first commit..HEAD) and note in the output that "the full history was targeted because there is no tag" (Fail-Soft). If a range is given, fall back to that range |
+| The given range argument is invalid (uninterpretable) | **Explicit error**: report that the range cannot be interpreted and do not generate a release note (do not output with a wrong range) |
+| The target range contains no commits | State in the output that it is empty and change neither the canonical files nor git |
+
+## Read-only git command allowlist (writes strictly forbidden)
+
+Use **only the following read-only commands** to resolve the range and read commits.
+
+- Allowed (read-only usage only): `git log` / `git tag` (listing only; creating usages such as `-a` / `-m` are not allowed) / `git describe` / `git rev-list` / `git rev-parse` / `git show`.
+- **Forbidden (never invoke)**: `git commit` / `git tag <name>` (creation) / `git push` / any writing fetch / `git checkout` / `git switch` / `git reset` / `git restore` / `git merge` / `git rebase` / `git cherry-pick` / any other operation that changes the working tree, refs, or remote.
+
+Do not change the git state (INV16). This rule only resolves the range and hands the material to read to SKILL.md; it does not perform matching, format mapping, or the destination Write.
+
+## Invariants
+
+- Only re-reads git, never modifies it (read-only; writes are SKILL.md's responsibility into `.intent/release-note/`).
+- Do not break the interpretation rules for the default range (latest tag..HEAD), the argument range, fallback, and the invalid-range error.
+- Do not add commands outside the read-only allowlist (do not introduce writing operations).
+- Do not bring custom machine scoring or thresholds into range interpretation (matching is the responsibility of SKILL.md's Step 3; this rule does range resolution only).