intent-planner 0.13.1

package/templates/en/claude/skills/intent-to-spec/rules/source-scope.md

@@ -0,0 +1,50 @@
+# source scope interpretation procedure (read-only, three-layer reading)
+
+The canonical procedure by which the `intent-to-spec` skill interprets the range specified by the user (source scope) and reads the three layers of that range (Intent / steering constraints / requirements) as source material. SKILL.md holds only the procedure and reporting format; "which range to interpret how, and what to read from which heading" is defined by this rule. This rule only **reads** the projection source; it never modifies the canonical `.intent/*.md`, packets, or steering (tech.md etc.) (writes go only under `.intent/nl-spec/`, and that is outside this rule's responsibility).
+
+## posture (hold no custom parser; read and interpret `.intent/` directly)
+
+Range interpretation and three-layer reading are performed by the LLM reading the `.intent/` artifacts directly, holding no custom parser, schema, or index. Introduce no new structure; treat the existing artifacts' headings, columns, and frontmatter as source material as they are. Do not reimplement the recovery / check / drift judgment logic; if they have left output, only read it.
+
+## Range interpretation (arguments + dialogue completion)
+
+Starting from the arguments the user passed to `/intent-to-spec`, interpret the range along the following four axes. For any axis the arguments do not uniquely determine, ask the user, wait for a reply, and only then confirm (do not fill by guessing).
+
+| Axis | What to interpret | Default (when unspecified) |
+|---|---|---|
+| Intent subtree | which level / which branch of intent-tree to use as source (from where in L0–L4 down) | If the range is not unique, ask. Do not generate while ambiguous |
+| packet group | which packets to use as source (enumeration of packet names / "all" / narrowing by state) | If the range is not unique, ask |
+| steering constraints | whether to include steering-level constraints (tech.md etc.) as source | Do not include. Include only when explicitly specified (e.g. "+steering") |
+| crossing requirements | which range of individual requirements crossing multiple packets to bundle | Follow the packet-group specification above |
+
+- If the arguments uniquely fix the range, do not perform dialogue completion (do not add unnecessary questions).
+- When the arguments cannot uniquely fix the range, ask the user only about the axes that cannot be fixed, wait for a reply, and then proceed to reading.
+
+## Three-layer reading (exact references, fixed)
+
+For the confirmed range, read the following three layers across, and bundle them as source material for a single document. Each artifact's headings, columns, and frontmatter are fixed in the table below (if they change, this rule must follow = Revalidation Trigger).
+
+| Layer | File to read | Exact heading / column (fixed) | Treatment as source material |
+|---|---|---|---|
+| Intent (why / invariants / decision criteria) | `.intent/intent-tree.md` | `## L0`–`## L4` (the hierarchy body) plus `## Assumptions` (plus `## Open Questions` if present) | Read L0–L4 of the specified subtree as canonical why. Treat Assumptions / Open Questions as inferred, in a separate slot |
+| Intent (direction and constraints) | `.intent/intent-compass.md` | `## North Star` / `## Anti-direction` / `## Invariants` / `## Decision Rules` | Read North Star as purpose, Invariants as invariants, Decision Rules as decision criteria, Anti-direction as the direction to avoid |
+| steering constraints (only when specified) | steering (`tech.md` etc.) | the headings of each steering document | Only when there is a specification to include them in the range, read them as constraints to uphold. If unspecified, do not read |
+| requirements (individual requirements) | `.intent/packets/index.md` plus `.intent/packets/active/*.md` | index columns `packet_id \| name \| state \| summary` plus packet body frontmatter (including `depends_on`) and the body `## Evidence` | Read the individual requirements, dependencies, and evidence of the specified packet group, and bundle them as crossing requirements |
+
+- Keep canonical descriptions (the tree's L0–L4 / the compass's 4 sections / packets / steering) and inferred-derived descriptions (Assumptions / Open Questions) distinguished from the reading stage on, and do not mix them.
+- Do not read artifacts outside the range (use only the `.intent/` artifacts of the specified range as source material).
+
+## When the range is ambiguous / the relevant artifact is absent (do not generate)
+
+In any of the following cases, do **not** generate the natural-language Spec. Without generating, present the information by which the user can choose the next move, and stop.
+
+- **Range is ambiguous** (no axis is uniquely fixed by arguments or dialogue): name what is ambiguous (which axis), present the **available range** (the actually-existing intent-tree subtrees / the packet list / the presence of steering), and prompt for re-specification of the range.
+- **Relevant artifact is absent** (the specified intent-tree / compass / packet / steering does not exist, or is unfilled): name the **missing artifact**, and guide to the relevant skill that prepares it (discover / compass / packets etc.). Do not substitute by guessing.
+
+In either case, do not write.
+
+## Reading boundary (read-only)
+
+- Treat the projection source (intent-tree / compass / packets / steering) as **read-only**; do not create, modify, or delete it.
+- This rule's responsibility ends at "range interpretation" and "three-layer reading"; mapping the read material into the document is the responsibility of the format rules, and trace attribution / inferred marking is the responsibility of the fabrication-guard rule.
+- Pass the read material on while preserving which layer, which heading, and which packet it came from, so that the subsequent mapping can trace back to the projection source.

package/templates/en/claude/skills/intent-validate/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: intent-validate
+description: Read-only verification that cross-checks intent-tree, intent-compass, and packets (+ the export draft) and reports contradictions, coverage gaps, boundary inconsistencies, and normative violations with severity. Fixes remain proposals.
+allowed-tools: Read, Glob, Grep
+argument-hint: none
+---
+
+# intent-validate Skill
+
+## Core Mission
+- **Success Criteria**:
+  - intent-tree, intent-compass, and packets (+ the export draft) are cross-checked, applying all checks in the check catalog (the set of checks, their categories, and their severities are authoritatively defined by the table in `rules/validate-checks.md`)
+  - Findings are classified by severity (must-fix / recommended / info), and every item carries its check ID (the ID column of the table in `rules/validate-checks.md`), its evidence (file and the relevant statement), and a fix proposal (the skill to re-run or the fix direction)
+  - Unverified targets (missing / unfilled deliverables, plus the IDs of skipped checks) are stated explicitly together with the reason
+  - Packets are read statically from the four PBR perspectives (user / operations / test / maintenance), confirming read-only whether each perspective's breakdown conditions are documented
+  - No file has been created, changed, or deleted at all (read-only, one-way reporting)
+
+## Execution Steps
+
+### Step 1: Confirm the prerequisites
+- If `.intent/` is absent, guide the user through the intent-planner setup steps (running `npx intent-planner`) and finish.
+- Partial absence of `intent-tree.md` / `intent-compass.md` / `.intent/packets/` is **non-blocking**: do not stop; run the checks within the verifiable scope and report the missing deliverables as unverified targets (packets count as missing when `.intent/packets/` is absent or `active/` is empty; in that case skip the packet-dependent checks).
+
+### Step 2: Read the deliverables
+- Read `.intent/intent-tree.md`, `.intent/intent-compass.md`, `.intent/packets/index.md` and `.intent/packets/plan.md`, and the packet files subject to the checks (for cross-packet checks, read all files under `active/`; do not read `archive/`), plus `.intent/cc-sdd/<slug>/*.md` (the per-packet export drafts, if present) and `.intent/mode.local.md` (falling back to `.intent/mode.md` if absent) for the mode state.
+- If both mode.local.md and mode.md are absent, continue with the standard default and announce it (do not stop).
+
+### Step 3: Apply the check catalog
+- Read `rules/validate-checks.md` and apply all checks in the check catalog (the set of checks, their categories, and their severities are authoritatively defined by the table in `rules/validate-checks.md`).
+- Severity classification (including the must-fix / recommended decision for the L3 mismatch) follows the criteria in the rules.
+- The target of the boundary checks is the directory of the packet on the latest row of `.intent/export-log.md` (identification is authoritatively the exact match of the `## Source Packet` heading in the directory's requirements.md). Drafts of past packets coexist by design and are not treated as violations. If export-log is absent or uninterpretable, fall back to the drafts' Source Packet headings (when multiple directories exist, present them as candidates without asserting one) and report that fact.
+
+### Step 3.5: Statically confirm the four PBR perspectives (read-only; search for breakdown conditions)
+- Read the packets (under `active/`, plus the export drafts if present) from the four perspectives below, and statically confirm **whether each perspective's breakdown conditions are documented**. If the documentation is missing, list it as a finding for that perspective in the severity-grouped list (perform no automatic fix or interactive confirmation).
+- **User perspective**: whether the breakdown conditions of the behavior for the user (inputs / situations under which the expected behavior collapses) are documented.
+- **Operations perspective**: whether a fail-safe design (behaviors such as degradation, rejection, retry) against faults, timeouts, and malicious input is documented.
+- **Test perspective**: whether test cases based on equivalence partitioning and boundary-value analysis can be created. If they cannot, report it as a missing boundary condition.
+- **Maintenance perspective**: whether the packet holds How internally (fixing a ceiling) and thereby obstructs the free design of the implementing agent.
+- For every perspective, do not stop at confirming the happy path; actively search for "the conditions under which this design breaks down (abnormal cases, high load, invalid input)" (confirmation-bias mitigation). When no breakdown condition is found, treat it as "the breakdown-condition documentation is missing" rather than "unexplored".
+- This per-perspective confirmation is a static check item; introduce no new interaction loop, state machine, or interactive-confirmation tool. If an interactive per-perspective audit is needed, note in Open Questions / fix proposals that it is delegated to the existing reviewer subagent practice (`kiro-review`, etc.).
+
+### Step 3.6: Name suspected coinages (`coinage-suspect`; read-only; semantic)
+- **Read the mother-set**: read `.intent/glossary.md` (the lightweight canonical-vocabulary ledger) read-only, taking the "Canonical term" column and its "Aliases & synonyms" as the mother-set. If `.intent/glossary.md` is **absent, treat the mother-set as empty and do not fire this detection at all** (the existing validate output is unchanged; backward-compatible).
+- **Judge (semantic, not a mechanical check)**: among the terms appearing in the intent artifacts (intent-tree / intent-compass / packets, plus the export drafts if present), name as a "suspected coinage" any term found **nowhere** in the mother-set (canonical terms, aliases, synonyms). Judge by a semantic reading (including grasping synonyms / spelling variants in the LLM context), not by a mechanical regex match. Do not push this onto `scripts/intent-check.mjs` in any way.
+- **Exclusions**: do not name the following as suspected coinages.
+  - Proper nouns (product names, personal names, organization names, etc.).
+  - Established English technical terms.
+  - **Legitimate new terms that already carry a first-mention one-line explanation per the terminology convention** (do not double-flag what the terminology convention already governs).
+- **Tone**: stay a candidate suggestion and never assert (false-positive-tolerant). Raise it as a "this might be a coinage" candidate and do not take the judgment away from the user. When in doubt, do not raise it.
+- **Silence**: when there is not a single suspected coinage, **do not fire any coinage-detection output at all** (do not force anything to be treated as a coinage).
+- **Attach a rewrite suggestion (presentation only)**: when naming a suspected coinage, attach **the glossary ledger's canonical term(s) the coinage could fold into as a "fix proposal"** (enumerate candidates if several; e.g., "`<coinage>` is a candidate to fold into the glossary's `<canonical term>`"). Like the naming itself, stay a candidate and never assert. When no fitting target is found in the glossary, do not assert a target; instead suggest "consider adding a canonical term to the ledger". The rewrite suggestion rides on the coinage naming: when detection is silent, emit no rewrite suggestion either.
+- **The rewrite is presentation only and rewrites nothing**: keep the rewrite / consolidation suggestion to a read-only report, and **do not automatically rewrite** the canonical artifacts (intent-tree / intent-compass / packets) or the glossary ledger. This skill only names the suggestion; it does not edit files. Any actual adoption is a **separate action** taken only after a human approves it (this feature stops at presentation; INV20).
+- **No gate**: a suspected coinage is an info-severity one-way report; it never stops export or implementation.
+
+### Step 4: Report (one-way; fixes are proposals only)
+- Present the findings as a list grouped by severity (must-fix / recommended / info), citing for every finding its check ID (the ID column of the table in `rules/validate-checks.md`) together with the severity (e.g., `must-fix invariant-conflict: …`).
+- Always attach to every item its "evidence (file and the relevant statement)" and a "fix proposal (the skill to re-run or the fix direction)".
+- State the unverified targets and their reasons explicitly, identifying skipped checks by their IDs.
+- Present the remaining Open Questions.
+- Perform no automatic fixes at all.
+
+## Output Description
+
+**Reader**: a human developer who looks at the findings and decides whether to remediate.
+**What this output makes them grasp first**: "**N must-fix / M recommended**. These are what to fix, and this is the command to re-run." The enumeration of check IDs / unverified targets is detail for the decision, so place it after the counts and the must-fix items.
+
+Lead the output with the conclusion (the counts and the must-fix items).
+
+- **Verdict summary (top, one line)**: `N must-fix / M recommended / K info`. If there are 0 must-fix, state explicitly "no critical issues".
+- **Must-fix list (next)**: each item with its check ID + evidence (file and the relevant statement) + fix proposal (the skill to re-run or the fix direction). The chunk the reader should tackle first.
+- **Details**: the recommended / info-level findings (same format), the unverified targets (including the IDs of skipped checks) and their reasons, and the Open Questions that the human should review.
+- Include the command to run next in the fix proposals (e.g., re-running `/intent-compass`).
+- For a `coinage-suspect` finding, attach in the fix-proposal area a **rewrite / consolidation suggestion toward the canonical term** (the target canonical term, or — when no fitting target exists — a note to consider adding a canonical term to the ledger). Presentation only, with no automatic rewrite; adoption is a separate action taken only after a human approves it.
+
+## Safety & Fallback
+- Read-only: create, change, or delete no file whatsoever. Keep fixes as proposals, always attaching the skill to re-run or the fix direction.
+- Only the absence of `.intent/` is a stop condition: guide the user through the setup steps and finish.
+- Partial absence of deliverables is non-blocking: check only the verifiable scope and state the unverified targets and reasons explicitly.
+- The absence of mode.md does not stop; continue with the standard default and announce it.
+- Do not change application code (INV6. Being read-only, the skill has no write path in the first place).

package/templates/en/claude/skills/intent-validate/rules/validate-checks.md

@@ -0,0 +1,121 @@
+# Check Catalog: intent-validate
+
+The canonical source of the checks that the `intent-validate` skill applies. SKILL.md carries only the procedure and the report format; the definition of the checks references this file. To add a check, just add a row to this table (the table is the source of truth). The ID of each check is its stable identifier and is cited alongside the severity in each reported finding (this table is also the source of truth for the list and count of IDs).
+
+## The 3 severity classes
+
+| Severity | Definition |
+|----------|------------|
+| must-fix | A contradiction or consistency break that should be resolved before starting work. Proceeding to export / implementation as-is becomes a cause of architectural drift |
+| recommended | A quality risk. Not severe enough to stop work immediately, but resolving it raises the deliverables' reliability as a basis for judgment |
+| info | A heads-up. Action is optional, but the state should be known |
+
+### Demotion rule
+
+- If an intentional, reasoned deferral record (Deferred or Open Questions) exists for a missing item, report that item's severity lowered to "info".
+
+## Check catalog
+
+| ID | Category | Check | Condition | Severity guideline |
+|----|----------|-------|-----------|--------------------|
+| invariant-conflict | Contradiction | A packet's Scope/Expected Behavior conflicts with the compass Invariants | always | must-fix |
+| anti-direction-violation | Contradiction | A packet's direction falls under the compass Anti-direction | always | must-fix |
+| l3-intent-mismatch | Contradiction | Mismatch between the intent-tree L3 intent and the packet content (direct contradiction with an explicit L3 statement = must-fix; divergence open to interpretation = recommended) | always | must-fix/recommended |
+| goal-without-packet | Coverage | A goal among the tree's L1–L3 goals that corresponds to no packet (including L4) | always | recommended |
+| orphan-packet | Coverage | An orphan packet whose Parent Intent traces back to no node of the tree | always | must-fix |
+| stale-questions | Coverage | Stagnation of unresolved Questions in tree/compass/packets | always | info |
+| stale-assumptions | Coverage | Items remaining in the intent-tree Assumptions that have been neither promoted to canonical nor rejected | always | info |
+| dependency-cycle | Consistency | `depends_on` contains a cyclic dependency A→…→A | always | must-fix |
+| dependency-broken-ref | Consistency | `depends_on` references a packet_id that does not exist | always | must-fix |
+| invariant-uninherited | Consistency | A compass universal invariant is not inherited into the packet `## Safety / Invariants` (silent omission, not a conflict) | always (compass Invariants filled and an active packet exists) | recommended |
+| invariant-stale-vs-compass | Consistency | A compass section update date (Invariants section / Decision Rules section) is newer than the packet `updated_at` (a follow-up-lag candidate) | always (compass section update date and packet update date present) | recommended |
+| decision-rule-mismatch | Consistency | The packet `## Decisions` violates the compass Decision Rules | always (compass Decision Rules filled and the packet has a `## Decisions` section) | must-fix/recommended |
+| decision-rule-code-alignment | Consistency | Grep-read the code module (file name / module name) named by a Decision Rule's main statement / Context, and detect a semantic divergence between the Rule's main statement and the implementation via the AI's limited semantic matching. Matching surface = the meaning of the code implementation (separated from `decision-rule-mismatch`, whose surface = packet slot values). Output carries an "AI semantic-matching estimate" label and is a one-directional report that never asserts | always (a Decision Rule names a code module and the named target exists) | recommended |
+| packet-scope-overlap | Boundary | Scope overlap / responsibility conflict between the packet files under active/ (archive/ is not read) | always | must-fix |
+| decision-slot-empty | Completeness floor | Among the decision slots (④) sown in the packet's `## Decisions` section, those whose value is empty (unfilled). A reasoned `undetermined` is demoted to info by the demotion rule | a packet that has slots sown in its `## Decisions` section | recommended |
+| decision-slot-unsown | Completeness floor | The `## Decisions` section exists but not a single common-core slot (none of the 8 common-core IDs of `decision-slots.md`) has been sown | a packet that has a `## Decisions` section (an old packet with no section at all is skipped as an unverified target) | recommended |
+| export-draft-mismatch | Boundary | Consistency between the current export draft (the directory of the packet on the latest export-log row) and the target packet file (under active/) (mismatched transcription of Invariants, divergence from the packet definition, etc.) | always | recommended |
+| requirements-smell | Quality | A requirement statement still contains vague words, subjective words, comparatives, weak words, or undefined pronouns (e.g., "appropriately", "fast", "better", "etc.", "as much as possible", an "it" with no clear referent). Detect, quote, and leave the judgment to the user (do not write the rewording back to the source) | always | recommended |
+| ambiguous-deferred-phrasing | Quality | In the packet's `## Decisions` section, an unsettled verb (assume/assumed, reuse/divert, planned/TBD, tentative, etc.) that sits outside the Human-fixed / Agent-discretion partition and carries no accompanying Revisit when, hidden in finalized-sounding phrasing. Detect, quote, and leave the judgment to the user (do not write the rewording back to the source) | always (the packet has a `## Decisions` section) | info |
+| trace-downstream-missing | Coverage | A packet exists for a tree L1–L3 intent, yet that packet has no downstream link (`verified-by` / verification) so it cannot be traced to verification (the verification side of downward coverage). The packet's own absence is owned by `goal-without-packet`, so do not duplicate it | always | recommended |
+| trace-pre-rs-missing | Coverage | The packet frontmatter lacks the upstream link `parent_intents` key, or it is empty (the cut point of intent→requirement pre-RS). An orphan whose `parent_intents` is present but traces back to no node of the tree is owned by `orphan-packet`, so do not duplicate it | always | recommended |
+| poc-experiment-missing | Normative | Any of hypothesis / falsification criteria / GO-NO-GO criteria is unrecorded in "PoC Experiment Definition" | designer-questions=on and purpose=poc | must-fix |
+| l1-metric-missing | Normative | An L1 item lacks a `Measurement criteria:` line | designer-questions=on | recommended |
+| walking-skeleton-missing | Normative | The "Walking Skeleton" section of plan.md is unfilled (when plan.md is filled in) | designer-questions=on | recommended |
+| screen-sketch-missing | Normative | The "Screen Rough Reference" section is unfilled (none of a path, a link, "Not applicable", or a reasoned "none" is present) | designer-questions=on | recommended |
+| designer-questions-unrecorded | Normative | designer-questions is unrecorded (skip the checks in the Normative category and announce only this row) | designer-questions unrecorded | info |
+| purpose-unrecorded | Normative | purpose is unrecorded (skip the hypothesis / falsification criteria / GO-NO-GO check and announce only this row) | designer-questions=on and purpose unrecorded | info |
+| coinage-suspect | Quality | Against the mother-set `.intent/glossary.md` (the lightweight canonical-vocabulary ledger), name in a read-only manner any term found nowhere in the ledger as a "suspected coinage". The judgement is semantic (excluding proper nouns, established English terms, and legitimate new terms already given a first-mention one-line explanation), not pushed onto the mechanical check. It stays a candidate suggestion that never asserts, and stays silent when there is no suspected coinage | always (`.intent/glossary.md` present) | info |
+
+- The condition "always" does not override the principle of unverified targets (if the target deliverable is missing or unfilled, skip that check).
+- The designer-questions / purpose in the conditions refer to the values recorded in mode.md. Do not run a check whose condition is not met. When designer-questions=off is recorded, run none of the checks in the Normative category. The reader judges designer-questions first and does not consult the purpose value unless on is recorded.
+
+## Note on the completeness-floor checks (no inference; declaration-based)
+
+- `decision-slot-empty` / `decision-slot-unsown` carry the "completeness floor" (the cutoff line). They prevent ④ decisions-under-constraints (consistency, idempotency, error semantics, authorization, etc.) from advancing to export/implementation while blank. The canonical source for the slots is `intent-packets/rules/decision-slots.md` (it owns the categories, firing conditions, and value domain).
+- **Do not infer applicability from packet content**: these checks target only the slots **actually sown** in the `## Decisions` section. They do not make inferential judgments like "this packet must involve writes, so it needs a slot" (which slot to sow is the responsibility of a human confirming it in discover's elicitation; the same discipline as not inferring `depends_on`).
+- An old packet with no `## Decisions` section at all is skipped as an unverified target (no forced immediate bulk migration; the next update flow lazily completes the slots).
+- A reasoned `undetermined` is demoted to "info" for `decision-slot-empty` by the demotion rule (deferral is allowed as an intentional postponement; the completeness floor is "prohibition of blanks", not "forcing immediate finalization of every item").
+
+## Note on the dependency-soundness checks (read-only and the reference-resolution scope)
+
+- `dependency-cycle` / `dependency-broken-ref` are **read-only** and do not modify the packet source of truth (frontmatter, etc.) at all.
+- The existence check for the referenced packet_id in `dependency-broken-ref` is performed against the **full set of active+archive packet_ids** (an archived packet_id is also considered to "exist").
+
+## Note on the smells / trace checks (read-only, minimally sufficient, no write-back)
+
+- `requirements-smell` **only detects and quotes** vague words, subjective words, comparatives, weak words, and undefined pronouns; it does not write reworded suggestions back to the source. Its severity is "recommended" (not enough to stop work, but resolving it raises reliability as a basis for judgment).
+- The trace checks (`trace-downstream-missing` / `trace-pre-rs-missing`) are **read-only** and do not write derived links or filled-in gaps back to the source (the same discipline as not inferring / auto-computing `depends_on`).
+- Keep traces **minimally sufficient**: do not connect every artifact pairwise; flag only the gaps that break being able to trace "why it exists (upstream `parent_intents`), where it was realized (`realized-by`), and how it was verified (`verified-by`)". Downstream links are optional (when filled in, check whether verification can be traced).
+- Boundary with the existing coverage checks: the packet's own absence is owned by `goal-without-packet`, and an orphan whose `parent_intents` is present but cannot be traced back to the tree is owned by `orphan-packet`. `trace-downstream-missing` focuses on the side where a packet exists but cannot be traced to verification, and `trace-pre-rs-missing` on the cut point where the `parent_intents` key itself is missing or empty, so no duplicate check is created.
+
+## Note on the unsettled-verb check (read-only, strict demotion rule, no write-back)
+
+- `ambiguous-deferred-phrasing` only detects and quotes an unsettled verb (a placeholder hidden in finalized-sounding phrasing) that sits **outside the Human-fixed / Agent-discretion partition** of the packet `## Decisions` section and carries **no accompanying Revisit when**; it does not write reworded or finalized suggestions back to the source (the same read-only pattern as `requirements-smell`). Its severity is **"info"** (do not promote it to must-fix, because the false-positive rate is high).
+- **The finalized vocabulary of unsettled verbs** (limit to this list and do not overlap with the `requirements-smell` vocabulary [appropriately / fast / better / etc. / as much as possible / a bare "it", and so on]):
+  - assume / assumed, reuse / divert, planned / TBD, tentative.
+- **Excluding nominal-idiom false positives (required)**: even for the words above, do not flag nominal or adverbial idioms that do not signal unsettled intent. Concretely, exclude word forms used with a settled connotation such as "as expected" / "as assumed", and **limit detection to verbal usages that signal an unsettled action or intent** such as "assumed to do ~" / "to reuse / divert ~". When in doubt, do not flag it, and do not take the judgment away from the user.
+- **Strict application of the demotion rule**: when a detected spot is already recorded as a deferral under Deferred / Open Questions / a reasoned undetermined slot (reason + accompanying Revisit when), suppress that finding by the demotion rule (do not re-list an unsettled item already recorded as a structural deferral). By default its severity is already "info", and it is never promoted to must-fix or recommended.
+- Separation from existing axes: this axis looks at unsettled verbs (phrasing match) that sit outside the partition and have no Revisit when, while an empty slot itself is owned by `decision-slot-empty` and a contradiction with the compass Decision Rules is owned by `decision-rule-mismatch`. No duplicate check is created.
+
+## Note on the decision-vs-code divergence check (the sole inference exception in the read-only check layer, with boundary conditions)
+
+- `decision-rule-code-alignment` Grep-reads a code module and detects a **semantic divergence between the Rule's main statement and the implementation via the AI's limited semantic matching**, **only when a Decision Rule's main statement / Context names a code module (file name / module name)**.
+- **This is the sole inference exception in the read-only check layer.** All other check axes (including the existing three [`invariant-uninherited` / `invariant-stale-vs-compass` / `decision-rule-mismatch`], `ambiguous-deferred-phrasing`, and the status / improve axes) do not infer. **Only this axis is the exception, and the exception does not spread to other axes** (the other axes keep the prior discipline of reading only the presence of a statement and the presence of a direct contradiction).
+- **Boundary conditions (compensating for the reduced reproducibility of false positives; required)**:
+  - The output always carries the explicit label **"AI semantic-matching estimate"** and does not assert.
+  - The severity stops at **recommended**. It is never promoted to must-fix.
+  - It stays a **one-directional report that prompts human confirmation** rather than the user's primary basis (it auto-fixes neither the canonical nor the code).
+  - **Limited to a naming origin**: do not flag it when a Decision Rule names no module, the Rule is abstract, or no divergence can be observed ("which module to look at" originates from the Rule's naming, and the semantic matching is limited to "after the target to look at is fixed"). When in doubt, do not flag it, and do not take the judgment away from the user.
+- **Separation of matching surfaces (required; avoids duplicate detection)**: the matching surface of this axis is **the meaning of the code implementation**. Because this differs from the existing `decision-rule-mismatch`, whose surface is a text match against the packet `## Decisions` slot values (no inference), even when both axes apply to the same Decision Rule it is not a duplicate detection (the former = code implementation vs. Rule, this axis = packet slot value vs. Rule).
+- **Tool invariance (required)**: the intent-validate allowed-tools remain `Read, Glob, Grep` (do not add Write / Bash). Code is only Grep-read and never modified at all (INV6). The AI semantic matching is a judgment in the skill body, not a tool.
+
+## Criteria for classifying the L3 mismatch
+
+- Packet content that **directly contradicts an explicit statement** of the intent-tree L3 = **must-fix**
+- **Divergence open to interpretation** (no explicit statement, but the direction looks off, etc.) = **recommended**
+- When in doubt, lean toward recommended, attach a quotation of the evidence, and leave the judgment to the user
+
+## Note on the compass-conformance checks (matching inheritance, staleness, and ADR divergence)
+
+- Separation of concerns:
+  - `invariant-uninherited` ≠ `invariant-conflict`: the latter detects a "conflict = contradiction", this axis detects a "silent omission". Both may apply to the same packet, but the detection viewpoint differs.
+  - `decision-rule-mismatch` ≠ `l3-intent-mismatch`: the latter matches against the intent-tree L3, this axis matches against the compass Decision Rules.
+- Classification criteria (`decision-rule-mismatch`, reusing the `l3-intent-mismatch` template): a direct contradiction with an explicit Decision Rules statement = must-fix; a divergence open to interpretation = recommended; when in doubt, lean toward recommended, attach a quotation of the evidence, and leave the judgment to the user.
+- **Limiting the matching surface (required)**: an ADR (the 6-field long form: Context/Decision/Why/Alternatives/Consequences/Revisit when) and the packet `## Decisions` (slot value domain) are structurally asymmetric, so limit the matching surface to **"the `Decision` of a Decision Rules entry (the main statement of the option taken)" vs. "the finalized value of each slot in the packet `## Decisions`"**. Use the surrounding fields (Why/Alternatives/Consequences, etc.) as the source of evidence quotations, but not as the main axis of the contradiction judgment.
+  - Matching examples: Decision Rules `Decision` = "place aggregation logic in the domain layer", the corresponding packet `## Decisions` slot finalized value = "aggregate in the UI" → direct contradiction = must-fix. `Decision` = "prefer rollback-capable slices" while the packet leans toward bulk replacement but with no explicit negation → open to interpretation = recommended.
+- **Separation of axis roles (required)**: only `invariant-stale-vs-compass` carries a time axis (update-date comparison). `invariant-uninherited` (presence of inheritance) and `decision-rule-mismatch` (presence of contradiction with the ADR) are "current state" axes and are not linked to the compass section update dates. These two axes read the compass's current invariants / Decision Rules every time and flag them individually (the value of these axes is to surface "which invariant is missing in which packet").
+- **Output granularity**: only the time-axis `invariant-stale-vs-compass` defaults to a **one-line count summary** (e.g., `N packets not following up after the Invariants section update / M after the Decision Rules section update`), expanding the individual packet list only on user request (to avoid crying wolf). Present it as recommended, not asserted as must-fix. The stale comparison targets only pairs where **both the relevant compass section update date and the packet `updated_at` are actually stamped (not `—`)**. `invariant-uninherited` / `decision-rule-mismatch` default to individual findings.
+- No inference (required): do not infer applicability from packet content (the same discipline as the `decision-slot` checks). Keep the semantic matching to reading the presence of a statement and the presence of a direct contradiction.
+- Backward compatibility: when compass `Updated (...)` is `—` / absent, the packet `updated_at` is absent, the `## Decisions` section is absent, or Invariants is unfilled, **skip that check, stating it as an unverified target with its ID** and do not assert staleness.
+
+## Note on the boundary checks (target selection for the export drafts)
+
+- The export drafts (`.intent/cc-sdd/<slug>/*.md`) **coexist per packet**. The target of the export-draft-consistency boundary check is limited to the directory of the packet on the latest row of `.intent/export-log.md`. Drafts of past packets coexist by design, so their existence itself is not treated as a violation.
+
+## Handling of unverified targets (the verifiable-scope principle)
+
+1. If a deliverable subject to verification is missing or unfilled, skip the checks that require that deliverable.
+2. Run the remaining checks within the verifiable scope (do not abort the whole run).
+3. Include "unverified targets" in the report, stating the skipped checks and the reason (which file is missing / unfilled).
+4. Example: `.intent/packets/` is absent (or active/ is empty) → skip the packet-dependent checks across contradiction/coverage/boundary, and run only the checks possible with the tree/compass alone (e.g., stagnation of unresolved Questions).

package/templates/en/claude/skills/intent-writeback/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: intent-writeback
+description: After implementing an exported packet, record the learnings gained from the implementation into deltas.md as a delta, and promote only the approved items into the canonical deliverables (intent-tree / intent-compass / packets). Never edits the canonical deliverables directly.
+disable-model-invocation: true
+allowed-tools: Read, Write, Glob, Grep, AskUserQuestion, Bash
+argument-hint: <target packet name (optional)>
+---
+
+# intent-writeback Skill
+
+## Core Mission
+- **Success Criteria**:
+  - The target packet is identified as exactly one via the 4-tier priority (argument → latest row of export-log → Source Packet heading → text matching + confirmation)
+  - Learnings from the 5 perspectives are extracted and presented by cross-checking the implementation reality against the packet definition and the compass
+  - The learnings are first recorded into deltas.md as a delta, and the canonical deliverables are not edited directly
+  - Only the approved items are reflected into the canonical deliverables, with Status and reflection targets recorded in the delta
+  - Declined items carry one of the two tags "rejected (no re-proposal) | on-hold (re-propose at the next writeback)"
+  - The completed packet has state: done, closed_at, and spec_refs filled in, has been moved to archive/<year>/, and index.md has been regenerated
+  - No application code has been changed at all
+
+## Execution Steps
+
+### Step 1: Identify the target packet
+- Read `rules/writeback-protocol.md` and identify exactly one target via the 4-tier priority (1. argument → 2. packet name in the latest row of export-log.md (canonical) → 3. "## Source Packet" heading in the drafts (only when exactly one packet directory exists) → 4. text matching + user confirmation). When a fallback (tier 3 or later) identified the target, announce that fact; if the target still cannot be identified, ask for a specification and stop (see rules).
+- Identify the target packet's file by matching `name` in index.md / under `active/` of `.intent/packets/`. If it is not under `active/`, refer to `archive/` explicitly to identify it and report the fact that the packet is done / superseded (the only explicit exception to the principle of normally never reading archive/; see rules).
+- Read `.intent/mode.md`. If absent, continue with the standard default and announce it.
+- Present the list of past delta entries of the target packet (including declined items with the "on-hold" tag). Writing back the same packet again creates a new entry (see rules).
+
+### Step 2: Extract and present the learnings
+- Cross-check the implementation reality (the codebase, tests, and `.kiro/specs/`; all read-only) against the packet definition (the target packet file), the cc-sdd drafts, and intent-compass.md.
+- Extract learnings via the 5 perspectives of the rules ([decision] / [invariant-violation] / [implicit-behavior] / [deferred-resolved] / [question]) and present them as a tagged list.
+
+### Step 3: Record the delta (canonical untouched)
+- Record the extracted learnings into `.intent/deltas.md` as a new entry (Status: pending).
+- If deltas.md is absent, create it anew from the canonical template embedded in the rules (never overwrite an existing file).
+- At this stage, do not edit the canonical deliverables (intent-tree.md / intent-compass.md / the files under `.intent/packets/`) at all.
+
+### Step 4: Confirm promotion (vary the approval granularity)
+- Vary the approval granularity by the kind of learning (rules §3 Stage 2). Do not ask about every item uniformly, one at a time.
+- **Gated items** (`[invariant-violation]` and `[decision]` that changes Decision Rules) are confirmed item by item.
+- **Everything else** (L3-append kind and `[question]` transcription) is presented as a list of reflection targets; ask whether there is any item to hold back, and promote in bulk if none is named.
+- For items held back (not approved), confirm one of "rejected (no re-proposal) | on-hold (re-propose at the next writeback)".
+
+### Step 5: Promote the approved items and finalize the records
+- Reflect only the approved items into the canonical deliverables. A promotion that changes Decision Rules adds a new entry in the ADR form (Context / Decision / Why / Consequences) + a superseded note on the old entry + the evacuation of the old entry, with its 6 fields intact, into compass-archive/<rule-slug>.md (a per-rule file; CONTRACT split & archive convention; see rules).
+- Transcribe [question] learnings into the Open Questions of intent-tree.md and record the transcription target as the reflection target.
+- Record the Status (promoted / closed), the reflection targets, and the two-valued tags of declined items in the delta entry. The final tag updates from re-proposal results of on-hold items (promote / confirm rejection / keep on hold) are also done here.
+
+### Step 6: Complete the packet
+- When the writeback completes, perform the packet's completion as one sequence of operations (see rules): (1) fill in `state: done`, `closed_at`, and `spec_refs` (cross-checked against the specs in progress under `.kiro/specs/` and finalized with user confirmation) in the frontmatter → (2) move the file to `archive/<year of closed_at>/` → (3) regenerate index.md from the frontmatter under `active/`.
+
+## Output Description
+
+**Reader**: a human developer who promotes implementation learnings into intent and closes the packet.
+**What this output makes them grasp first**: "**this is what was promoted to canonical / this is what was deferred**. The target packet became done and moved to archive." The process of extracting learnings and recording deltas is detail leading up to the promotion result.
+
+Lead the output with the conclusion (the promotion result and the completion processing).
+
+- **Promotion result (top)**: what was promoted to canonical (intent-tree / intent-compass / packets), with reflection-target details. Show the deferred items distinguished by their declined tag "rejected (no re-proposal) / on-hold (re-propose next time)".
+- **Completion processing result (next)**: the target packet's `state: done` / `closed_at` / `spec_refs` entries, the move to `archive/<year>/`, and the index.md regeneration. Phrased so it is clear that "this packet is now closed".
+- **Promotion proposals** (if shown at the stage that asks for approval): gated items (invariant violations / Decision Rules changes) confirmed item by item; the L3-append kind presented as a list + naming the items to hold back.
+- **Details**: the list of extracted learnings (tagged with the 5 perspectives [decision]/[invariant-violation]/[implicit-behavior]/[deferred-resolved]/[question]) and the delta recording result (the entry in deltas.md).
+
+## Safety & Fallback
+- If the target packet cannot be identified, present the situation, ask the user to specify the write-back target, and stop.
+- Never delete packet files (move to archive only). Bash usage is limited to getting the date/time and directory creation (mkdir) and moves to archive under `.intent/packets/` (the invariant of not changing application code stays).
+- If deltas.md is absent, create it anew from the template embedded in the rules (never overwrite an existing file).
+- Never rewrite the canonical deliverables without approval. If nothing is approved, keep the entry pending and finish.
+- `.kiro/specs/` and the codebase are read-only. Never write into `.kiro/`.
+- The absence of mode.md does not stop; continue with the standard default and announce it.
+- Do not change application code (INV6).

package/templates/en/claude/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/codex/skills/CONTRACT.md

@@ -0,0 +1,77 @@
+# intent-* Skill Shared Contract
+
+The conventions that every `intent-*` skill follows. The scope is the whole set of skills whose names start with `intent-`, not an enumerated list (adding a skill does not require revising this contract; it applies as-is). They are aligned to the same skeleton as cc-sdd's `kiro-*` skills and coexist non-destructively.
+
+## frontmatter (required fields)
+
+```yaml
+---
+name: intent-<phase>            # Must start with intent-. Never collide with kiro-*
+description: <one-line summary>  # A description that makes clear when to use it
+---
+```
+
+- `name` is `intent-*`. The directory name must match it too. Never collide with `kiro-*`.
+- The frontmatter is limited to **`name` / `description` only** (the Codex minimal-frontmatter convention). Do not place `allowed-tools` / `argument-hint` / `disable-model-invocation`.
+  - Note: on the claude side too, `disable-model-invocation` is not uniform across all skills — it is a conditional field placed only on skills that rewrite canonical (canonical-writers) (see the claude CONTRACT). The Codex side, regardless of that condition and regardless of skill classification, places none of the three fields (the minimal-frontmatter convention).
+  - Tool limitations (restricting to planning-oriented tools, not changing application code, etc.) are expressed in the body and the "Shared constraints" below, not in the frontmatter.
+  - **Gemini CLI also shares this minimal-frontmatter tree.** Gemini CLI reads `.agents/skills/` as Agent Skills and injects `name` + `description` via progressive disclosure at startup, so the Codex minimal-frontmatter convention fits as-is. The gemini entry in `AGENT_REGISTRY` uses `skillSubdir: "codex"` (sharing the `.agents/skills` destination with Codex); no gemini-specific skill tree is created (verified by real-machine smoke that the shared tree is read — gemini-cli-support).
+
+## Body structure
+
+Align to the cc-sdd style.
+
+```
+# <skill-name> Skill
+
+## Core Mission
+- Success Criteria: ...
+
+## Execution Steps
+### Step 1: ...   (Read and apply rules/*.md as needed)
+### Step 2: ...
+
+## Output Description
+- The generated update proposal
+- Open Questions that the human should review
+- The command to run next
+
+## Safety & Fallback
+- Behavior on error / missing prerequisites
+```
+
+## Shared constraints
+
+- **Output is fundamentally a "proposed update"**. Writing to `.intent/` is allowed.
+- **Do not change application code** (INV6).
+  - The scope of INV6 is "do not change application code", not "do not invoke other skills". The two are distinct concepts. `intent-export-cc-sdd` invoking `/kiro-spec-init` and `intent-export-openspec` invoking `/opsx:propose` do not contradict INV6 (they touch no code).
+- **Respect the mode (read fallback contract)**: resolve mode state in the order **`mode.local.md` → otherwise old `mode.md` → otherwise the `standard` default** (backward-compatible fallback). Follow the mode definition in the definition file. When neither `mode.local.md` nor old `mode.md` is present, continue with `standard` as the default and add "mode undetermined; `/intent-discover` recommended" to the Open Questions (do not stop). Enforcement / Drift-watch (shared policy) are read from `mode.md` (not subject to this fallback contract).
+- **When a prior deliverable is missing**, do not fill the gap with guesses; guide the user to "run the corresponding command first" and stop (distinguish this from the absence of mode state).
+- **Confirm with the user in natural language**: present the recommendation, ask the user in natural language, and wait for their answer. Do not depend on a dedicated tool.
+- **Bash (shell execution) is not used as a rule. Strictly limited exception**: skills that run the staleness check (currently the gate checks in `intent-export-cc-sdd` / `intent-export-openspec` and the freshness warning in `intent-status`) may use Bash solely to launch the read-only script `node .intent/scripts/intent-check.mjs` and — for the export record of the export skills (`intent-export-cc-sdd` / `intent-export-openspec`) — to run the read-only `git rev-parse --short HEAD` (neither creates, modifies, nor deletes any files). No other Bash use is permitted to intent-* skills.
+- **Read-only skills** (currently `intent-status` / `intent-validate`) perform reading and reporting only: they do not write, and they do not run interactive confirmation with the user (natural-language reporting only). This is an intentional, permitted narrowing of the standard conventions. As an exception, under the Bash-limited exception above, `intent-status` may additionally use Bash solely to launch the read-only script `node .intent/scripts/intent-check.mjs` (the property of creating, modifying, and deleting no files is preserved). `intent-validate` carries no Bash.
+
+## Question and Terminology Conventions
+
+- **Self-contained questions**: every question or confirmation addressed to the user must be a self-contained sentence that can be answered without knowing the terminology. When a term is used, include a one-line explanation inside the question text itself (e.g., "Confirm with the user whether the first packet (unit of work) is a walking skeleton (a minimal implementation that runs end to end from input to output)").
+- **English terms + one-line explanations**: keep terms in English; do not replace them with translated coinages. When an explanation is needed, attach a one-line explanation that states the function or meaning (in parentheses or as a blockquote) at the first occurrence.
+- **Do not invent coined terms**: do not invent new coined terms that are absent from the canonical vocabulary (the ubiquitous language already in use across the intent deliverables); reuse an existing term. If you must introduce a new term, attach a one-line explanation at its first occurrence.
+
+## State sharing across skills
+
+- The shared state points are **`mode.local.md`** (mode state: mode / designer-questions / purpose; local-only, git-ignored) and **`mode.md`** (shared policy: Enforcement / Drift-watch; git-tracked) — two files (do not create hidden sharing). The read fallback contract is consolidated in "Respect the mode" above.
+- `.intent/deltas.md` is a **deliverable** just like the packet files under `.intent/packets/` (written by intent-writeback, read by intent-status / intent-improve); it is distinct from the mode-state sharing described above. It is not the introduction of new hidden sharing.
+
+### Split and archive convention for append-only records
+
+The append-only single-Markdown records under `.intent/` (deltas / export-log / drift-log / milestones / compass-archive and the like — records of the same shape, where writers append at the end and readers read the whole file) collide on a single anchor (the end of the file) under concurrent appends and grow unbounded. To resolve this structurally, append-only records take a physical form that follows the conventions below (this is the single source of truth for the convention).
+
+1. **Separate the active surface (the current projection) from history (archive)**. Keep the currently-referenced records thin on the active surface, and move terminal (no-longer-updated) entries off to archive.
+2. **The split key has two classifications**. Records stop appending to the end of a single file and are instead written to small files split by a non-colliding natural key. The classification is decided by the record's origin: **packet-origin = a file per packet** (e.g. `deltas/<packet-slug>.md`) / **event-origin = a file per date+slug** (e.g. `drift-log/<date>-<slug>.md`). Because a different packet / different event touches a different file, end-of-file collisions disappear in principle.
+3. **Do not use sequential numbering; use date+slug**. Do not use a central-counter sequence such as `0001` in file names (concurrent sessions cannot see each other's numbering and so cannot avoid collisions). Use date+slug instead.
+4. **Archive eviction follows the existing `archive/<year>/` structure**. Move terminal entries off to `archive/<year>/` (a per-year directory; the precedent that packets already have) under the record directory, keeping the active surface thin. Do not invent a new eviction naming scheme.
+5. **Do not use merge=union for records whose order is load-bearing**. `merge=union` (erasing conflict markers via gitattributes) silently breaks order, so do not use it for records where entry order carries meaning. Collisions are eliminated structurally by the split (convention 2).
+
+- **Naming of the split key references the existing packet slug rule and does not redefine a new numbering scheme**. The deterministic slug derivation (NFC normalization → trim → lowercase → dangerous characters to `-` → collapse consecutive `-` → strip leading/trailing `-` → preserve non-ASCII) and the date part (the drafting date) have their single source of truth in the slug rule of `intent-packets/rules/packet-format.md`; the split key need only reference it (do not bring in new numbering logic or a central counter).
+- The content of records (each record's entry format, fixed key order, etc.) is out of scope of this convention; split and archive govern placement only (content is kept behavior-preserving).
+- **Placement for the five record files (where convention 2 applies)**: apply the classification above to all five files. **packet-origin** = `deltas/<packet-slug>.md` / `export-log/<packet-slug>.md` (a file per packet). **event-origin** = `drift-log/<date>-<slug>.md` / `milestones/<date>-<event-slug>.md` (a file per date+slug). **compass-archive is per superseded Decision Rule (rule-unit)** = `compass-archive/<rule-slug>.md` (re-superseding the same rule goes to the same file). Until reader cross-following is complete, keep the old `export-log.md` as a generated active mirror (split files concatenated in `exported_at` order; derived, never hand-edited) alongside the split files, regenerated by the writer on every export.