@dannylee1020/kkt 0.5.0

package/skills/kkt/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: kkt
+description: Constrained optimization workflow for ordinary coding requests. Use when a coding agent should capture user meaning, discover repo constraints and validation paths, build a mathematical-style optimization model, derive an execution contract, select a feasible implementation plan, execute the change, validate with evidence, and finish with a constraint audit.
+license: Apache-2.0
+---
+
+# KKT
+
+Use this skill for ordinary coding work that needs stricter planning than default plan mode. Apply constrained optimization as a discipline: choose the best feasible implementation given what must stay true.
+
+Read `references/kkt-kernel.md` before acting. Read `references/feature-optimization-model.md` when building the compact model. Read `references/state-contract.md` only when durable state is useful. Read `references/plan-assimilation.md` only when prior plan text exists. Read `references/discovery-tooling.md` during non-trivial discovery or structural search. Read `references/layered-modeling-methods.md` only when method selection beyond the plan profile is needed. Read `references/schemas.md` only when a full copyable state, guardrail, or layer-output shape is needed.
+
+## Core Rule
+
+Intake before modeling. Discovery before asking for repo facts. Model before editing. Show the final modeling result and get explicit user approval before implementation. Finish only with validation evidence or an explicit blocker.
+
+## CLI-First Workflow
+
+Use the `kkt` CLI whenever durable state is useful. The skill owns reasoning policy; the CLI owns state creation, reads, mutation, approval, evidence, validation, and completion.
+
+```text
+kkt start plan "<user request>"
+kkt status [--json]
+kkt next
+kkt model "<objective_function, files_to_modify, constraint_functions, decision_variables, validation_proof, and selected compact model>"
+kkt approve "<approved scope>"
+kkt evidence "<validation evidence>"
+kkt validate [--run]
+kkt done
+```
+
+If `kkt` is missing and durable state is needed, stop and ask the user to install or upgrade KKT. Do not hand-write replacement state. Use `kkt validate --run` when guardrails define required commands; `kkt evidence` alone is narrative evidence, not command proof.
+
+## Workflow
+
+1. Capture intent: user goal, desired behavior, user-visible success, scope boundary, examples, priority signals, and explicit user constraints.
+2. If prior plan text exists, assimilate it as untrusted scaffold: extract signals, classify claims, verify discoverable facts, and keep unverified claims as assumptions or candidates.
+3. 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.
+4. Inspect relevant code, docs, tests, config, schemas, routes, UI, infra, logs, or issues before forming the model. Use `rg` directly for broad text and file discovery, `ast-grep` directly for structural search when syntax matters, `git` for repository state, and language-native commands when they provide stronger evidence.
+5. Separate explicit user statements, prior-plan assumptions, discovered facts, inferred constraints, assumptions, unknowns, and owner decisions.
+6. Build a compact model: objective function, system state, files to modify, constraint functions, decision variables, hard/soft constraints, feasible plans, selected plan, binding constraints, and sensitivity.
+7. Derive the execution contract: acceptance criteria, validation plan, evidence required, and stop conditions.
+8. Reject infeasible plans, then choose the best feasible plan by this order: user request, correctness/security/data/public contracts, blast radius, existing architecture, maintainability, validation clarity.
+9. Show the final modeling result and wait for approval before editing.
+10. Execute the approved plan with focused edits, then validate with evidence and finish with a constraint audit.
+
+## Output Discipline
+
+For small tasks, keep the model brief and avoid durable state unless it helps. For durable plan-tier state, use project-root `.kkt/kkt.yaml` through `kkt` commands; do not hand-edit `kkt.yaml` as the primary workflow operation. Load full schemas only when writing or auditing durable state. Switch to `$kkt-model` for deeper non-mutating modeling, `$kkt-run` to implement a completed model with guardrails, or `$kkt-loop` for long-running continuation.
+
+Before implementation, expose a compact optimized plan: objective function, known constraints, files to modify, constraint functions, decision variables, selected plan, rejected alternatives, binding constraints, validation proof plan, and residual risk. Keep formal method names hidden unless they explain a material tradeoff.
+
+Final audit shape:
+
+```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
+```
+
+## Stop Conditions
+
+Stop and ask before continuing when no feasible plan satisfies hard constraints, approval is missing, destructive action is required, credentials/secrets/external access/paid services are required, feasible plans differ mainly by product intent, or continuing expands scope.
+
+## Do Not
+
+- Do not use fake numeric scores for subjective qualities.
+- Do not treat the first plausible plan as selected before feasibility checks.
+- Do not edit before the final modeling result is approved.
+- Do not silently follow existing patterns that appear wrong; flag them.
+- Do not make broad refactors unless required by the model.
+- Do not finish without validation evidence or an explicit validation limitation.

package/skills/kkt/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/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/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/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/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/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": []
+  }
+}
+```