@dannylee1020/kkt 0.5.0

package/skills/kkt-run/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-run/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-run/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-run/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.

package/skills/kkt-run/references/schemas.md

@@ -0,0 +1,231 @@
+# KKT Schemas
+
+Optional reference for copyable shapes. Do not load this on every invocation; use it when writing or auditing durable KKT state, layer contracts, plan-assimilation output, discovery tooling output, or guardrails.
+
+## Layer Contract
+
+```yaml
+layer_contract:
+  layer:
+  status: pending | complete | blocked
+  method_used:
+  inputs_consumed:
+  outputs:
+  decisions:
+  assumptions:
+  unknowns:
+  artifact_refs:
+  next_layer_readiness:
+```
+
+## Optimized Plan
+
+```yaml
+optimized_plan:
+  objective_function:
+  known_constraints:
+    explicit:
+    discovered:
+    inferred:
+    assumptions:
+  decision_variables:
+    - name:
+      allowed_domain:
+      chosen_value:
+      rationale:
+  files_to_modify:
+    - path_or_surface:
+      change_type:
+      rationale:
+  constraint_functions:
+    hard:
+      - name:
+        predicate:
+        source:
+        status:
+    soft:
+      - name:
+        preference:
+        source:
+        status:
+  candidates:
+    feasible:
+    rejected:
+  selected_plan:
+  binding_constraints:
+  validation_plan:
+  validation_proof:
+  execution_implications:
+  guardrail_variables:
+  residual_risk:
+```
+
+## Plan Assimilation
+
+```yaml
+plan_assimilation:
+  source:
+    original_request:
+    prior_plan_text:
+  extracted_signals:
+    proposed_goal:
+    proposed_steps:
+    suspected_surfaces:
+    implied_constraints:
+    validation_suggestions:
+    open_questions:
+    risk_signals:
+  classification:
+    explicit_user_input:
+    plan_assumption:
+    discoverable_fact:
+    candidate_decision:
+    candidate_constraint:
+    candidate_validation:
+    unknown_or_ambiguous:
+  verification:
+    verified_facts:
+    rejected_claims:
+    assumptions_carried:
+    searches_or_evidence:
+  next_layer_readiness:
+```
+
+## Discovery Tooling
+
+```yaml
+discovery_tooling:
+  available:
+    core:
+    preferred:
+    optional:
+    language_native:
+  unavailable:
+  searches:
+    - tool:
+      purpose:
+      query_or_pattern:
+      paths:
+      result_summary:
+      confidence:
+  negative_searches:
+    - tool:
+      query_or_pattern:
+      paths:
+      implication:
+  fallback_notes:
+```
+
+## Execution Contract
+
+```yaml
+execution_contract:
+  acceptance_criteria:
+  validation_plan:
+  evidence_required:
+  stop_conditions:
+  continuation_policy:
+```
+
+## kkt.yaml
+
+```yaml
+schema_version: 1
+workspace_type: plan | model | run | loop
+profile: plan | model | run | loop
+status: initialized | modeling | approved | executing | validating | complete | blocked
+active_layer: intent | discovery | modeling | execution | validation
+layers:
+  intent:
+    status: pending | complete | blocked
+    method: pending | goal_anti_goal | why_how | obstacle_questions | pairwise_questions
+    summary: ""
+    artifact: intent.md
+  discovery:
+    status: pending | complete | blocked
+    method: pending | naive | traceability_matrix | coupling_map | dsm_lite
+    summary: ""
+    artifact: discovery.md
+  modeling:
+    status: pending | complete | blocked
+    method: pending | lexicographic | decision_tree | shortest_path | ordinal_mcda | pairwise_ahp | outranking
+    summary: ""
+    artifact: model.md
+  execution:
+    status: pending | complete | blocked
+    method: pending | smallest_feasible_step | contract_preserving_change
+    summary: ""
+    artifact: plan.md
+  validation:
+    status: pending | complete | blocked
+    method: pending | acceptance_map | hard_constraint_audit | binding_constraint_audit
+    summary: ""
+    artifact: evidence.md
+method_invocations: []
+decision_log: []
+planning_contract:
+  objective_function:
+  files_to_modify:
+  constraint_functions:
+  decision_variables:
+  validation_proof:
+artifact_refs:
+approval:
+  required: true
+  status: not_required | pending | approved | rejected
+  approved_scope:
+stop_conditions: []
+loop_state:
+  current_task: ""
+  tasks: []
+  acceptance_criteria: []
+  evidence: []
+  stop_conditions: []
+```
+
+## guardrails.json
+
+```json
+{
+  "schema_version": 1,
+  "source": {
+    "workspace_type": "model",
+    "workspace": ".kkt/model/<slug>",
+    "request": ""
+  },
+  "constraints": [
+    {
+      "id": "stable-contract",
+      "kind": "architecture",
+      "severity": "block",
+      "statement": "Preserve the selected model's public contract.",
+      "allowed_paths": ["internal/workflow/**"],
+      "blocked_paths": ["dist/**"]
+    }
+  ],
+  "change_bounds": {
+    "allowed_paths": ["internal/workflow/**"],
+    "blocked_paths": [".git/**", ".env*", "dist/**"],
+    "require_explicit_approval_outside_allowed": true
+  },
+  "workflow": {
+    "execution_mode": "run",
+    "requires_approval_before_mutation": true,
+    "requires_validation_before_done": true
+  },
+  "validation": {
+    "acceptance_criteria": [],
+    "required_commands": [],
+    "evidence_required": ["scope audit confirms only allowed paths changed"]
+  },
+  "drift_policy": {
+    "block_on": [
+      "missing_approval",
+      "empty_allowed_paths",
+      "changed_blocked_path",
+      "validation_failed"
+    ],
+    "warn_on": []
+  }
+}
+```

package/skills/kkt-run/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.