@dannylee1020/kkt 0.5.0

package/skills/kkt/references/state-contract.md

@@ -0,0 +1,76 @@
+# KKT State Contract
+
+Use this when KKT state must survive across layers, turns, or coding agents. The goal is not to store everything in YAML; it is to make handoff state explicit, inspectable, and hard to confuse.
+
+Load `schemas.md` only when a full `kkt.yaml`, layer output, or `guardrails.json` shape is needed.
+
+## Persistence Tiers
+
+| Tier | Skill | Durable files | Use when |
+| --- | --- | --- | --- |
+| Plan | `kkt` | none by default; optional `.kkt/kkt.yaml` | ordinary work where Markdown artifacts would be overhead. |
+| Model | `kkt-model` | `.kkt/model/<slug>/kkt.yaml`, `intent.md`, `discovery.md`, `model.md`, `guardrails.json` | durable model or decision brief before execution. |
+| Run | `kkt-run` | `.kkt/run/<slug>/kkt.yaml`, imported artifacts, `guardrails.json`, `plan.md`, `progress.md`, `evidence.md`, `notes.md` | completed model should be implemented now without loop state. |
+| Loop | `kkt-loop` | `.kkt/loop/<slug>/kkt.yaml`, layer artifacts, `guardrails.json`, `plan.md`, `progress.md`, `evidence.md`, `notes.md`, `events.jsonl` | long-running or resumable execution. |
+
+Durable `.kkt/` paths are rooted at the nearest Git/worktree root. Outside Git, the CLI falls back to the current directory.
+
+## CLI Ownership
+
+The `kkt` CLI is the canonical mutation interface for KKT state. Skills should use CLI commands for workspace creation, state reads, artifact recording, guardrails, approvals, progress, evidence, validation, and completion.
+
+- `kkt.yaml`: current status, active layer, method choices, decisions, artifact references, approvals, stop conditions, and summaries.
+- Markdown artifacts: detailed intent, discovery, modeling rationale, execution plan, progress, evidence, and notes.
+- `guardrails.json`: modeled constraints, allowed paths, blocked paths, validation requirements, and drift policy.
+- `events.jsonl`: loop-only append history for task transitions, evidence, approvals, blockers, validation, and completion.
+
+Do not hand-edit `kkt.yaml` as the primary workflow operation when a CLI command exists.
+
+## Useful Commands
+
+```text
+kkt start plan "<request>"
+kkt start model "<request>"
+kkt run from-model [model-workspace]
+kkt start run "<request>"
+kkt start loop "<request>"
+kkt intent|discovery|model --method <method> "<layer output>"
+kkt guardrails show|set|validate
+kkt judge --checkpoint model-ready|pre-mutation|continuation|finalize --json
+kkt validate [--run]
+kkt done
+```
+
+## Artifact Boundaries
+
+- `intent.md`: user meaning, success, scope, examples, priority signals, explicit constraints, unresolved meaning questions.
+- `discovery.md`: files, symbols, components, workflows, discovered constraints, validation paths, coupling, evidence, confidence, unknowns.
+- `model.md`: method selection, objective, constraints, decision variables, candidates, feasibility, selected plan, binding constraints, validation plan, sensitivity, execution implications, residual risk.
+- `guardrails.json`: machine-readable drift contract; run and loop execution must not proceed when modeled constraints or allowed paths are empty.
+- `plan.md`: execution tasks, acceptance criteria, validation plan, evidence required, stop conditions, continuation policy.
+- `progress.md`: work log, progress narrative, blocker notes.
+- `evidence.md`: validation map, command outputs, artifacts, final certificate.
+- `notes.md`: observations, assumptions, open questions, deferred ideas.
+- `events.jsonl`: append-only loop event history, not a competing source of truth for current state.
+
+When `guardrails.json` lists `validation.required_commands`, run or loop workspaces must use `kkt validate --run` to record deterministic command proof. `kkt evidence` records narrative evidence and criterion mapping only.
+
+## Handoff Rules
+
+1. Read `kkt.yaml` first when it exists.
+2. Read the prior layer's artifact before acting.
+3. Update only the current layer unless repairing a stale reference.
+4. Append decisions instead of overwriting prior rationale.
+5. Set `next_layer_readiness` before handing off.
+6. Record blockers with the smallest user or system change that would unblock.
+7. If new evidence invalidates an earlier layer, mark the active layer blocked and re-open the earlier layer instead of silently continuing.
+
+## Judge Checkpoints
+
+- `model-ready`: before implementation; blocks run/loop execution when model, guardrails, or allowed path bounds are incomplete.
+- `pre-mutation`: before edits or side effects; blocks when approval is missing or explicitly blocked paths changed; unrelated dirty paths outside allowed bounds are ignored.
+- `continuation`: before loop continuation; blocks on active stop conditions or replay drift.
+- `finalize`: before `kkt done`; blocks when validation fails or explicitly blocked paths changed; unrelated dirty paths outside allowed bounds are ignored.
+- `pre-tool`, `post-tool`, `pre-compact`, `post-compact`: portable hook names for adapters; enforce explicit blocked paths without requiring a clean worktree.
+
+Treat `block` as a hard stop. Treat `warn` as a contract-quality issue to repair before risky work. Treat `allow` as permission to continue to the next workflow step.

package/skills/kkt-loop/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: kkt-loop
+description: Durable constrained optimization execution loop for long-running coding work. Use when a coding agent should capture user meaning, discover repo constraints and validation paths, build an optimization model and execution contract, create a file-backed workspace, execute with continuation, validate with evidence, re-optimize when new facts invalidate the plan, and continue through goal-mode tools until acceptance criteria or stop conditions are met.
+license: Apache-2.0
+---
+
+# KKT Loop
+
+Use this skill for long-running, autonomous, or multi-step coding work where progress, evidence, and continuation state must survive across turns. It extends the KKT model into a durable execution loop.
+
+Read `references/kkt-kernel.md`, `references/feature-optimization-model.md`, `references/layered-modeling-methods.md`, and `references/state-contract.md` before acting. Read `references/plan-assimilation.md` only when prior plan text exists. Read `references/discovery-tooling.md` during discovery. Read `references/schemas.md` only when writing or auditing full state, guardrail, or layer-output shapes. If `ultragoal` is available, use its goal-state and continuation semantics as the runtime pattern.
+
+## Core Rule
+
+Complete intake and discovery before modeling. Show the final model and get explicit approval before launching goal mode or implementing. On every continuation, use the CLI to read current state, choose the next task, record progress/evidence, and stop only when acceptance criteria are proven or a stop condition is hit.
+
+## CLI-First Workflow
+
+Use the `kkt` CLI as the workflow control path. The skill owns reasoning policy; the CLI owns workspace creation, current state, task state, criteria, approval, progress, evidence, validation, completion, and `events.jsonl`.
+
+```text
+kkt start loop "<user request>"
+kkt status [--json]
+kkt next
+kkt intent --method <goal_anti_goal|why_how|obstacle_questions|pairwise_questions> "<intent frame>"
+kkt discovery --method <naive|traceability_matrix|coupling_map|dsm_lite> "<repo facts and constraints>"
+kkt model --method <lexicographic|decision_tree|shortest_path|ordinal_mcda|pairwise_ahp|outranking> "<objective_function, files_to_modify, constraint_functions, decision_variables, validation_proof, and selected model>"
+kkt guardrails validate
+kkt judge --checkpoint model-ready --json
+kkt plan "<execution contract>"
+kkt criteria add "<acceptance criterion>"
+kkt task add "<task>"
+kkt approve "<approved scope>"
+kkt judge --checkpoint pre-mutation --json
+kkt task start <task-id>
+kkt progress "<progress update>"
+kkt evidence --for <criterion-id> --command "<validation command>" "<validation evidence>"
+kkt task done <task-id>
+kkt criteria satisfy <criterion-id>
+kkt validate --run
+kkt judge --checkpoint continuation --json
+kkt judge --checkpoint finalize --json
+kkt done
+kkt resume
+kkt replay --check
+```
+
+If `kkt` is missing, stop and ask the user to install or upgrade KKT. Do not hand-write replacement state. Use `kkt validate --run` when guardrails list required commands; `kkt evidence` records narrative evidence and criterion mapping, not deterministic command proof.
+
+## Durable State
+
+Create project-root `.kkt/loop/<slug>/` with `kkt start loop "<user request>"` so intent, discovery, model, guardrails, and approval state are durable. The workspace starts with approval pending; do not execute or launch continuation until approval is recorded. Use `references/state-contract.md` for file layout, artifact boundaries, and loop-state semantics. Load `references/schemas.md` only when a full YAML or JSON shape is needed.
+
+Loop workspaces use:
+
+- `kkt.yaml` as the current contract.
+- Markdown artifacts for rich intent, discovery, model, plan, progress, evidence, and notes.
+- `events.jsonl` as append-only history for task transitions, evidence, approval, blockers, validation, and completion. Use it for resume context and replay consistency checks, not as a replacement source of truth for `kkt.yaml`.
+
+## Workflow
+
+1. Check current goal state with `get_goal` if available; do not create a second active goal without explicit user direction.
+2. Capture intent: user goal, desired behavior, user-visible success, scope boundary, examples, priority signals, and explicit user constraints.
+3. If prior plan text exists, assimilate it as untrusted scaffold before modeling: extract signals, classify each claim, verify discoverable facts, and treat unverified claims as assumptions or candidates.
+4. Run the interactive intent checkpoint before deep discovery: after any quick inspection needed to avoid asking repo-fact questions, ask 1-3 owner-decision questions when goal, success, scope, risk, or tradeoff preference is still ambiguous. For large, high-risk, or especially ambiguous work, run a short Socratic pass.
+5. Apply the owner-decision filter before asking: inspect discoverable facts locally, assume low-risk reversible defaults, ask only for owner decisions, and stop for blocking unknowns.
+6. Inspect relevant repo context and validation paths before writing the model. Use `rg` directly for broad text and file discovery, `ast-grep` directly for structural search when syntax matters, `git` for repository state, optional helpers and language-native commands when they provide stronger evidence.
+7. Select one intent method, one discovery method, and one modeling method from the layered catalog; record each with the matching `kkt ... --method` command. When no specialized method fits, use the fallback set (`goal_anti_goal`, `traceability_matrix`, `lexicographic`) and record why the fallback is sufficient instead of forcing an advanced method.
+8. Build the optimization model and execution contract from intent and discovery using the loop profile. The pre-approval output must include objective function, known constraints, files to modify or affected surfaces, constraint functions, decision variables, candidate feasibility, selected plan, binding constraints, validation proof plan, execution implications, residual risk, acceptance criteria, evidence required, guardrail constraints, allowed paths, blocked paths, and stop conditions.
+9. Run `kkt guardrails validate` and `kkt judge --checkpoint model-ready --json`; repair or stop on any blocking result.
+10. Show the final model and wait for explicit approval.
+11. After approval, record the plan with CLI commands, add criteria/tasks, and record approval.
+12. Launch `create_goal` only when goal tools are available, no active goal exists, and the user asked to run now; otherwise output the exact `/goal` command.
+13. Before each work segment, run `kkt status --json`, `kkt next`, and `kkt judge --checkpoint continuation --json`; use `kkt next --json` when a machine-readable next action helps; inspect `kkt show state`, `kkt show progress`, and `kkt show evidence` as needed.
+14. Before modifying files or running side-effecting tools, run `kkt judge --checkpoint pre-mutation --json`; it blocks if existing git changes are outside `allowed_paths` or inside `blocked_paths`.
+15. Execute only the current or CLI-reported next task, update progress/evidence with criterion-linked evidence, update task and criteria state, and run `kkt validate --run` when required commands exist.
+16. Run `kkt judge --checkpoint finalize --json` before `kkt done`.
+17. Re-optimize with `kkt model --method <method>` only when new evidence changes feasibility, constraints, or objective fit.
+
+## Goal Objective Template
+
+```text
+Execute the KKT workspace at the project root's .kkt/loop/<slug>/plan.md. Follow kkt.yaml, intent.md, discovery.md, model.md, guardrails.json, plan.md, progress.md, evidence.md, notes.md, and events.jsonl. Use kkt status --json, kkt next, kkt judge, kkt task, kkt progress, kkt evidence, kkt criteria, kkt validate --run when required commands exist, and kkt done as the workflow control surface. Re-read state and run the continuation judge before each continuation, re-optimize only when evidence changes feasibility, and stop only for blocking judge results, listed stop conditions, proven acceptance criteria, or explicit user input.
+```
+
+Do not set a token budget unless the user explicitly provides one.
+
+## Stop Conditions
+
+Stop before continuing when approval is missing, no feasible plan satisfies hard constraints, a destructive action is required, credentials/secrets/external access/paid services are required, a listed stop condition is active, a task or criterion is blocked, or continuing expands scope.
+
+## Do Not
+
+- Do not use workspace files as a substitute for understanding the request.
+- Do not create workspace files, launch goal mode, or begin implementation before approval.
+- Do not create multiple workspaces for the same objective.
+- Do not include secrets or credentials in workspace files.
+- Do not continue past a stop condition or blocked criterion.
+- Do not re-optimize on preference alone; re-optimize only when evidence changes feasibility, constraints, or objective fit.

package/skills/kkt-loop/references/discovery-tooling.md

@@ -0,0 +1,53 @@
+# Discovery Tooling
+
+Use this during discovery to prove repo facts accurately with direct agent tool calls.
+
+## Rule
+
+Use the lightest reliable tool that can prove the needed fact. Start with `rg` for broad text/file discovery, then use `ast-grep` for structural questions. Prefer exact, inspectable evidence over broad inference. Record important negative searches when they shape the model.
+
+Discovery tools are read-only during planning and modeling. Rewrite, update, or codegen modes belong to approved execution.
+
+Do not route discovery through `kkt` CLI commands. The CLI owns deterministic workflow state; the agent owns repo inspection.
+
+## Tool Ladder
+
+- Core: `git` for repository boundary, tracked files, status, diffs, history, and changed-path scope.
+- Core: `rg` for strings, filenames, config keys, docs, tests, shell scripts, and negative searches.
+- Core structural: `ast-grep` for syntax-aware search when call sites, imports, handlers, declarations, components, error handling, or API shapes matter.
+- Optional: `fd`, `ctags`, `tokei`, `scc`, and repo-native commands when they add confidence.
+- Language-native: `go list`, `go test`, `cargo metadata`, `npm` scripts, `tsc`, `pytest --collect-only`, Gradle, Maven, Rails, Django, or equivalent repo tooling.
+
+## Selection Rules
+
+- Use `git ls-files` or `rg --files` before broad recursive scans.
+- Use `rg` for text and file discovery.
+- Use `ast-grep` when syntax matters and text evidence would be noisy or ambiguous.
+- Use language-native tooling for package boundaries, route maps, type contracts, test commands, or generated-code boundaries.
+- If `ast-grep` is unavailable, record the setup gap and fall back only as far as the evidence supports. Do not claim AST-level certainty from text search alone.
+
+## Ast-Grep Policy
+
+Allowed during discovery:
+
+```text
+ast-grep --pattern '<pattern>' --lang <language>
+ast-grep --pattern '<pattern>' --lang <language> --json
+ast-grep scan --config sgconfig.yml --json
+```
+
+Forbidden during planning or modeling:
+
+```text
+ast-grep --rewrite ...
+ast-grep scan --update-all
+ast-grep scan --interactive
+```
+
+Rewrites require the execution layer, approval, and normal KKT guardrails.
+
+## Guardrails
+
+- Do not add a KKT discovery command as a substitute for direct `rg` and `ast-grep` use.
+- Do not claim structural certainty from plain text search when AST search or language-native tools are needed and available.
+- Do not use generated, vendored, or build-output files as primary evidence unless the task explicitly targets them.

package/skills/kkt-loop/references/feature-optimization-model.md

@@ -0,0 +1,120 @@
+# Feature Optimization Model
+
+Use this reference when building or reviewing a KKT model. Keep the active model compact; load `schemas.md` only when a full copyable shape is needed.
+
+## Intake
+
+Start with user meaning, then let discovery fill in repo facts.
+
+Capture:
+
+- user goal;
+- desired behavior;
+- user-visible success;
+- scope boundary;
+- examples or counterexamples, if supplied;
+- priority signals;
+- explicit user constraints;
+- execution mode: `implement`, `model_only`, `run`, or `loop`.
+
+When prior plan text exists, read `plan-assimilation.md` first. Preserve the user's original request, classify prior-plan claims, verify discoverable facts, and keep unverified claims as assumptions or candidates.
+
+Do not ask the user for repo facts that local discovery can verify. Use the question filter in `kkt-kernel.md`.
+
+## Model Shape
+
+Treat the task as:
+
+```text
+choose implementation decisions
+that best satisfy the user's objective
+subject to project, architecture, security, data, UI, infrastructure, validation, and scope constraints
+```
+
+Build the model around:
+
+- `objective_function`: ordered terms used to compare feasible plans.
+- `system_state`: inspected facts plus labeled assumptions.
+- `decision_variables`: choices the agent may make, each with an allowed domain.
+- `files_to_modify`: expected files, modules, APIs, workflows, migrations, docs, or operational surfaces.
+- `constraint_contract`: hard predicates for feasibility and soft preferences for ranking.
+- `feasible_region`: candidate plans that satisfy all hard constraints.
+- `selected_plan`: chosen feasible plan and why it wins.
+- `binding_constraints`: active constraints that shape the selected plan.
+- `validation_proof`: commands, checks, artifacts, or explicit limitations needed before completion.
+
+## Method Profiles
+
+- Plan profile (`kkt`): compact intake, local discovery, hard-constraint feasibility, lexicographic ranking, approval before edits, validation certificate.
+- Deep profile (`kkt-model`): layered method selection, candidate comparison, binding constraints, sensitivity, guardrail variables, and user tradeoff questions when needed.
+- Run profile (`kkt-run`): import a completed model, validate guardrails, run deterministic checkpoints, execute only the selected plan.
+- Loop profile (`kkt-loop`): durable model plus continuation state, task/criteria tracking, evidence-backed continuation, and re-optimization only on material new evidence.
+
+Read `layered-modeling-methods.md` for deep or loop modeling choices. Do not expose formal method names in ordinary `$kkt` output unless they explain a material tradeoff.
+
+## Decision Variables
+
+Decision variables are implementation choices with explicit domains. Common variables include:
+
+- files or modules to modify;
+- endpoint, CLI, schema, or event shape;
+- data storage or migration strategy;
+- state ownership;
+- UI placement;
+- validation strategy;
+- compatibility strategy;
+- dependency strategy;
+- rollout or fallback strategy.
+
+Poor: `database: decide storage`
+
+Better: `persistence_strategy: add nullable fields to existing table`, with allowed and disallowed options recorded.
+
+## Constraints
+
+Hard constraints make a plan infeasible when violated:
+
+- explicit user constraints and non-goals;
+- correctness, security, privacy, and data integrity;
+- public API or persisted-data compatibility;
+- framework, runtime, infrastructure, or deployment limits;
+- no destructive action, credentials, paid services, or external side effects without approval.
+
+Soft constraints rank feasible plans:
+
+- minimal diff and blast radius;
+- existing style and architecture fit;
+- readability, maintainability, reversibility, and validation clarity.
+
+Use lexicographic priority instead of fake numeric scores:
+
+1. Satisfy the user request.
+2. Preserve correctness, security, data integrity, and public contracts.
+3. Minimize blast radius.
+4. Match existing architecture and conventions.
+5. Improve maintainability where cheap.
+6. Prefer validation clarity over elegance.
+
+## Selected Plan Contract
+
+An approval-ready plan or selected model must include:
+
+- objective function;
+- known constraints by source: explicit, discovered, inferred, assumptions;
+- decision variables and chosen values;
+- affected files or surfaces;
+- feasible and rejected candidates;
+- selected plan;
+- binding constraints;
+- validation plan and proof required;
+- execution implications;
+- guardrail variables when durable run or loop state will enforce scope;
+- residual risk.
+
+If a field is irrelevant, say `none` or give a short reason. Do not hide constraints inside prose.
+
+## Re-Optimization
+
+Re-optimize when new evidence changes system state, feasible region, hard constraints, selected-plan binding constraints, selected decisions, or validation feasibility.
+
+Do not re-optimize merely because another plan feels more elegant.

package/skills/kkt-loop/references/kkt-kernel.md

@@ -0,0 +1,58 @@
+# KKT Kernel
+
+This is the mandatory operating contract for every KKT skill. It should stay short enough to read on every invocation.
+
+## Invariants
+
+- Capture user meaning before modeling.
+- Discover repo facts before asking the user for file names, routes, schemas, tests, commands, or config.
+- Treat prior host-agent or plan-mode output as scaffold, not truth.
+- Check hard constraints before comparing plans.
+- Pick the smallest feasible plan that satisfies the user's objective and protects existing contracts.
+- Get approval before mutation when the skill is in a planning, model, run, or loop gate.
+- Validate with evidence before completion.
+- Re-optimize only when new evidence changes facts, constraints, feasible plans, selected decisions, or validation feasibility.
+
+## Question Filter
+
+Before asking, classify the unknown:
+
+- `discoverable_fact`: inspect the repo, docs, tests, config, schemas, routes, logs, or issues.
+- `reversible_default`: choose the conservative low-risk default and label it as an assumption.
+- `owner_decision`: ask when the answer changes product behavior, scope, risk, approval, destructive actions, external dependencies, credentials, paid services, or execution mode.
+- `blocking_unknown`: stop when no conservative default keeps the hard constraints feasible.
+
+## Core Model
+
+Every KKT model or approval-ready plan needs:
+
+- objective function;
+- known constraints, with explicit, discovered, inferred, and assumed sources separated;
+- decision variables with allowed domains and chosen values;
+- files, modules, APIs, workflows, docs, migrations, or operational surfaces expected to change;
+- candidate plans, with infeasible options rejected before comparison;
+- selected feasible plan and why it dominates alternatives;
+- binding constraints that shaped the selected plan;
+- validation plan and evidence required;
+- residual risk.
+
+## Discovery Rules
+
+- Use `git` for repository boundaries, status, diffs, history, and changed-path scope.
+- Use `rg` immediately for broad text and file discovery.
+- Use `ast-grep` immediately when syntax matters and text search would be ambiguous.
+- Use language-native tools when they reveal package boundaries, types, route maps, generated-code boundaries, or test contracts.
+- If `ast-grep` is unavailable in an already-installed environment, record the setup gap and do not claim AST-level certainty from text search alone.
+- Record important negative searches when they shape the selected plan.
+
+## Completion Certificate
+
+Finish with:
+
+```text
+Objective: satisfied / not satisfied
+Hard constraints: satisfied / violations listed
+Binding constraints: respected / changed
+Validation evidence: commands, checks, artifacts, or reason validation was not possible
+Residual risk: concise notes
+```

package/skills/kkt-loop/references/layered-modeling-methods.md

@@ -0,0 +1,101 @@
+# Layered Modeling Methods
+
+Use this catalog for `$kkt-model`, `$kkt-loop`, or unusually complex `$kkt` work. Do not apply every method to every request.
+
+Every layer must produce enough output for the next layer to continue without hidden session context. Load `schemas.md` only when a copyable layer-contract shape is needed.
+
+## Profiles
+
+### Plan Profile
+
+Use for ordinary `$kkt` implementation work:
+
+- compact intent frame;
+- local discovery with `git`, `rg`, and structural search when useful;
+- hard-constraint feasibility gate;
+- lexicographic ranking of feasible plans;
+- approval before implementation;
+- validation certificate.
+
+Keep formal method names out of normal output unless they explain a material tradeoff.
+
+### Deep Profile
+
+Use for `$kkt-model` and complex planning:
+
+- ask targeted owner-decision questions after quick inspection;
+- build a discovery map with evidence confidence;
+- select and record one intent, discovery, and modeling method;
+- compare candidate models and reject infeasible options first;
+- explain binding constraints, sensitivity, and execution implications.
+
+Fallback set: `goal_anti_goal`, `traceability_matrix`, `lexicographic`. Use it when specialized methods do not materially improve reliability.
+
+### Loop Profile
+
+Use for `$kkt-loop`:
+
+- front-load deeper modeling before execution;
+- write durable state through the CLI;
+- require approval before workspace execution or goal launch;
+- continue from CLI state and evidence;
+- re-optimize only when new evidence changes feasibility, constraints, objective fit, or validation feasibility.
+
+## Intent Methods
+
+Purpose: turn rough user input into a meaning frame discovery can test against the repo.
+
+- Goal / anti-goal: desired outcome and explicit non-goals.
+- WHY / HOW ladder: find the real objective; ask HOW only when it clarifies desired behavior.
+- Obstacle questions: identify interpretations that would be unacceptable, too broad, or aimed at the wrong workflow.
+- Example / counterexample: use when examples would prevent a materially wrong interpretation.
+- Tradeoff prompt: ask only when competing priorities change the model.
+- Owner-decision filter: classify possible questions as discoverable facts, reversible defaults, owner decisions, or blocking unknowns.
+
+Question budget:
+
+- clear task: 0-1 questions;
+- medium ambiguity: 1-3 targeted questions;
+- large, high-risk, or ambiguous work: short Socratic pass after quick inspection.
+
+## Discovery Methods
+
+Purpose: convert intent into inspected facts and traceable system context.
+
+- Naive/local discovery: direct `git`, `rg`, file reads, and tests for obvious locality.
+- Traceability matrix: map intent to files, modules, routes, schemas, tests, docs, config, and runtime boundaries.
+- Coupling map: identify callers, public interfaces, state owners, side effects, and downstream contracts.
+- DSM-lite: use a small dependency matrix when several modules/workflows make blast radius unclear.
+- Structural discovery: use `ast-grep` when syntax matters.
+
+Discovery output must distinguish observed facts, inferred constraints, assumptions, unknowns, validation paths, unavailable preferred tools, fallback notes, and important negative searches.
+
+## Modeling Methods
+
+Always apply the hard-constraint feasibility gate before ranking.
+
+| Decision shape | Method | Use when |
+| --- | --- | --- |
+| Normal implementation choice | Lexicographic ranking | Priorities are clear and correctness / safety / contracts outrank lower preferences. |
+| Branching facts determine feasibility | Decision tree | Repo facts eliminate paths. |
+| Staged transition or rollout | Shortest path | There are real states, transitions, costs, and forbidden states. |
+| Comparable feasible options | Ordinal MCDA | Alternatives differ across blast radius, maintainability, validation clarity, speed, or reversibility. |
+| User priorities are unclear | AHP-style pairwise questions | Risk, speed, migration, or architecture preference determines the choice. |
+| No feasible option clearly dominates | Outranking shortlist | Architecture choices need a defensible shortlist rather than a forced winner. |
+
+Do not invent numeric scores for subjective criteria. Prefer ordinal labels unless the user supplies actual weights.
+
+## Execution Methods
+
+- Smallest feasible step: edit only the surfaces selected by the model.
+- Contract-preserving change: preserve public APIs, data contracts, security boundaries, and user non-goals unless approval changed them.
+- Re-optimization trigger: stop when new evidence changes feasibility, selected decisions, or validation feasibility.
+
+## Validation Methods
+
+- Acceptance-criteria map: map each criterion to evidence.
+- Hard-constraint audit: explicitly check feasibility constraints.
+- Binding-constraint audit: verify the selected plan still respects the constraints that shaped it.
+- Residual-risk register: list claims not proven by validation.
+
+Final validation must include commands, checks, artifacts, unavailable checks, residual risk, and a completion certificate.

package/skills/kkt-loop/references/plan-assimilation.md

@@ -0,0 +1,46 @@
+# Plan Assimilation
+
+Use this only when KKT is invoked after a host agent or default plan mode has already produced a plan.
+
+## Rule
+
+Prior plan text is an untrusted scaffold. Consume whatever exists, extract useful signals, verify discoverable claims, and rebuild the KKT model from KKT's own intent, discovery, constraints, decision variables, selected plan, and validation proof.
+
+Do not ask the user to reformat prior plan output.
+
+## Checklist
+
+1. Preserve the original user request and explicit user constraints.
+2. Extract signals from the prior plan:
+   - proposed goal and steps;
+   - suspected files, modules, APIs, schemas, routes, tests, docs, or operational surfaces;
+   - stated or implied constraints;
+   - validation suggestions;
+   - open questions and risk signals.
+3. Classify each signal:
+   - `explicit_user_input`;
+   - `plan_assumption`;
+   - `discoverable_fact`;
+   - `candidate_decision`;
+   - `candidate_constraint`;
+   - `candidate_validation`;
+   - `unknown_or_ambiguous`.
+4. Verify discoverable facts through repo inspection before using them as facts.
+5. Keep unverified claims as assumptions or candidates, never as discovered facts.
+6. Add missing KKT structure: objective, constraints, decision variables, candidate feasibility, selected plan, binding constraints, guardrails, and validation proof.
+7. Reject or revise the prior plan when it violates hard constraints, skips cheaper feasible paths, or names validation that does not exist.
+
+## Anti-Anchoring Checks
+
+- Which prior-plan claims were verified?
+- Which claims remain assumptions?
+- Which constraints or decision variables did the plan miss?
+- What smaller or safer feasible plan exists?
+- What validation proof would certify the selected plan?
+
+## Guardrails
+
+- Do not enforce a schema on host plan-mode output.
+- Do not treat prior-plan file names, routes, commands, or architecture claims as facts before inspection.
+- Do not rubber-stamp the prior plan as the selected KKT plan.
+- Do not ask the user for repo facts the discovery layer can verify.