intent-planner 0.13.1

package/templates/en/codex/skills/intent-to-spec/rules/format-nonprogram.md

@@ -0,0 +1,45 @@
+# format mapping: non-program target (documents, operations, research, etc.)
+
+The mapping rule by which the `intent-to-spec` skill assembles the three-layer material read by source-scope interpretation into a **non-program-target natural-language Spec** (a readable artifact for paths that use neither cc-sdd nor openspec — documents, business processes, research / decision-making). SKILL.md holds only the procedure and reporting format; "which material to place in what order, under which heading" is defined by this rule.
+
+## Responsibility boundary (this is a mapping, not reading or reconciliation)
+
+- This rule is a **format mapping**. It is responsible only for the composition, order, and heading assignment of the material. It does not re-read the projection source (intent-tree / compass / packets / steering) and holds no custom parser or schema; it merely rearranges the material handed over by source-scope interpretation (which preserves which layer, which heading, and which packet each piece came from).
+- Making each description traceable to the projection source, marking inferred material, and preserving invariants are the **responsibility of the fabrication-guard rule**; this rule does not do them. It receives canonical-derived and inferred-derived material kept distinguished and places them without collapsing that distinction.
+- This rule holds **no packing strategy (mode)**. Packing intent is the responsibility of `intent/modes/` (DR16); it must not be mixed into this rule, which is the output-layout container.
+
+## Basic posture (let the reader read the artifact in their own words)
+
+A non-program-target Spec is a layout that lets a reader who writes no code (the document's agreeing party, the operations owner, the research / decision stakeholders) read straight through **what is decided, why it is so, how to judge, and what must be satisfied**. It does not bring implementation vocabulary (APIs, modules, test cases, etc.) to the front; it presents the artifact in the words of the target domain. Therefore:
+
+- Show the background and purpose (the why) and the bar to reach (the what) at the head of the artifact, in the reader's words.
+- Place the promises to uphold and the basis for judgment (invariants, decision criteria) before the individual content.
+- State the acceptance basis (was it agreed, or sent back) in **words of agreement / acceptance**, not in code's testable vocabulary (the degrade vocabulary is re-read on the packets side; this rule places that already-re-read material as is).
+- Do not add background or detail absent from the material for fluency's sake (places that need completion are handled by the fabrication-guard rule as inferred; this rule must not dissolve them into the body).
+
+## Composition
+
+Place the three-layer material handed over by source-scope interpretation as a single generic artifact, in the following order (do not cover per-domain count / granularity here). Hand each section's material over with its origin preserved, so that the downstream fabrication-guard rule can trace which layer and which heading it came from.
+
+| Order | Section | What to place | Main material origin |
+|---|---|---|---|
+| 1 | Background and purpose | The direction this artifact heads toward and the problem it solves (in the reader's words) | Intent's North Star (compass) plus intent-tree's L0–L1 |
+| 2 | Promises / premises to uphold | Invariants that must not be deviated from, and the direction to avoid | compass's Invariants / Anti-direction (plus steering constraints only when specified) |
+| 3 | Basis for judgment | The basis for what to prioritize when uncertain | compass's Decision Rules |
+| 4 | Content (the individual bars to reach) | The individual requirements / agreements to satisfy under the above | crossing requirements (packets' individual requirements, dependencies, acceptance grounds) |
+| 5 | Acceptance basis | The acceptance vocabulary (already degraded) for judging whether it is agreed or sent back | packets' verification vocabulary (re-read for non-code: testable→judgeable by acceptance criteria, etc.) |
+| 6 | Premises / unsettled (if any) | Premises and open questions placed in a separate slot, **not mixed** with the confirmed material above | intent-tree's Assumptions / Open Questions (inferred-derived) |
+
+- Compose sections 1–5 from canonical-derived material. Do not reorder them (the order background & purpose → promises → basis for judgment → content → acceptance is the core of the non-program-target layout).
+- Place section 6's inferred-derived material (Assumptions / Open Questions) in a **separate slot at the end**, not dissolved into the canonical body. If there is no such material, omit the section entirely (do not create an empty heading).
+- Omit the section for any layer whose material is absent (do not fill in information that is not there). However, background and purpose (1) and promises / premises to uphold (2) are the crux of this layout; if their material has been read, always place them.
+- Even when steering has not been read (steering is opt-in), sections 1, 2, 4, and 5 can be composed from the Intent and packets two layers. Do not drop the artifact for the sole reason that steering is absent.
+
+## Invariants
+
+- Do not re-read or modify the projection source (mapping only; reading is the responsibility of source-scope interpretation, writing is the responsibility of SKILL.md's derived Write). Output is limited to derived artifacts under `.intent/nl-spec/`, and canonical material (intent-tree / compass / packets) is treated read-only.
+- Keep each description traceable to the projection source, and mark material absent from the projection source as inferred (leave the marking itself to the fabrication-guard rule; this rule only upholds placing them without collapsing the distinction).
+- Do not break the order that places background & purpose (why) and promises / decision criteria **before** the individual content.
+- Do not mix canonical-derived material with inferred-derived material (place them with the distinction preserved).
+- Do not add background, motivation, or detail absent from the material to smooth the prose.
+- Do not mix packing strategy (mode) into the output-layout (format) container (DR16: responsibility separation).

package/templates/en/codex/skills/intent-to-spec/rules/format-upstream.md

@@ -0,0 +1,41 @@
+# format mapping: upstream-facing (why up front)
+
+The mapping rule by which the `intent-to-spec` skill assembles the three-layer material read by source-scope interpretation into an **upstream-facing natural-language Spec** (an RFP / proposal-style layout where why leads). SKILL.md holds only the procedure and reporting format; "which material to place in what order, under which heading" is defined by this rule.
+
+## Responsibility boundary (this is a mapping, not reading or reconciliation)
+
+- This rule is a **format mapping**. It is responsible only for the composition, order, and heading assignment of the material.
+- It does **not re-read** the projection source (intent-tree / compass / packets / steering). It holds no custom parser or schema; it merely rearranges the material handed over by source-scope interpretation (which preserves which layer, which heading, and which packet each piece came from).
+- Making each description traceable back to the projection source, marking material absent from the projection source as inferred, and preserving invariants without omission or alteration are the **responsibility of the fabrication-guard rule**; this rule does not do them. This rule receives canonical-derived material and inferred-derived material (Assumptions / Open Questions) **kept distinguished**, and only upholds placing them without collapsing that distinction.
+- The intermediate format (between upstream and integrated) is treated as the "why up front" degree of this rule shifted toward the integrated side. It holds no separate, independent rule.
+
+## Basic posture (place why up front)
+
+An upstream-facing Spec is a layout that makes the reader read **why it is built (and what must be upheld) before what is built**. The assumed reader is not the implementer but someone judging direction and validity (an upstream decision-maker). Therefore:
+
+- Place purpose, invariants, and decision criteria (the why and constraints) at the **front** of the document.
+- Place implementation-near detail such as individual requirements and acceptance criteria **after** the why and constraints, as material supporting them.
+- Do not add background or motivation absent from the material for fluency's sake (places that need completion are handled by the fabrication-guard rule as inferred; this rule must not dissolve them into the body).
+
+## Composition (top to bottom: why → constraints → decision criteria → individual requirements)
+
+Place the three-layer material handed over by source-scope interpretation in the following order. Hand each section's material over with its origin preserved, so that the downstream fabrication-guard rule can trace which layer and which heading it came from.
+
+| Order | Section | What to place | Main material origin |
+|---|---|---|---|
+| 1 | Purpose (why it is built) | The direction this Spec heads toward and the problem it solves | Intent's North Star (compass) plus intent-tree's L0–L1 (the upper why) |
+| 2 | Invariants / constraints to uphold | Invariants that must not be deviated from, and the direction to avoid | compass's Invariants / Anti-direction (plus steering constraints only when specified) |
+| 3 | Decision criteria | The basis for judgment when design / implementation is uncertain | compass's Decision Rules |
+| 4 | Individual requirements | The individual requirements to satisfy under the above why and constraints | crossing requirements (packets' individual requirements, dependencies, evidence) |
+| 5 | Premises / unsettled (if any) | Premises and open questions placed in a separate slot, **not mixed** with the confirmed material above | intent-tree's Assumptions / Open Questions (inferred-derived) |
+
+- Compose sections 1–4 from canonical-derived material. Do not reorder them (the order why → constraints → decision criteria → individual requirements is the core of the upstream-facing layout).
+- Place section 5's inferred-derived material (Assumptions / Open Questions) in a **separate slot at the end**, not dissolved into the canonical body. If there is no such material, omit the section entirely (do not create an empty heading).
+- Omit the section for any layer whose material is absent (do not fill in information that is not there). However, purpose (1) and invariants / constraints (2) are the crux of the upstream-facing layout; if their material has been read, always place them.
+
+## Invariants
+
+- Do not re-read or modify the projection source (mapping only; reading is the responsibility of source-scope interpretation, writing is the responsibility of SKILL.md's derived Write).
+- Do not break the order that places why (purpose) and constraints (invariants, decision criteria) **before** individual requirements.
+- Do not mix canonical-derived material with inferred-derived material (place them with the distinction preserved, and leave the marking itself to the fabrication-guard rule).
+- Do not add background, motivation, or detail absent from the material to smooth the prose.

package/templates/en/codex/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/codex/skills/intent-validate/SKILL.md

@@ -0,0 +1,78 @@
+---
+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.
+---
+
+# 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/codex/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/codex/skills/intent-writeback/SKILL.md

@@ -0,0 +1,68 @@
+---
+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.
+---
+
+# 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).