@dannylee1020/kkt 0.5.0

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

@@ -0,0 +1,62 @@
+---
+name: kkt-run
+description: Execute an existing KKT model with deterministic drift guardrails. Use when a coding agent should pick up a completed kkt-model workspace, preserve the optimized model and guardrail contract, check model-readiness before mutation, implement the selected plan, validate with evidence, and finish without the long-running kkt-loop continuation machinery.
+license: Apache-2.0
+---
+
+# KKT Run
+
+Use this skill when modeling is already complete and the user wants implementation now. It is the execution tier between `$kkt-model` and `$kkt-loop`: richer than a compact plan, but lighter than a durable long-running loop.
+
+Read `references/kkt-kernel.md` and `references/state-contract.md` before acting. Read `references/feature-optimization-model.md` only when the completed model must be interpreted, repaired, or checked for drift. Read `references/plan-assimilation.md` only when the selected model used prior-plan assimilation. Read `references/discovery-tooling.md` only when verifying drift or missing facts. Read `references/layered-modeling-methods.md` only when reopening an incomplete model. Read `references/schemas.md` only when auditing full state or guardrail shapes.
+
+## Core Rule
+
+Run only the selected model. Before edits, load the model workspace, validate the guardrail contract, run the model-ready judge checkpoint, show the execution contract, and get explicit approval. During implementation, use the pre-mutation and finalize checkpoints to catch drift before changing files or finishing.
+
+## CLI-First Workflow
+
+Use the `kkt` CLI as the workflow control path. The skill owns implementation judgment; the CLI owns deterministic workspace creation, guardrail state, checkpoint results, evidence, validation, and completion.
+
+```text
+kkt run from-model [model-workspace]
+kkt status [--json]
+kkt show model
+kkt guardrails validate
+kkt judge --checkpoint model-ready --json
+kkt approve "<approved scope>"
+kkt judge --checkpoint pre-mutation --json
+kkt plan "<execution contract>"
+kkt progress "<progress update>"
+kkt evidence --command "<validation command>" "<validation evidence>"
+kkt validate --run
+kkt judge --checkpoint finalize --json
+kkt done
+```
+
+If no completed model workspace exists, switch back to `$kkt-model` instead of inventing one. If the work needs continuation, autonomous execution, multiple resumptions, task queues, or event replay, switch to `$kkt-loop`.
+
+## Workflow
+
+1. Resolve or create the run workspace with `kkt run from-model [model-workspace]`.
+2. Read `kkt status --json`, `kkt show model`, `kkt show guardrails`, and `kkt guardrails validate`.
+3. Run `kkt judge --checkpoint model-ready --json`. Treat `block` as a hard stop, `warn` as a contract-quality issue to repair before risky edits, and `allow` as permission to seek approval. This checkpoint blocks if modeled constraints or allowed path bounds are missing.
+4. Confirm whether the selected model used plan assimilation. Preserve the model's classification of prior-plan claims and do not promote unverified prior-plan assumptions during execution.
+5. Show the user the execution contract: selected model, hard constraints, allowed paths, blocked paths, validation commands, and residual risk.
+6. Get explicit approval and record it with `kkt approve`.
+7. Before modifying files, run `kkt judge --checkpoint pre-mutation --json`; it blocks if existing git changes are outside `allowed_paths` or inside `blocked_paths`.
+8. Implement the smallest change that satisfies the selected model. Do not expand scope, add unrelated cleanup, or change the model unless new evidence invalidates feasibility.
+9. Record progress and validation evidence with CLI commands. Use `kkt evidence` for narrative evidence, not as deterministic command proof.
+10. Run `kkt validate --run` when guardrails list required commands, then run `kkt judge --checkpoint finalize --json` before `kkt done`.
+
+## Stop Conditions
+
+Stop before editing when the model-ready checkpoint blocks, guardrails are missing or invalid for the intended change, approval is missing, changed files are outside allowed paths, changed files hit blocked paths, the selected model no longer matches repo facts, destructive action is required, credentials/secrets/external access/paid services are required, or implementation would expand beyond the model.
+
+## Do Not
+
+- Do not use `$kkt-run` as a substitute for modeling.
+- Do not execute an incomplete or blocked model workspace.
+- Do not continue past a blocking judge result.
+- Do not create loop tasks or rely on `events.jsonl`; use `$kkt-loop` for continuation.
+- Do not silently change the selected model during implementation.

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