intent-planner 0.13.1

package/templates/en/codex/skills/intent-from-spec/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: intent-from-spec
+description: Inward ingestion skill that reads a user-provided natural-language spec (PRD / design spec / feature spec / issue / user story) read-only, extracts unstated intent candidates, surfaces silence as gaps against the existing rulers, qualitatively prioritizes by load-bearing, and presents an omission recap. All extractions are Assumptions (hypotheses); output is limited to derived artifacts under `.intent/spec-ingest/` and never modifies any canonical artifact.
+---
+
+# intent-from-spec Skill
+
+## Core Mission
+- **Success Criteria**:
+  - Reads the user-provided natural-language spec (a general development spec text such as a PRD / design spec / feature spec / issue / user story) read-only, and extracts intent candidates for purpose, outcomes, capabilities, invariants, constraints, anti-direction, and implicit assumptions. Marks all extracted candidates as Assumptions (inferred intent) and never mixes them with canonical (confirmed intent) (R1.1 / R1.2)
+  - Does not use source code, execution traces, or test results as extraction input. Input is limited to the user-specified natural-language spec text (R1.4)
+  - Picks up the must-hold constraints contained in the spec (technical / security requirements) without dropping them, as Compass Invariants candidates, and limits their destination to Invariants (reflection into steering (tech.md) / design is delegated downstream. R1.5 / R1.6)
+  - When no spec text is provided as input, performs no extraction, asks the user for the spec to ingest, and stops (fail-fast. R1.3)
+  - Reads the existing rulers (the inspection catalog in `validate-checks.md` and the common-core slots in `decision-slots.md`) against the spec, and enumerates the unfilled items as gaps. Shows in an observable form which category / slot each gap is the silence of, and presents it as a hypothesis rather than a confirmed defect (R2.1 / R2.2 / R2.3)
+  - While presenting gaps, does not stop processing; limits itself to warnings / awareness (same stance as drift-watch. R2.4)
+  - Qualitatively sorts the extractions / gaps by load-bearing (whether their loss would damage the correctness of what follows), and presents high items distinctly from low. The judgment merely reads and copies the "front-load / defer door" column in `decision-slots.md`, and holds no mathematical solver, numeric score, or threshold (R3.1 / R3.2 / R3.3)
+  - Summarizes "what was checked (presenting the frames) and what was left unfilled" as an omission recap, prompting reconfirmation (R4.1)
+  - Treats only approved items as candidates to load onto the canonical Intent structure, and retains unapproved items as Assumptions without discarding them. Performs no auto-reflection into canonical; promotion is delegated to the user's manual copy (R4.2 / R4.3 / R4.4)
+  - Limits output to derived artifacts under `.intent/spec-ingest/`, and never modifies any canonical `.intent/*.md`, application code, or the input spec (read-only. R5.2). Follows the `intent-*` naming convention and does not modify external spec tools or the kiro-* development environment (R5.6)
+
+## Execution Steps
+
+### Step 1: Confirm the input (natural-language spec text) exists (fail-fast)
+- When the user runs `/intent-from-spec`, first confirm whether the natural-language spec text to ingest (a file path or pasted body) is provided.
+- If no spec text is provided, **write nothing**, state the absence of the input explicitly, ask the user in natural language to provide the spec to ingest (a path or pasted body), and stop (fail-fast. R1.3). Do not write anything under `.intent/spec-ingest/` at this point.
+- Do **not** use source code, execution traces, or test results as extraction input. Recovering intent from those is a separate path handled by behavior-unknown mode's code→Intent, outside this skill's scope (R1.4).
+- The ruler sources of truth (`intent-validate/rules/validate-checks.md` / `intent-packets/rules/decision-slots.md`) and the canonical `.intent/*.md` (intent-tree / compass / mode, if present) are referenced read-only in later steps. Do not stop if absent (state the absence for anything that cannot be linked).
+
+### Step 2: Delegate to the four rules to extract, check, sort, and recap
+- This skill has no extraction / checking / judgment / scoring logic of its own. The exact reading, transcription, and linking rules for each concern are delegated to the following four rules (referenced by relative path). Follow the exact headings, transcription destinations, and ID systems each rule specifies; mark all extracted candidates as Assumptions; only read the rulers without reimplementing them; and state gaps and unobserved areas explicitly without filling them in by guessing.
+- `rules/extract-intent.md` — reads the spec text and extracts intent candidates across the seven categories of purpose / outcomes / capabilities / invariants / constraints / anti-direction / implicit assumptions. Marks all candidates as Assumptions and writes each out with a heading and granularity whose transcription destination (intent-tree's L0–L4 Assumptions / compass's Invariants, Anti-direction, Decision Rules) is uniquely determined. Picks up the must-hold constraints such as technical / security requirements without dropping them, as compass Invariants candidates, and limits their destination to Invariants (reflection into tech.md / design is not included in the output = delegated downstream. R1.1 / R1.2 / R1.4 / R1.5 / R1.6 / R5.1).
+- `rules/gap-readout.md` — **reads** the stable kebab-case inspection IDs in `validate-checks.md` and the common-core 8 slot IDs in `decision-slots.md`, and enumerates the items unfilled against the input spec as gaps. Shows which ruler's silence each gap is (ID linking) and which category / slot's silence it is (observable evidence), and presents it as a hypothesis rather than a confirmed defect. Defines no new inspection IDs / slot IDs of its own. Since spec-ingest is a proposer, not an acceptance gate, it **may infer** slot applicability from the spec's silence **but does not confirm** (a different posture from validate). Does not stop processing; warnings only (R2.1 / R2.2 / R2.3 / R2.4).
+- `rules/load-bearing.md` — for the gaps / intent candidates that gap-readout linked to slot IDs, qualitatively sorts high/low by merely reading and copying the **"front-load / defer door" column** in `decision-slots.md`. "Front-load" = high (dangerous if it falls), "deferrable" = low. Holds no mathematical solver, numeric score, or threshold, and invents no new discriminating axis. Items that cannot be linked to a slot ID are stated as load-bearing-unknown (absence). Presents high distinctly observable from low, and retains low without discarding it (R3.1 / R3.2 / R3.3).
+- `rules/omission-recap.md` — summarizes as a list "the frames checked (what was read) / the filled areas / the unfilled areas (silence) / the areas that could not be checked (absence)", avoiding the "silence of silence" (the omission error where the AI hints at completeness and the human stops searching). Cites the existing IDs that gap-readout linked, without redefining them. Treats only approved items as candidates for canonical promotion, retains unapproved items as Assumptions, and guides that promotion is a manual copy in which the user carries approved items by hand into the discover / compass dialogue (no machine handoff. R4.1 / R4.2 / R4.3 / R4.4).
+
+### Step 3: Write the derived view to `.intent/spec-ingest/` last (full replacement, derived)
+- Only after all extraction, checking, sorting, and recap are complete, **last** write `.intent/spec-ingest/spec-ingest.md` by **full replacement** (idempotent regeneration). Never write to any canonical `.intent/*.md` (intent-tree / compass, etc.), steering (tech.md), design, or the input spec.
+- In the view header, declare that this view is derived / regenerable, not the source of truth, and Git-untracked, and that all intent candidates / gaps / load-bearing levels described are Assumptions (hypotheses) and remain provisional until the user's approval (R1.2).
+- Compose the output per extract-intent's transcription-destination headings, at a granularity the user can copy 1:1 into intent-tree's Assumptions / compass's blocks (keeping the promotion seam manual).
+
+## Output Description
+- `.intent/spec-ingest/spec-ingest.md` (derived, regenerable, Git-untracked; the view header declares it is not the source of truth and that all items are Assumptions). Its content includes:
+  - **Intent candidates (extraction)**: per extract-intent's output contract, presents purpose / outcomes / capabilities candidates (→ intent-tree L0–L4 Assumptions), Invariants candidates (→ compass Invariants, including technical / security constraints), Anti-direction candidates (→ compass Anti-direction), and implicit-assumption candidates (→ intent-tree Assumptions / compass Decision Rules), with headings whose transcription destination is uniquely determined. Each candidate carries its extraction basis (from which spec description / silence).
+  - **Gaps (silence)**: enumerates as hypotheses the gaps that gap-readout linked to IDs in `validate-checks.md` / `decision-slots.md`, together with which category / slot's silence each is.
+  - **Load-bearing sorting**: presents high items distinctly from low (e.g. grouping high at the top). Items that cannot be linked to a slot are stated as load-bearing-unknown.
+  - **Omission recap**: a list of the frames checked / filled areas / unfilled areas / areas that could not be checked, plus promotion guidance for the user to transcribe approved items by hand into discover / compass.
+- Categories / axes without source material are stated as "no relevant description (silence) / unobserved" and omitted (never filled in by guessing).
+
+## Safety & Fallback
+- **Write boundary**: writes are limited to under `.intent/spec-ingest/`. The canonical `.intent/*.md` (intent-tree / compass / mode, etc.), the ruler sources of truth (`validate-checks.md` / `decision-slots.md`), steering (tech.md), design, and the input spec are read-only — never created, modified, or deleted there (writes are confined to under `.intent/spec-ingest/`. R5.2).
+- **Gaps are hypotheses (warnings only — never stop)**: gaps, load-bearing levels, and intent candidates are all Assumptions (hypotheses), not confirmed defects / severities. While presenting them, never stop processing; limit to warnings / awareness (same stance as drift-watch. R2.3 / R2.4).
+- **Approval gate — promotion is manual**: reflection into canonical requires the user's explicit approval. Treat only approved items as candidates for canonical promotion, and retain unapproved items as Assumptions without discarding them. Perform no auto-reflection into canonical. Promotion is a manual copy in which the user carries approved items by hand into the discover / compass dialogue; spec-ingest does not call discover / compass, and discover / compass do not auto-read spec-ingest's output (no machine handoff = no hidden shared ownership. R4.2 / R4.3 / R4.4).
+- **Does not reimplement the rulers**: never runs inspections / slot verification of its own; only reads the ID catalogs in `validate-checks.md` / `decision-slots.md` and the "front-load / defer door" column. Holds no inspection IDs / slot IDs / scoring / weighting engine of its own.
+- **Zero external dependencies** (INV2 / R5.3). Introduces no external package, AST parser, or mathematical solver; limited to Node standard and natural-language heuristics, completing extraction within a natural-language workflow.
+- **Does not modify application code** (R5.2). In the intent-planning phase, modifies neither application code nor the input spec (read-only).
+- **Naming / no external modification**: follows the `intent-*` naming convention and does not modify external spec tools or the kiro-* development environment (R5.6).
+- **When prerequisites are absent**: when no input spec text exists, write nothing, state the absence, ask the user in natural language to provide the spec to ingest (a path or pasted body), and stop (fail-fast. R1.3).
+- **On partial gaps**: for any of the seven categories the spec is silent on, gaps that cannot be linked to the ruler catalogs, and items that cannot be linked to a slot and are load-bearing-unknown, state the area explicitly as "no relevant description (silence) / absent / unknown" and omit it (never fill in by guessing).

package/templates/en/codex/skills/intent-from-spec/rules/extract-intent.md

@@ -0,0 +1,56 @@
+# Intent Candidate Extraction Procedure (read-only; all candidates are Assumptions)
+
+The single source of truth by which the `intent-from-spec` skill reads the natural-language specification text the user provides (PRDs, design specs, feature specs, issues, user stories, and other general development specifications) and extracts candidates for intent that is not stated explicitly. SKILL.md holds only the procedure and report format; "what to read under which category, and toward which transcription destination to write it out" is governed by this rule. This rule only **reads** the specification; it does not modify the input specification, the canonical `.intent/*.md`, steering (tech.md, etc.), or the design at all (writes go only under `.intent/spec-ingest/`).
+
+## posture (a proposer, not an adjudicator)
+
+What this rule performs is **extraction (proposal)** by the heuristics of LLM judgment, not certification of confirmed intent. Every extracted candidate is a **hypothesis (Assumption)** and is treated as provisional until the user confirms and approves it. Processing does not stop; it stays at presenting warnings and observations (consistent with the product invariant that inferred intent is treated as provisional until a human reviews it). Therefore this rule **may infer** slot applicability from the specification's statements and silences, **but does not finalize** it.
+
+## Input boundary (fixed)
+
+- Input is **limited** to the natural-language specification text the user designates (path reference or paste).
+- **Source code, execution traces, and test results are not used as input for intent extraction.** Recovering intent from those is a separate path handled by the code→Intent of behavior-unknown mode, and is out of scope for this rule.
+- When no input is given, perform no extraction and ask the user for the specification to be supplied (write nothing).
+
+## Candidate categories to extract (7 kinds; all Assumptions)
+
+Read the specification text and extract candidates in the following 7 categories. For each candidate, attach the extraction basis (which statement or which silence in the specification it was derived from). **Mark every extracted candidate as an Assumption (inferred intent) and do not mix it with canonical (confirmed intent).**
+
+1. **Purpose** — what this product/feature exists for.
+2. **Desired Outcomes** — the state changes one wants to cause for users, business, operations, and developer experience.
+3. **Capabilities** — the responsibilities/capabilities that support the outcomes (as capabilities, not feature names).
+4. **Invariants** — behavior, APIs, data, UX, and operational constraints that must never be broken. Includes "constraints to be upheld" such as technical and security requirements.
+5. **Constraints** — technical/security/operational requirements and preconditions to be upheld.
+6. **anti-direction** — directions one must not proceed in; local optima to avoid.
+7. **Implicit Assumptions** — matters the specification presupposes without stating them, and the judgments derived therefrom.
+
+> Constraints to be upheld, such as technical and security requirements, are **not dropped**, whether stated explicitly or implicit. Pick these up reliably into the Invariants category and write them out as the Invariants candidates in the output contract below.
+
+## output contract (write out under headings whose transcription destination is uniquely determined)
+
+Write each candidate at a heading and granularity that lets a person transcribe it 1:1 to its destination. Make the headings correspond uniquely to the destinations in the table below. The responsibility of this rule extends only to **writing out** the candidates; reflecting them into destinations (the canonical intent-tree / compass, and steering / design) is not performed here. Promotion occurs when the user manually carries approved candidates into the discover / compass dialogue (there is no machine handoff).
+
+| Extraction category | Heading to write out | Destination (by hand; not reflected by this rule) |
+|---|---|---|
+| Purpose | `### Purpose candidates (→ intent-tree L0 Assumptions)` | intent-tree `## Assumptions` (corresponding to L0: Product Purpose) |
+| Desired Outcomes | `### Outcome candidates (→ intent-tree L1 Assumptions)` | intent-tree `## Assumptions` (corresponding to L1: Desired Outcomes) |
+| Capabilities | `### Capability candidates (→ intent-tree L2 Assumptions)` | intent-tree `## Assumptions` (corresponding to L2: Capabilities) |
+| Invariants | `### Invariants candidates (→ compass Invariants)` | compass `## Invariants` |
+| Constraints | `### Constraint candidates (→ compass Invariants)` | compass `## Invariants` |
+| anti-direction | `### Anti-direction candidates (→ compass Anti-direction)` | compass `## Anti-direction` |
+| Implicit Assumptions | `### Implicit-assumption candidates (→ intent-tree Assumptions / Decision Rules)` | intent-tree `## Assumptions`, and judgments derived from the assumptions become compass `## Decision Rules` candidates |
+
+- **Purpose, Outcomes, and Capabilities** are written at a granularity that can be transcribed 1:1 into the corresponding L0–L4 level `## Assumptions` items of the intent-tree (do not write into the canonical L0–L4 body).
+- **anti-direction** is written at a granularity transcribable into the compass `## Anti-direction` block.
+- **Judgments derived from implicit assumptions** are written out as compass `## Decision Rules` candidates (candidates, not finalized ADRs).
+- **Invariants and Constraints (constraints to be upheld, including technical/security requirements) are written out as candidates for the compass `## Invariants` block.** The destination of Invariants candidates is **limited** to the compass Invariants.
+
+## Downstream delegation (what not to include in output)
+
+- Reflecting Invariants candidates into steering (tech.md) or design is handled by the existing flows (writeback / export / by hand). **Reflection into tech.md / design is not included in the output of this rule.** The responsibility of this rule stays at recording them as Invariants candidates under headings bound for the compass, preserving a single source of truth.
+- Writing into the canonical intent-tree / compass is also not performed (promotion is by hand, after approval).
+
+## Handling of omissions / non-observation
+
+- Among the 7 categories, those on which the specification is silent are not filled in by guessing but stated explicitly as "no corresponding statement (silence)." Treating silence itself as a gap is the responsibility of the gap-readout side; this rule presents, distinctly, the candidates it could extract and the absence of categories it could not extract.
+- All outputs are made explicit as derived, regenerable, and not the source of truth. Nothing is written back to canonical.

package/templates/en/codex/skills/intent-from-spec/rules/gap-readout.md

@@ -0,0 +1,54 @@
+# Silence Gap Readout Procedure (read-only; only reads the rulers; gaps are hypotheses)
+
+The single source of truth by which the `intent-from-spec` skill holds the existing rulers up against the natural-language specification the user provides and surfaces the places where the specification is **silent** as gaps. SKILL.md holds only the procedure and report format; "which rulers to read and how, and which category/slot silence to bind them to" is governed by this rule. This rule only **reads** the rulers' catalogs; it does not define its own check IDs or slot IDs. The source of truth for the decision logic lives in the references, and this rule merely borrows that ID system as a vessel and sorts into it the items the specification fails to satisfy. Observation is limited to Read / Glob / Grep, and it does not modify the input specification, the canonical `.intent/*.md`, or the rulers' sources at all (writes go only under `.intent/spec-ingest/`).
+
+## posture (a proposer, not an accept/reject gate)
+
+State this rule's posture at the top. It is a **different posture** from the adjacent `intent-validate`, and is not a contradiction.
+
+- `intent-packets/rules/decision-slots.md` rules that "a tool (the slot validator) must not infer slot applicability from artifact content." That is because `intent-validate` is an **accept/reject gate (an adjudicator)** — if an adjudicator infers applicability from content, it produces unjust verdicts that stop or pass work on matters that were never declared.
+- `intent-from-spec` is a **proposer**, not an adjudicator. Its output is not an accept/reject verdict but **Assumptions (hypotheses)** that require human confirmation.
+- Therefore, with this rule, **spec-ingest may infer slot applicability from the specification's silences, but does not finalize it.** validate is forbidden from inferring because it is an adjudicator; for this rule, a proposer, to infer is not an exception to that discipline — it stands on a different posture from the start.
+- Every inferred applicability is marked as a hypothesis and treated as provisional until the user confirms and approves it (consistent with the product invariant that inferred intent is treated as provisional until a human reviews it).
+
+## Rulers to read (reference IDs; do not define them)
+
+This rule **reads** the ID catalogs of the following two existing sources of truth. The ranges, firing conditions, and severities of the IDs are owned by the references; this rule does not duplicate or redefine them ("the table is canonical").
+
+1. **The check catalog table in `intent-validate/rules/validate-checks.md`** — read the stable kebab-case ID set in the `ID` column (`invariant-conflict` / `anti-direction-violation` / `requirements-smell` / `decision-slot-empty` / `decision-slot-unsown`, and so on) and the severity-guideline column. Adding or changing checks is owned by that table, and this rule cites the ID column as-is (it does not re-derive them).
+2. **The common-core slot table in `intent-packets/rules/decision-slots.md`** — read the 8-slot ID set sown in all modes (`decision-consistency` / `decision-idempotency` / `decision-error-semantics` / `decision-authz` / `decision-quality-priority` / `decision-fit-criterion` / `decision-exception-flow` / `decision-downstream-trace`). The slots' classifications and closing destinations are owned by the reference, and this rule cites those IDs as-is.
+
+> This rule **never defines new** check IDs or slot IDs of its own. It creates no IDs absent from the catalogs above and sorts observed gaps into the existing IDs.
+
+## Gap-enumeration procedure
+
+Once intent-candidate extraction (extract-intent) is complete, read the catalogs above and, holding them up against the input specification, enumerate the **items that go unfilled** as gaps. Each gap shows the following three points in an observable form.
+
+1. **Which ruler's silence** — make explicit which it corresponds to among the stable kebab-case IDs of `validate-checks.md` or the common-core slot IDs of `decision-slots.md` (bind referenceable ones to an ID, and for ones that cannot be bound, omit the ID and state the absence explicitly).
+2. **Which category/slot silence** — show which absence in the specification (which check classification, which slot) the gap corresponds to, together with observable evidence (which part of the specification is silent).
+3. **Presentation as a hypothesis** — present it not as a confirmed defect but as a **hypothesis** the user should confirm ("there is a suspicion that the specification is silent on this item"). Do not certify confirmed defects.
+
+### Examples of binding (IDs are cited from the reference catalogs)
+
+- The specification is silent on the consistency model at data change → bind it as silence of the `decision-consistency` slot of `decision-slots.md` and present as a hypothesis.
+- The specification is silent on the return contract for abnormal input → silence of the `decision-error-semantics` slot.
+- The specification is silent on access rights / the executing actor → silence of the `decision-authz` slot.
+- Vague, subjective, or comparative wording remains in the requirement statements → bind to `requirements-smell` of `validate-checks.md`, quote it, and leave it to the user's judgment (do not write paraphrases back into the source of truth).
+- A statement in a direction that could conflict with the compass Invariants → `invariant-conflict`; a statement in a direction to be avoided → bind to `anti-direction-violation` and present as a hypothesis.
+
+> All of the above are examples, not the definitions of the IDs themselves. The ranges, firing conditions, and severities are owned by the reference catalogs.
+
+## Do not stop processing (warn only; same stance as drift-watch)
+
+- Even while presenting gaps, do **not stop** processing. Because this rule is not an accept/reject gate, the existence of a gap does not stop work or what follows; it stays at presenting warnings and observations (consistent with drift-watch's "warn only; do not stop" stance).
+- Every enumerated gap is a hypothesis and is held as an Assumption until the user confirms and approves it. It is neither approved nor rejected, and not discarded.
+
+## Avoid the "silence of silence" (also show what was checked)
+
+- Beyond showing each gap, also present **what was checked (the frame of the rulers read)** to avoid the error of omission caused by the checked frame itself being invisible (summarizing the checked frame and the places that went unfilled is the responsibility of omission-recap, but this rule too makes "which vessel it was held up against" observable by stating the ID system it bound to).
+- For places that cannot be referenced (no corresponding ID exists in the catalog; the ruler does not hold that viewpoint), do not fill in by guessing; **omit** the binding to an ID and state the absence explicitly.
+
+## Handling of output
+
+- All outputs are derived, regenerable, and not the source of truth. Nothing is written back to the canonical intent-tree / compass (promotion is by hand, after approval).
+- This rule does not modify the rulers' sources of truth (`validate-checks.md` / `decision-slots.md`) at all. It does not run checks or slot validation itself; it merely goes and reads the ID catalogs.

package/templates/en/codex/skills/intent-from-spec/rules/load-bearing.md

@@ -0,0 +1,48 @@
+# load-bearing Sorting Procedure (read-only; only reads the table; holds no numbers)
+
+The single source of truth by which the `intent-from-spec` skill qualitatively prioritizes the extracted intent candidates and surfaced gaps by "whether they are of a kind that, if dropped, damages the correctness of what follows (whether they are load-bearing)," and presents items with a high load-bearing degree in a form distinguishable from low ones. SKILL.md holds only the procedure and report format; "what to read as the discriminating axis and how to sort into high/low" is governed by this rule. This rule does **not invent** a new discriminating axis; it merely **reads and copies** a column of an existing source of truth. Observation is limited to Read / Glob / Grep, and it does not modify the input specification, the canonical `.intent/*.md`, or the rulers' sources at all (writes go only under `.intent/spec-ingest/`).
+
+## The discriminating axis is a read-the-table operation, not a fresh judgment
+
+The core of this rule comes down to "**reading and copying an existing column of `decision-slots.md`**." It does not define or derive the high/low axis in this rule, and it holds no mathematical solver, numeric score, or threshold whatsoever. Sorting is a table-citing operation, not the performing of new weighting or scoring.
+
+- The load-bearing degree per slot is already written in the **"front-load / defer door" column** of `intent-packets/rules/decision-slots.md`. This rule reads that column as the **primary discriminating axis**.
+- That column **exists in all of** the common-core slot table and every mode-specific delta table (standard / refactor / behavior-unknown / feature-growth) of `decision-slots.md`. Therefore, whichever slot is cited, that column can be read unambiguously.
+- The "rationale" column **exists only in the common-core table**. So it is not made the primary key of discrimination; it is used only as material to **supplement the explanation** of why something was judged high (borrowing only the wording for why dropping it is dangerous, while the high/low discrimination itself is performed on the "front-load / defer door" column).
+
+## The column read and the high/low correspondence
+
+Copy the value of the "front-load / defer door" column of `decision-slots.md` as-is, as follows.
+
+| Value of the "front-load / defer door" column | load-bearing degree | Meaning |
+|------------------------------------------------|---------------------|---------|
+| front-load (one-way; irreversible; floor of security / legal regulation) | **high** | Overturning it later has large external impact, and if dropped it damages the correctness of what follows. Silence on it is dangerous |
+| deferrable (two-way; localizable and reversible) | **low** | It can be re-decided in both directions and is reversible, and can be patched locally later. Even if silent, it is unlikely to directly break what follows |
+
+- Silence on a slot whose column value begins with "front-load" is **high**, and silence on a slot whose value begins with "deferrable" is **low**. No further gradation (intermediate values, numbers) is introduced in this rule.
+- The parentheticals of "front-load" / "deferrable" (one-way/two-way, irreversible/reversible, floor of security / legal regulation, and so on) are the places where the table itself explains why that high/low is read so, and this rule cites that wording as-is for the reason of presentation (it does not redefine it).
+
+### Examples of copying (values are cited from the reference table)
+
+- `decision-authz` (authorization) is "front-load (one-way: floor of security / legal regulation)" → silence is **high**. As the reason, append "irreversible; security floor" from the common-core table's "rationale" column as a supplement.
+- `decision-consistency` (consistency model) is "front-load (one-way: overturning it later has large external impact)" → silence is **high**.
+- `decision-error-semantics` (error semantics) is "deferrable (two-way)" → silence is **low**.
+- `decision-data-migration` (data migration; feature-growth) is "front-load (one-way: irreversible)" → silence is **high**.
+
+> All of these are examples of copying the values of the reference table, not re-adjudication in this rule. If a value changes, the reference table is canonical, and this rule merely follows and re-reads it.
+
+## Application to gaps and intent candidates
+
+- For a gap that gap-readout bound to a slot ID of `decision-slots.md`, cite the "front-load / defer door" column of that slot row and attach high/low. For a gap that cannot be bound to a slot ID (one for which the catalog has no corresponding column), do not attach high/low by guessing; state the absence explicitly as **load-bearing unknown**.
+- For intent candidates too (invariants, constraints, anti-directions, etc. that extract-intent picked up), if there is a corresponding slot, cite that row's column and attach high/low. In particular, Invariants candidates derived from technical / security requirements often fall on "front-load" slots such as `decision-authz`, and lean toward **high**.
+- Both high and low are **hypotheses, not confirmed severities**. They are held as Assumptions until the user confirms and approves them, and this rule's sorting neither discards nor finalizes any item.
+
+## Present high and low distinguishably
+
+- In presentation, distinguish high items from low ones in an **observable** way (e.g., grouping high ones at the top, attaching an explicit label, and so on). Do not pour all gaps out equally; let the user address the dangerous-if-dropped ones first.
+- Distinction stays at labeling and does not cut low ones away. Low ones too are held as Assumptions and included in omission-recap's re-confirmation scope.
+
+## Handling of output
+
+- All outputs are derived, regenerable, and not the source of truth. Nothing is written back to the canonical intent-tree / compass (promotion is by hand, after approval).
+- This rule does not modify the rulers' source of truth (`decision-slots.md`) at all. It holds no scoring or weighting engine of its own; it merely goes and reads the "front-load / defer door" column.

package/templates/en/codex/skills/intent-from-spec/rules/omission-recap.md

@@ -0,0 +1,42 @@
+# omission recap Procedure (summarize what was checked and what went unfilled, and prompt re-confirmation)
+
+The single source of truth by which the `intent-from-spec` skill, after finishing extraction (extract-intent), readout (gap-readout), and qualitative sorting (load-bearing), summarizes **what was checked (presenting the frame) and what went unfilled** for the user and prompts re-confirmation. SKILL.md holds only the procedure and report format; "how to summarize the checked frame, how to hold unapproved items, and how to guide promotion of approved items" is governed by this rule. This rule defines no new checks or slots; it **summarizes as-is** the frame of the existing ID system (`validate-checks.md` / `decision-slots.md`) that gap-readout bound to. Observation is limited to Read / Glob / Grep, and it does not modify the input specification, the canonical `.intent/*.md`, or the rulers' sources at all (writes go only under `.intent/spec-ingest/`).
+
+## Why a recap is needed (avoid the "silence of silence")
+
+State this rule's purpose at the top. Whereas the adjacent gap-readout "shows each gap," this rule bears the role of "**summarizing, as a list, the checked frame itself and the places that went unfilled.**"
+
+- Merely showing each gap individually does not let the user see **how far the AI checked**. When the checked frame itself is invisible, the user jumps to the conclusion that "it is already covered" and stops their own search. This is the "**silence of silence**" (an error of omission / automation bias in which the human stops searching because the AI implied completeness).
+- To avoid this, the recap **explicitly presents the frame of the rulers that were checked**. It lists "which rulers were read (the check catalog of validate-checks, the 8 slots of decision-slots), and of those which were filled, which were silent, and which could not be checked," and shows the very outline of the inspection to the user.
+- Beyond the silences, it also makes explicit the **places that could not be checked** (no corresponding ID exists in the catalog; the ruler does not hold that viewpoint). It does not fill them in by guessing; it leaves absence as absence. Not claiming coverage is itself a responsibility of the recap.
+
+## What the recap summarizes
+
+Receiving the output of extract-intent, gap-readout, and load-bearing, it lists the following in an observable form. In every case it cites as-is the existing IDs that gap-readout bound to, and does not re-derive or redefine them.
+
+1. **The checked frame (what was read)** — present the rulers read (the check catalog of `validate-checks.md`, the common-core 8 slots of `decision-slots.md`) and show the outline of the inspection.
+2. **The places that were filled (items the specification answered)** — show the frames the specification answered, making it observable that the recap did not "pick up only silences."
+3. **The places that went unfilled (silences)** — list the gaps gap-readout enumerated, together with the bound IDs. Record the qualitative sorting of load-bearing (high / low) in a distinguishable form alongside.
+4. **The places that could not be checked (absence)** — make explicit, without filling in by guessing, the places where there is no bound ID and judgment was withheld, as absence.
+
+## Approval gate (only approved items are promoted to canonical)
+
+The recap is a presentation to prompt re-confirmation, not a finalization. Reflecting anything into canonical requires the user's explicit approval.
+
+- Only when the user **confirms and approves** an item is that item made a target for placement onto the canonical intent structure (the intent-tree / compass Invariants, Anti-direction, Decision Rules) (Req 4.2).
+- Items that have not gone through the user's confirmation are **not automatically reflected** into canonical (Req 4.3). At the moment the recap presents them, every item is still a hypothesis.
+- Items that were not approved are **not discarded but held as Assumptions** (Req 4.4). This is a hold, not a rejection, and they remain in the derived area (`.intent/spec-ingest/`) for re-confirmation on later occasions.
+
+## Promotion is a human copy (it holds no machine handoff)
+
+This is the crux of this feature's boundary, and not stating it would create hidden shared ownership.
+
+- spec-ingest's output is **derived and regenerable**, not the canonical source of truth. spec-ingest merely writes out approved candidates into the derived area in a "**transcribable form**."
+- Promotion to canonical is done by a **human copy in which the user carries approved items by hand into the discover / compass dialogue**. spec-ingest **does not call** discover / compass, and discover / compass **do not automatically read** spec-ingest's output. No automatic linkage (machine handoff) exists between them.
+- Therefore the recap presents a **guide**: "please transcribe the items you approved, yourself, into the discover / compass dialogue." The recap itself never performs promotion. By writing out with headings and granularity that can be copied 1:1 into the transcription destination (the Assumptions of the intent-tree / each block of the compass), it makes the human transcription easy (keeping the seam of promotion in human hands).
+- Through this separation, no double source of truth between the derived (spec-ingest) and the canonical (intent-tree / compass) is created, and the overlap of ownership (hidden shared ownership) is avoided.
+
+## Handling of output
+
+- All outputs are derived, regenerable, and not the source of truth. Nothing is written back to the canonical intent-tree / compass (promotion is by hand, after approval).
+- This rule does not modify the rulers' sources of truth (`validate-checks.md` / `decision-slots.md`) at all; it merely summarizes the output of gap-readout and load-bearing. It does not run checks or slot validation itself.

package/templates/en/codex/skills/intent-improve/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: intent-improve
+description: After implementation, cross-check the .intent/ deliverables against the implementation reality on the three axes of completeness / correctness / coherence, classify the drift, and propose corrections. Reflects changes only after user approval. Guides missed write-backs to /intent-writeback.
+---
+
+# intent-improve Skill
+
+## Core Mission
+- **Success Criteria**:
+  - The `.intent/` deliverables and the implementation reality (codebase, tests, cc-sdd spec progress) are evaluated on the three axes (completeness / correctness / coherence)
+  - The evaluation results are presented in the 5 classifications (aligned / intent reinforcement recommended / corrective packet recommended / Decision Rules update recommended / invariant violation detected), with evidence (file / relevant text)
+  - Only the corrections the user approved are reflected into `.intent/` (the approval unit is per proposal)
+  - When an unrecorded write-back learning is detected, the skill does not write a delta itself but prompts the user to run `/intent-writeback`
+  - On a run whose 5 classifications include `Decision Rules update recommended` or `invariant violation detected`, following the provisions of `rules/improve-axes.md`, it also prompts the user to run `/intent-validate` (the check for conformance catch-up) (on a run that does not include them, it does not prompt; it only guides and does not itself make a conformance judgment)
+  - When drift-watch is on, the coherence detections are recorded into drift-log as stage:improve / outcome:missed and a pattern×outcome improvement report is presented (when off / missing / invalid / missing section / missing mode.md, nothing is done; the 5 classifications are unchanged)
+  - When drift-watch is on, context-cost-cues are matched and ways of progressing that eat context are named in a noticing tone (recorded to no log, not included in the pattern×outcome tally, the 5 classifications unchanged; when off, nothing is done)
+  - No application code has been changed at all
+
+## Execution Steps
+
+### Step 1: Collect the current state
+- Read the `.intent/` deliverables (intent-tree.md / intent-compass.md / `.intent/packets/index.md` + the packet files under active/ (cross-cutting read for the completeness axis; do not read archive/) / the per-packet drafts under `cc-sdd/<slug>/` / deltas.md). If `.intent/` is absent, guide the user through setup (installing intent-planner and running `/intent-discover`) and stop.
+- Read `.intent/mode.local.md` (falling back to `.intent/mode.md` if absent) for the mode state. If both are absent, continue with the standard default and announce it.
+- Collect the implementation reality: the codebase (read-only via Read/Glob/Grep), the presence and placement of tests, the progress of `.kiro/specs/` (only if it exists), and the promoted / pending entries of deltas.md.
+- If `.kiro/` is absent, continue without cc-sdd context. If deltas.md is absent, continue treating it as "no delta records" (non-blocking).
+- If a target scope is specified by argument, narrow down to it; otherwise target the whole of `.intent/`.
+
+### Step 2: Evaluate on the three axes
+- Read `rules/improve-axes.md` and cross-check `.intent/` against the implementation reality on the three axes of completeness / correctness / coherence.
+- Always attach evidence (file / relevant text) to the evaluation. Do not present an evaluation whose evidence cannot be shown.
+
+### Step 3: Classify and report
+- Classify the evaluation results into the 5 classifications (aligned / intent reinforcement recommended / corrective packet recommended / Decision Rules update recommended / invariant violation detected; multiple may apply) and present them organized per classification.
+- When unrecorded write-back learnings or declined items with the "on-hold" tag are detected, also include guidance to `/intent-writeback` following the provisions of `rules/improve-axes.md`.
+- On a run whose 5 classifications include `Decision Rules update recommended` or `invariant violation detected`, following the "Validate catch-up guidance" provisions of `rules/improve-axes.md`, also include guidance to `/intent-validate` (the check for conformance catch-up) alongside the writeback guidance (on a run that does not include them, do not include it; only guide and do not make the judgment yourself).
+- When drift-watch is on (when off / missing / invalid / missing section / missing mode.md, do nothing): check the `drift-watch` value in the `## Drift-watch (user-managed)` section of `.intent/mode.md`, and only when it is `on`, following the provisions of `rules/improve-axes.md`, record the drift detected on the coherence axis (invariant violation / anti-direction conflict) into `.intent/drift-log.md` as a `stage: improve` / `outcome: missed` draft, and present a `pattern × outcome` cross-tabulated improvement report. Delegate the recording details (the fixed 9-key order, append-only, obtaining commit, creating drift-log when absent) to `rules/improve-axes.md` (do not duplicate them here). This recording **does not create a new correction class** (the 5 classifications above are unchanged), and does not write into deltas.md or hook writeback. When off / missing / invalid / missing section / missing mode.md, do not record or aggregate drift and proceed as before (byte-equivalent to current behavior). Note that the report of the 5 classifications above is always done regardless of the drift-watch value. In addition, when `drift-watch: on`, following the "Context cost cues" section at the end of `rules/improve-axes.md`, match `.intent/context-cost-cues.md` and name, in a noticing tone, ways of progressing that eat context (**recorded to no log, not included in the pattern × outcome tally, and the 5 classifications stay unchanged**; skip if the catalog is absent).
+
+### Step 4: Confirm approval per proposal for the corrections
+- For each item that needs correction, present the correction proposal (a deliverable update proposal or a corrective packet proposal) and confirm the user's approval **per proposal** (do not force bulk approval).
+- Proposals that were not approved end as presentation only (do not rewrite).
+
+### Step 5: Reflect only the approved corrections
+- Reflect only the approved corrections into the canonical deliverables (intent-tree.md / intent-compass.md / under `.intent/packets/` (the target packet file / plan.md)).
+- When the canonical under `.intent/packets/` has been changed (including when a delta promotion is reflected into the target packet file), regenerate `.intent/packets/index.md` from the frontmatter under active/.
+- Corrections that change the Decision Rules follow the change convention of `rules/improve-axes.md` (add a new entry in ADR form + annotate the old entry as superseded with a reference to its successor and move it to `.intent/compass-archive/<rule-slug>.md` (a per-rule file)).
+- Do not write into deltas.md (recording deltas and finalizing declined-item tags are the responsibility of `/intent-writeback`).
+
+## Output Description
+
+**Reader**: a human developer who, after implementation, approves and corrects the drift between intent and implementation.
+**What this output makes them grasp first**: "**here is the drift between implementation and intent (invariant violations come first if any). There are N items pending approval.** If there is a missed write-back, go to `/intent-writeback`." The breakdown of the three-axis evaluation is detail for the decision.
+
+Lead the output with the conclusion (the drift and the pending approvals).
+
+- **Divergence summary (top)**: show the key points of the detected corrections by classification. If there is an `invariant violation detected`, lead with it as the top priority. If everything is `aligned` (no drift), state explicitly "aligned, no correction needed".
+- **Approval-pending list (next, per proposal)**: attach evidence (file / relevant text) to each correction proposal. Phrased so it is clear what gets reflected by approving what.
+- **Writeback guidance** (when applicable): when an unrecorded write-back learning is detected, guidance to run `/intent-writeback`.
+- **Validate catch-up guidance** (when applicable): on a run whose 5 classifications include `Decision Rules update recommended` / `invariant violation detected`, attach the guidance to run `/intent-validate` (the check for conformance catch-up) alongside the writeback guidance.
+- **Details**: the three-axis evaluation summary (completeness / correctness / coherence) and the breakdown by classification (aligned / intent reinforcement recommended / corrective packet recommended / Decision Rules update recommended / invariant violation detected).
+- **Improvement report** (when drift-watch=on): a report cross-tabulating drift-log by `pattern × outcome`. Always attach the honesty notes (`missed=0` is a suspicion of missing records / frequent `false-positive` suggests the anti-direction is too broad), align the aggregation keys to the type (pattern), and establish the group comparison (without group / with group) by the type id and the `commit` column of drift-log only (do not create an additional comparison mechanism).
+
+## Safety & Fallback
+- Do not rewrite the `.intent/` deliverables without user approval. Confirm approval per proposal.
+- Do not change application code (INV6. Code is read-only via Read/Glob/Grep).
+- Do not write into `.kiro/` (progress is read-only). The absence of `.kiro/` continues without cc-sdd context.
+- Do not write directly into deltas.md. Handling of missed write-backs and on-hold items is guidance to `/intent-writeback` only; the final updates are done by writeback.
+- The absence of `.intent/` guides the user through setup and stops. The absence of mode.md does not stop; continue with the standard default and announce it.

package/templates/en/codex/skills/intent-improve/rules/improve-axes.md

@@ -0,0 +1,121 @@
+# Improve: three-axis evaluation and classification criteria
+
+Rules for cross-checking the `.intent/` deliverables against the implementation reality in post-implementation realignment. Used by the `intent-improve` skill. Whereas writeback is the regular per-packet path, improve is the cross-cutting safety net that also catches drift not tied to a packet.
+
+## The three evaluation axes
+
+- **completeness** (whether the intended content has been realized): whether the Expected Behavior / Scope of the packet files under active/ appears in the implementation and tests (the cross-cutting read is limited to active/; do not read archive/). Detects unrealized or partially realized content.
+- **correctness** (whether the realized content matches the intent): whether the implemented behavior matches the packet's Why / Expected Behavior. Detects realizations that differ from the intent and additions outside the intent.
+- **coherence** (whether the implementation is consistent with the North Star, Invariants, and Decision Rules): whether the implementation contradicts the North Star / Invariants / Anti-direction / Decision Rules of intent-compass.md. Detects local optimizations and invariant violations. It also detects Decision entries whose Revisit when conditions in the Decision Rules of intent-compass.md can be read as met from the implementation reality and `deltas` (cross-read in split form: the split files `.intent/deltas/*.md` (source of truth if present, natural-key ascending) → read-fallback to the legacy single `.intent/deltas.md` (generated mirror) if absent; when both coexist, treat split as source of truth and do not double-count the mirror). Report such detections with evidence under the existing classification "Decision Rules update recommended" (do not create a new classification). In addition, as a separate path with a different input source, substring-match each event string in `.intent/milestones.md` against the `Revisit when` field of every Decision Rule, and re-propose any matched Decision Rule for review under the same "Decision Rules update recommended" classification. Rules whose `Revisit when` is explicitly recorded as "undecided" are excluded from matching (so as not to produce a false firing). To avoid over-matching on events that are too short, assume sufficiently specific events (at or above a certain length). This milestones-originated matching is read-only and report-only; it does not auto-rewrite the compass and does not create a new corrective classification. The implementation/deltas-originated Revisit detection and the milestones-originated matching coexist, and both are reported under the "Decision Rules update recommended" classification.
+
+## Classification (5 kinds; multiple may apply)
+
+- **aligned**: no drift. Consistent on all three axes (no correction needed; still attach the evidence of consistency).
+- **intent reinforcement recommended**: the implementation is sound, but the `.intent/` side is thin or left implicit. Present update proposals that add to or clarify the deliverables (intent-tree.md / intent-compass.md / packet files).
+- **corrective packet recommended**: the drift is on the implementation side and code changes are needed. Since improve does not change code, present the corrective work as a new packet proposal (an addition proposal of a new packet file (under active/) → export → the regular path of cc-sdd implementation).
+- **Decision Rules update recommended**: a judgment gained in implementation conflicts with the existing Decision Rules, or a new decision criterion is needed. A Decision entry whose Revisit when conditions are detected as met is also reported for review under this classification. Follow the "Decision Rules change convention" below.
+- **invariant violation detected**: the implementation violates the Invariants. Report it with top priority and present a corrective packet proposal or a review of the invariant itself (the user's call).
+
+When multiple classifications apply, list them all, and organize the report per classification.
+
+## Handling of evidence
+
+- Sources of the implementation reality: the codebase (Read/Glob/Grep only; changes forbidden), the presence and placement of tests, the progress of `.kiro/specs/`, and `deltas` (promoted / pending; cross-read in split form). All of them are **read-only**.
+- **Cross-read `deltas` in split form (CONTRACT "Split and archive convention for append-only records"; the same discipline as `intent-overview`'s `aggregate-sources.md`)**: read the split files `.intent/deltas/*.md` (source of truth if present, natural-key ascending) → read-fallback to the legacy single `.intent/deltas.md` (generated mirror) if absent; when both coexist, treat split as source of truth and do not double-count the mirror; archive is history and is not mixed into the active tally (read-only).
+- Always attach evidence (file / relevant text) to the evaluation. Do not present an evaluation or correction proposal whose evidence cannot be shown.
+
+## Decision Rules change convention (the same convention as writeback)
+
+- A correction that changes the Decision Rules **adds a new entry** in the existing ADR form of intent-compass.md (**Context** / **Decision** / **Why** / **Alternatives considered** / **Consequences** / **Revisit when**) and annotates the superseded old entry as superseded with a reference to the succeeding entry.
+- Move the old entry annotated as superseded, with its 6 fields intact (do not summarize), into the retired Decision Rule's **per-rule file** `.intent/compass-archive/<rule-slug>.md` (CONTRACT split & archive convention; `<rule-slug>` 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. Active Decision Rules entries remain written directly inside the compass.
+- Do not delete the old entry (history is preserved in compass-archive.md). Do not introduce custom fields (e.g., Supersedes).
+- 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.
+
+## Writeback guidance (division of roles as the safety net)
+
+- When an unrecorded write-back learning is detected — no delta entry in `deltas` (cross-read in split form: the split files `.intent/deltas/*.md` (source of truth if present) → read-fallback to the legacy single `.intent/deltas.md` if absent; no double-count) corresponding to the current Source Packet (the latest export), or an unrecorded decision that surfaced in the implementation — do not write a delta yourself; prompt the user to run `/intent-writeback`.
+- When declined items with the "on-hold" tag remain, only prompt for a re-proposal or a confirmed rejection. The final tag update (promote / confirm rejection / keep on hold) is the responsibility of `/intent-writeback`.
+- improve does not write into the `deltas` record (in either split or legacy single-mirror form) (all recording and state updates of deltas are done by writeback).
+
+## Validate catch-up guidance (a bridge to the conformance check)
+
+- Only when that run's 5 classifications include `Decision Rules update recommended` or `invariant violation detected` (= a run where a reflection that could affect compass's Decision Rules / Invariants may arise), attach, alongside the writeback guidance, one sentence prompting the user to run `/intent-validate` (the cross-check of whether a compass update has been caught up by each packet = the check for conformance staleness). On a run that is `aligned` only, or that does not include the two classifications above, do not attach it (avoid over-prompting).
+- improve itself does not make the conformance staleness judgment (the estimate of the right moment). The estimate of the right moment is the responsibility of intent-status, and improve only guides. The definitive diagnosis is made by `/intent-validate`.
+- This guidance is limited to adding a guidance sentence and does not change the three-axis evaluation (completeness / correctness / coherence) or the 5-classification logic at all (the 5 classifications are unchanged).
+
+## Recording to drift-log (drift-watch-linked)
+
+Only when `drift-watch: on`, copy the drift detected on the coherence axis (invariant violation / anti-direction conflict) into `.intent/drift-log.md` as an after-the-fact record. When `off` / missing / invalid, do not record (byte-equivalent to current behavior; the off-guard is guaranteed on the SKILL.md side).
+
+### Recording procedure
+
+- **Reuse the drift the coherence axis detected (invariant violation / anti-direction conflict) rather than detecting it anew**, and append it one at a time to `.intent/drift-log.md` as a `stage: improve` entry. The values are:
+  - `pattern: <the matched drift-patterns id | uncatalogued:<short name> | ->` (an id if identifiable, `uncatalogued:<short name>` for an actual drift outside the catalog, `-` if undeterminable)
+  - `stage: improve`
+  - `packet: <the attributable packet name | ->` (`-` if attribution cannot be determined)
+  - `mechanism: compass-invariant` (when an Invariant is violated) or `compass-anti-direction` (when the Anti-direction is conflicted; choose by which compass element was breached)
+  - `outcome: missed` (**a draft**: at improve time the drift has already happened and slipped through, so it is `missed` by default. The verdict is backed by the user's `user-verdict` being valid / false-alarm / unjudged)
+  - `user-verdict: unjudged`
+  - `recorded_at: <ISO 8601>`
+  - `commit: <short hash | ->`
+  - `note: <1-2 lines>` (what was violated / conflicted)
+- If multiple drifts are detected, append one entry per drift.
+- **Write in split form (CONTRACT "Split and archive convention for append-only records")**: drift-log is event-origin, so instead of appending to the end of a single `drift-log.md`, write one entry to a **per-date+slug split file** `drift-log/<date>-<slug>.md`. `<date>` is the recorded_at date; `<slug>` is derived from the pattern (the event) via the existing slug rule (`intent-packets/rules/packet-format.md`) — do not create new/sequential numbering. Because a different event touches a different file, tail collisions disappear by construction. Never rewrite or delete an existing entry (**append-only**).
+- **Always write all 9 keys in the fixed order**: `pattern` → `stage` → `packet` → `mechanism` → `outcome` → `user-verdict` → `recorded_at` → `commit` → `note`. Do not write an entry that is missing even one of the 9 keys.
+- **commit**: write the result of `git rev-parse --short HEAD`. When it cannot be obtained (non-repository, git CLI absent, etc.), use `-` (fail-open: keep recording).
+- **When the `drift-log/` directory is absent**: create the directory, then write the split file. An old single `drift-log.md`, if still present, can be read side-by-side by readers (migration is handled by this slice's migration step). Follow the sample in the "Entry format" section of `.intent/drift-log.md` (`### drift-log entry`) for the entry format.
+
+### Do not create a new correction class (separating recording from correction)
+
+- This recording **does not create a new correction class**. The "Classification (5 kinds)" above (aligned / intent reinforcement recommended / corrective packet recommended / Decision Rules update recommended / invariant violation detected) is left entirely unchanged. It merely **also copies** the drift detected on the coherence axis **into the drift-log schema**, separately from the correction classification.
+- **drift-watch records, improve corrects**. Recording (drift-log) and correction (the 5 classes) are separate responsibilities and are not mixed. Appending to drift-log neither substitutes for nor alters any correction.
+
+## Improvement report (pattern × outcome cross-tabulation)
+
+When `drift-watch: on`, improve also presents in its output an improvement report that cross-tabulates drift-log by `pattern × outcome`.
+
+- **The aggregation keys are aligned to the type (pattern)**. The structure by which the user can later reconcile the "without group (past failures) / with group (the drift-watch-on period)" is established **by the type id and the `commit` column of drift-log only** (do not create an additional comparison mechanism).
+- The report must always carry the following **honesty notes**:
+  - Read `missed=0` as "a suspicion of missing records," not "evidence it worked" (keeping only the moments it worked in the tally is confirmation bias).
+  - Frequent `false-positive` suggests the anti-direction is too broad.
+- These notes are of the same intent as the honesty note in `.intent/drift-log.md` and guarantee a reading not biased toward the "worked" family (prevented / caught).
+
+### Reading packet-scope-overflow as an "instrument that measures the first defense's efficacy" (DR9 second defense)
+
+Entries with `mechanism: packet-scope-overflow` (the second-defense detection drift-watch records when, after export, the user issues an implementation instruction that exceeds the target packet's `## Scope`) are read as an instrument that measures **whether the first defense (the convention-doc rule "go back to intent on scope overflow"—recall only, no enforcement) is actually working**. They ride the same pattern × outcome cross-tally, with one added reading discipline:
+
+- `outcome: caught` (the user heeded the warning and returned to intent via `/intent-packets` → re-export) = a moment when the first and second defenses worked.
+- `outcome: missed` (they ignored the warning and pushed through with cc-sdd) = a moment when the first defense's recall did not work = the **denominator of the intent-shift rate (the rate of scope creep)**. Only as these accumulate can "how much the first defense is failing" be observed (the chicken-and-egg: the mechanism that measures the first defense's efficacy lives inside the second defense itself).
+- `outcome: false-positive` (it was actually a valid scope extension) = a sign the check may be over-sensitive.
+- **Do not bring in numeric scoring or threshold solvers.** Do not assert "more caught means the first defense is working"; carry over the honesty notes as-is (`missed=0` = suspected missing record, frequent `false-positive` = over-sensitive check) and keep it to candidate presentation. Align the tally key to the type (pattern = `scope-creep` or `uncatalogued:scope-overflow`); build no extra comparison machinery.
+
+## Role boundary (the three-way split of recording, correction, and writeback)
+
+- **drift-watch does not hook writeback** (Requirement R8). So as not to muddy writeback's single responsibility — the two-stage promotion of deltas — recording to drift-log does not interfere with the writeback path at all. The behavior of "Writeback guidance" above is unchanged.
+- Recording (drift-log), correction (the 5 classes), and writeback (the two-stage promotion of deltas) are **three separate responsibilities**. Do not mix the three.
+
+## Context cost cues (tied to drift-watch)
+
+Alongside the coherence-axis evaluation, run a matching that makes you **notice** whether the way you are doing the post-implementation realignment is eating context (tokens). This is a **separate catalog** from drift-patterns (types of intent drift); only the symptom differs — it is "a situation that eats context" rather than "intent drift". This is awareness, not a norm, and because it differs in nature from the "recording to drift-log" and "improvement report (pattern×outcome tally)" above, it is **kept as a separate procedure**.
+
+- **Only when `drift-watch: on`** do this matching (do nothing when off / unset / invalid). When `.intent/context-cost-cues.md` is absent, skip the matching and announce that (do not stop).
+- **This is not recorded to any log.** Unlike the coherence-deviation detection above (which appends to `drift-log.md` and tallies pattern×outcome), context cost cues are **not appended to `drift-log.md` or to any other log**. Reason: consumption cannot be measured and its outcome cannot be evaluated, so mixing it into the log would pollute the drift-log tally with guesses; furthermore, what eats context legitimately differs per person, so recording it would intrude on privacy. **Do not apply the "append procedure for drift-log" or the "improvement-report tally" above to this matching, and do not include it in the pattern×outcome tally.**
+- **The 5 classes are unchanged**: this cue does not alter the existing 5 classes (aligned / strengthen intent / corrective packet / update Decision Rules / invariant violation) at all. It is presented as advice that leaves no log, separate from the corrective classes.
+
+### Procedure
+
+1. **Read context-cost-cues.md**
+   - Read `.intent/context-cost-cues.md` and obtain all types (seed + every type the user has grown). If absent, skip and announce (do not stop).
+
+2. **Match each type's symptom against how the realignment is proceeding**
+   - Check each type's `symptom` against the post-implementation realignment (the path/subject of reading code or done work). The `symptom` is a weak cue; if the fit is weak, stay silent (lean toward staying silent over false positives — to keep the awareness feature trustworthy).
+   - Use only the subject for matching. Do not read token consumption, git diffs, or runtime metrics.
+
+3. **When a type matches (present the cue; do not write to any log)**
+   - Name it to the user in a noticing tone. Example: "The way this realignment is proceeding may match `<id>` — this might be eating context."
+   - Add the type's "if this is unintentional" light alternative (thin entry point / JIT pull / limited input) as an **optional choice**. Example: "If this is unintentional, there is also <light alternative> (the judgment is yours)."
+   - **Do not correct or instruct.** Phrase it as a cue rather than an imperative or a verdict. Installing many skills or loading full content can be a legitimate high-cost choice, so do not dismiss a context-eating choice as unnecessary. Leave the judgment to the user.
+   - **Do not append to any log** (do not reuse the coherence-deviation append procedure or tally).
+
+4. **When no type matches**
+   - Name nothing. **Write nothing to any log** (do not record a miss either — this matching has no log at all).

package/templates/en/codex/skills/intent-overview/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: intent-overview
+description: Read-only aggregation skill that reads the scattered .intent/ artifacts and generates a formatted read-through/overview view under .intent/overview/ as a derived view. Never modifies any canonical artifact.
+---
+
+# intent-overview Skill
+
+## Core Mission
+- **Success Criteria**:
+  - Reads the existing scattered `.intent/` artifacts (intent-tree / intent-compass / packets index & active / packets/plan / export-log / deltas / mode / drift-log) read-only, and generates a formatted overview view that humans and agents can read through at once at `.intent/overview/overview.md` (R1.1)
+  - Treats the output as a derived view and never creates, modifies, or deletes any canonical `.intent/*.md` artifact. Writes are limited to under `.intent/overview/` (R1.2)
+  - On re-run, regenerates the overview from the latest artifacts by full replacement, producing no duplication of the source of truth (idempotent regeneration. R1.3)
+  - When `.intent/` or a required artifact (e.g. intent-tree) is absent, writes nothing, states the absence explicitly, and guides the user to the skill to run first (e.g. `/intent-discover`) (R1.4)
+  - Makes clear that the output is derived / regenerable / not the source of truth (and Git-untracked) (the reader's concern takes priority, so this may be relegated to the end of the view. R1.5)
+  - Organizes the whole picture into concern-separated derived views (intent view / dependency-block view / progress view), reflecting progress not as a single percentage but along axes of differing nature
+  - Lays out all packets as a single progress rail at the top of the view, annotates each row with the five signals + `[current stage → next stage(s) to pass through]`, so that "which packet is 🔵 you are here now, which stages each will pass through next, and where the ⚪ remaining work / 🔴 unreflected items are" is visible at a glance (only mirroring the five signals and `state` read-only, without computing or inferring state)
+  - Aggregates while keeping canonical intent distinct from inferred intent, and design intent distinct from implementation reality; marks gaps and unobserved areas as "unfilled / unobserved" and never fills them in by guessing
+  - Does not call other skills directly; coordinates only via read-only access to scaffold files (`.intent/*.md`) and guidance in the output text (R6.5). Has no state machine / autonomous loop / resident process, and maintains zero external dependencies (R6.1 / R6.2)
+
+## Execution Steps
+
+### Step 1: Confirm `.intent/` and required artifacts exist (fail-fast)
+- When the user requests generation of an overview view, first confirm that the `.intent/` directory exists.
+- If `.intent/` or a required artifact (at minimum `.intent/intent-tree.md`) is absent, **write nothing**, state the absence explicitly, guide the user to the skill to run first (e.g. `/intent-discover`), and stop (fail-fast. R1.4). Do not create or update `.intent/overview/overview.md` at this point.
+- Read `.intent/mode.md` (do not stop if absent; the enforcement / drift-watch values are referenced in later steps. Read-only — never modify it).
+
+### Step 2: Read sources and aggregate by delegating to the four rules
+- This skill has no analysis / recovery / inspection logic of its own. The exact reading rules for each concern are delegated to the following four rules (referenced by relative path). Follow the exact headings, keys, and column names each rule specifies; keep canonical and inferred distinct; and state gaps and unobserved areas (never fill in by guessing).
+- `rules/aggregate-sources.md` — intent-document aggregation (intent-tree L0–L4 / intent-compass North Star, Anti-direction, Invariants, Decision Rules / packets index & active / plan / export-log / deltas). Separate canonical intent from inferred intent (derived from intent-tree's Assumptions / Open Questions). Code recovery is read-only from the refactor-mode `algo-intent-recovery` output; do no AST / scanner recovery of your own. If recovery output is absent, state the absence and guide the user to that algo (R2.x / R4.x).
+- `rules/mermaid-tree.md` — render intent-tree's L0→L4 as a pure Mermaid `graph`, with the corresponding text hierarchy alongside it as the source of truth. If intent-tree is empty/ungenerated, omit the Mermaid figure and state why (R3.x).
+- `rules/gap-readout.md` — read the drift-log and intent-validate inspection axes **without reimplementing** them, and aggregate them as the "design intent vs implementation reality" gap. Aggregate drift only when `mode.md`'s `## Drift-watch` section is `on` and `drift-log.md` exists; when `off` / unspecified / absent, omit that block and state it as unobserved. Map validate axes to the stable kebab-case ID catalog in `validate-checks.md`. The `## Enforcement` / `## Drift-watch` sections are read-only — never modified (R5.x).
+- `rules/progress-readout.md` — split progress not into a single percentage but into 3 axes (intent stability / realization completeness / evidence certainty), deriving each axis from reading existing artifacts and stating its provenance. Present axis-to-axis divergences as-is without collapsing them. Read packet frontmatter `depends_on` to derive block state read-only (dependencies are only read from declarations, never inferred or computed), and surface cycles / unresolved dependencies. Organize into concern-separated derived views (intent / dependency-block / progress). Omit any axis or view whose source artifact is absent, stating "unobserved / ungenerated" (R8.x / R9.x).
+- Branching policy: branch on whether inferred intent is present and on drift-watch on/off; when absent, omit the relevant block and state its status (never fill in by guessing). For backward compatibility, read an existing packet without `depends_on` as "no dependencies", without `## Evidence` as "unfilled", and the old 3-value state (`draft|active|done`)'s `active` as "in progress (equivalent to implementing)" (follow the rules' specifications).
+
+### Step 3: Write the overview view last (full replacement, derived)
+- Only after all reading and aggregation are complete, **last** write `.intent/overview/overview.md` by **full replacement** (idempotent regeneration. R1.3). Never write to any canonical `.intent/*.md`.
+- The composition order of the content follows "Output Description" (the progress rail = the conclusion at the top, then the concern-separated views, **with the derived / not-the-source-of-truth notice at the END**). Prioritize the human reader's "where am I now / what happens next," and do not fill the start of the view with the derived notice.
+- That this view is derived, regenerable, not the source of truth, and Git-untracked is made explicit in the end-of-view notice (R1.2 / R1.3 / R1.5). That each derived view is derived and regenerable (not the source of truth) is likewise shown in each view's notice (R9.5).
+
+## Output Description
+
+**Reader**: a human developer who wants to read through the whole of `.intent/` (and the AI that reads it downstream).
+**What this output makes them grasp first**: "of all packets, which one is 🔵 you are here now, which stages each will pass through next, and where the 🔴 unreflected / ⚪ remaining work are." Tool-internal notices such as derived / not-the-source-of-truth are not the reader's concern, so **relegate them to the END**.
+
+Compose the head of the view in the following order (the order that gets a human to "where am I / what happens next" by the shortest path).
+
+1. **Progress rail (top, conclusion)**: lay out all packets vertically and annotate each row with the five signals (✅ reflected / 🔵 you are here / ⚪ not started / 🔴 unreflected / ◻ merged), followed by `[current stage → next stage(s) to pass through]` (per `progress-readout.md` "Annotate each row with `[current stage → next stage(s) to pass through]`"). This makes "which P is you-are-here now and which stages remain after this" and "where the unreflected / remaining work are" visible at a glance on a single sheet.
+2. **Concern-separated derived views** (the rail's breakdown):
+   - **Intent view**: the Mermaid figure of intent-tree (L0–L4) + the text hierarchy, intent-compass, and the packet list (with plan / export-log / deltas alongside as context). Canonical and inferred kept distinct.
+   - **Dependency-block view**: dependency relations based on packets' `depends_on` and the resulting block state (with cycles / unresolved dependencies surfaced if any).
+   - **Progress view**: the 3 axes (intent stability / realization completeness / evidence certainty) with each axis's provenance, axis-to-axis divergences, and the design-intent vs implementation-reality gap aggregation (since the progress rail is brought to the top in 1., concentrate here on the breakdown of the 3 axes).
+3. **End-of-view notice**: that this view as a whole and each view is derived / regenerable / Git-untracked and not the source of truth (R1.2 / R1.3 / R1.5 / R9.5). Any view or axis without source material is omitted, with the reason (unobserved / ungenerated) stated.
+
+## Safety & Fallback
+- **Write boundary**: writes are limited to under `.intent/overview/`. The canonical `.intent/*.md` is read-only — never created, modified, or deleted there (the `Write` in the frontmatter is permitted solely for writing under `.intent/overview/`).
+- **Does not call other skills directly**: coordination happens only via read-only access to scaffold files (`.intent/*.md`) and guidance in the output text (R6.5). It holds no decision logic for recovery (`algo-intent-recovery`) / inspection (intent-validate) / drift (drift-watch); it only reads the outputs and definitions they leave behind.
+- **Has no state machine / autonomous loop / resident process** (R6.1). The output view itself serves as a snapshot at read time.
+- **Zero external dependencies** (INV2 / R6.2). Introduces no external package; limited to Node standard and natural-language heuristics.
+- **Does not modify application code** (INV6 / R6.3).
+- **When prerequisites are absent**: when `.intent/` or a required artifact is missing, write nothing, state the absence, guide the user to the skill to run first (e.g. `/intent-discover`), and stop (R1.4).
+- **On partial gaps**: when inferred intent is unfetched / drift-watch is off / intent-tree is empty, omit the relevant block and state "unfetched / unobserved / ungenerated" (never fill in by guessing). When Mermaid cannot be generated, present the text hierarchy as the source of truth, omit the figure, and note the reason.