@dannylee1020/kkt 0.5.0

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

@@ -0,0 +1,76 @@
+---
+name: kkt-model
+description: Deep constrained optimization modeling for coding and product-engineering decisions. Use when a coding agent should capture user meaning, discover repo constraints and validation paths, inspect the system, identify objectives, system state, decision variables, domains, hard and soft constraint contracts, selected-plan binding constraints, execution-contract implications, multiple feasible models or architectures, sensitivity analysis, and interactive user tradeoffs before any implementation.
+license: Apache-2.0
+---
+
+# KKT Model
+
+Use this skill when the deliverable is a model, decision brief, or implementation-ready recommendation rather than code. It is for architecture choices, feature shaping, complex implementation options, scope negotiation, and high-impact tradeoffs.
+
+Read `references/kkt-kernel.md` and `references/feature-optimization-model.md` before acting. Read `references/layered-modeling-methods.md` when choosing methods, which is normal for deep modeling. Read `references/state-contract.md` when durable model state is useful. 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.
+
+## Core Rule
+
+Stay non-mutating by default. Intake before modeling. Discovery before asking for repo facts. Select the modeling method that fits the decision shape. Ask only for product, risk, scope, approval, or execution-mode choices that cannot be resolved from inspection or conservative reversible defaults.
+
+## CLI-First Workflow
+
+Use the `kkt` CLI whenever durable model state is useful. The skill owns modeling judgment; the CLI owns workspace creation, state reads, artifact recording, validation, and completion.
+
+```text
+kkt start model "<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 set '<constraints and path bounds JSON>'
+kkt guardrails validate
+kkt validate
+kkt done
+```
+
+If `kkt` is missing and durable model state is needed, stop and ask the user to install or upgrade KKT. Do not hand-write replacement state.
+
+## 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 before modeling: extract signals, classify each claim, verify discoverable facts, and treat unverified claims as assumptions or candidates.
+3. 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 using WHY/HOW, obstacle, example/counterexample, or pairwise tradeoff prompts.
+4. Inspect relevant code, docs, configs, schemas, routes, tests, UI, infra, issues, or logs before choosing a 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.
+5. Separate explicit requirements, prior-plan assumptions, discovered facts, inferred constraints, assumptions, unknowns, and owner decisions.
+6. Build a discovery map when the decision crosses modules, workflows, contracts, or architecture boundaries.
+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 shared optimization model from intent and discovery: objective function, system state, files to modify or affected surfaces, constraint functions, decision variables, hard/soft constraints, candidates, feasibility, binding constraints, sensitivity, and execution implications.
+9. Produce 2-4 candidate models when meaningful alternatives exist; eliminate infeasible models before comparing feasible ones.
+10. Compare feasible models by hard-constraint satisfaction, binding constraints, blast radius, maintainability, validation clarity, reversibility, and fit with user intent.
+11. Ask the user only for unresolved owner decisions; otherwise select the best feasible model.
+12. Translate the selected model into guardrail variables: constraints, allowed paths, blocked paths, validation evidence, and required commands.
+13. Record durable output with `kkt intent --method`, `kkt discovery --method`, `kkt model --method`, `kkt guardrails set`, `kkt guardrails validate`, and `kkt validate` when a workspace exists.
+
+## End States
+
+End with one of:
+
+- `Selected model`: one feasible model is recommended and ready for implementation.
+- `Decision needed`: the smallest user decisions required to select a model.
+- `No feasible model`: the hard constraints that block feasibility and the relaxation that would restore it.
+
+For each serious alternative, include the method used, objective fit, decision-variable assignments, hard-constraint status, binding constraints, tradeoffs, execution-contract implications, residual risks, and when to choose it.
+
+Decision briefs must include the optimized-plan reasoning from `references/feature-optimization-model.md`: objective function, known constraints, files to modify or affected surfaces, forbidden files or surfaces, constraint functions, decision variables, candidate feasibility, selected plan, binding constraints, validation proof, execution implications, and residual risk.
+
+## Durable Output
+
+For substantial modeling work, use project-root `.kkt/model/<slug>/` through `kkt` commands. `kkt.yaml` is the state index; Markdown files carry rich intent, discovery, and modeling context. `guardrails.json` carries the modeled constraints and path bounds that `$kkt-run` or `$kkt-loop` will enforce before mutation. Load `references/schemas.md` only when a full copyable shape is needed. Do not create execution files unless switching to `$kkt-run` or `$kkt-loop`.
+
+## Do Not
+
+- Do not modify code unless the user explicitly switches from modeling to implementation.
+- Do not invent numeric scores for subjective criteria.
+- Do not collapse materially different architectures into one vague plan.
+- Do not ask for user input before inspecting discoverable context.
+- Do not choose a method because it sounds rigorous; choose it because the decision shape calls for it.
+- Do not recommend a model without selected-plan binding constraints and execution implications.
+- Do not finish a durable model without guardrail constraints and non-empty allowed paths.

package/skills/kkt-model/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-model/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-model/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
+```