mdkg 0.4.2 → 0.5.1

package/dist/init/skills/default/pursue-mdkg-loop/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: pursue-mdkg-loop
+description: Pursue a selected mdkg loop by exhausting authorized linked work lanes, recording blocker recovery, and closing only when the loop definition of done is satisfied or explicitly waived.
+tags: [stage:execute, writer:orchestrator, mdkg, loop, recursive]
+version: 0.2.0
+authors: [mdkg]
+links: [AGENT_START.md, CLI_COMMAND_MATRIX.md]
+---
+
+# Goal
+
+Move one durable mdkg loop forward without prematurely closing, blocking, or
+shrinking the loop definition of done.
+
+## When To Use
+
+- A user has selected or named a `type: loop` node.
+- A reusable audit, planning, or implementation process should work across
+  several linked goals, tasks, tests, spikes, proposals, checkpoints, or
+  decisions.
+- A loop should keep making progress after one branch hits a decision point.
+
+## Inputs
+
+- Repo root
+- Loop id, qid, or template alias
+- Loop node, required evidence lanes, child refs, linked goals, output refs,
+  decision refs, approval refs, and blocker policy
+- Current user constraints, available approvals, and stop conditions
+
+## Steps
+
+1. Resolve the loop with `mdkg loop show <loop> --json`.
+2. Inspect identity-scoped readiness with `mdkg loop plan <loop> --json`.
+3. Route with `mdkg loop next <loop> --json`; prefer its authorized child or
+   recovery selection unless current graph evidence justifies an override.
+4. Build context with `mdkg pack <loop> --pack-profile concise --dry-run --stats`.
+5. Build a completion matrix: lane, required/optional, linked refs, allowed
+   actions, needed evidence, status, blockers, recovery node, and accepted
+   decision or waiver.
+6. Surface pre-run questions before beginning when the loop template declares
+   external calls, privileged tools, multi-agent delegation, publish, deploy,
+   provider, or policy-sensitive decisions.
+7. Treat read-only and planning loops as pre-approved for low-risk local work:
+   source/doc/mdkg inspection, local discovery commands, local tests/builds that
+   may write caches or generated outputs outside committed source, mdkg evidence
+   nodes, and provisional triage.
+8. Do not treat read-only/planning preapproval as permission for functional
+   source changes, push/publish/tag/deploy, external metadata-disclosing calls,
+   privileged tools, or subagent delegation unless approval is explicit.
+9. Work the linked graph, not just the first branch. If one branch is blocked,
+   record blocker recovery and continue another authorized branch.
+10. Classify blockers as `recoverable_now`, `branch_blocked`,
+   `definition_blocking`, or `residual`.
+11. For non-trivial blockers, create or update a source-grounded spike, proposal
+   or open-question section with at least three viable paths, one recommended
+   path, and blocker evidence.
+12. Continue while any authorized, in-scope, linked work remains actionable.
+13. Bind answers, approvals, evidence, and waivers to stable identities with
+    `question_answer_refs`, `action_approval_refs`, `evidence_lane_refs`,
+    `lane_waiver_decision_refs`, and `lane_waiver_approval_refs`. A waiver
+    requires both an accepted decision and verified approval for the same lane.
+14. Mark the loop done only when every required lane is complete or explicitly
+    waived and the loop body explains why the definition of done is satisfied.
+15. Mark the loop blocked only when no authorized, useful, in-scope linked work
+    remains across the loop graph and the loop records required decisions,
+    follow-up work, and unblock paths. Confirm
+    `exhaustion.whole_loop_blocked: true` from `mdkg loop next --json` against
+    current graph state before stopping.
+
+## Outputs
+
+- Completion matrix for the loop
+- Evidence recorded on linked children and summarized on the loop
+- Provisional decisions, open questions, approval requests, and residual
+  follow-up work
+- A clear stop reason: continue, done, blocked, or waiting for approval
+
+## Required Capabilities
+
+- mdkg loop inspection and packing
+- mdkg graph search/show/validate
+- Source and documentation review
+- Local command execution within the loop's authorization
+- Proposal, decision, spike, task, test, and checkpoint authoring
+
+## Resources Touched
+
+- `.mdkg/work/<loop>.md`
+- Linked child nodes under `.mdkg/work/`
+- Linked design and decision docs under `.mdkg/design/`
+- Local source/docs/test files only for read-only inspection unless the loop is
+  explicitly write-capable
+
+## Validation Checks
+
+- `git status --short --branch`
+- `mdkg loop show <loop> --json`
+- `mdkg loop plan <loop> --json`
+- `mdkg loop next <loop> --json`
+- `mdkg pack <loop> --pack-profile concise --dry-run --stats`
+- `mdkg validate --changed-only --json`
+- `mdkg validate --summary --json --limit 20`
+- Loop-specific local checks from the template or linked child nodes
+
+## Closeout Evidence
+
+- Completion matrix with every required lane classified
+- Evidence refs for completed lanes
+- Decision refs or approval refs for accepted waivers
+- Follow-up nodes split into definition-blocking and residual work
+- Validation receipts
+- A loop summary that states why the loop is done, blocked, or continuing
+
+## Safety
+
+- Do not mark a loop done merely because follow-up nodes were created.
+- Do not mark a loop blocked while authorized linked work remains actionable.
+- Do not shrink the loop definition of done without a durable decision or
+  approval record.
+- Treat external advisory checks, provider calls, publish/deploy actions, and
+  multi-agent delegation as approval-gated unless the loop has explicit
+  pre-approval.
+- Communicate provisional decisions and open questions to the human or
+  higher-level orchestrator before treating them as accepted.
+
+## Failure Handling
+
+- If pre-run approvals are missing, record the decision request and continue
+  authorized local lanes.
+- If all branches are blocked, create or update spike/proposal/decision-request
+  nodes before marking the loop blocked.
+- If validation fails, keep the loop open and record the failing lane.
+- If the loop template lacks required evidence lanes, create a template
+  hardening task instead of silently closing the loop.
+
+## Related Manifests
+
+- Future loop-runner or orchestrator agent manifests.
+
+## Projection Targets
+
+- `.agents/skills/pursue-mdkg-loop`
+- `.claude/skills/pursue-mdkg-loop`
+- `assets/init/skills/default/pursue-mdkg-loop`
+
+## Open Questions
+
+- Should mdkg add first-class approval nodes later, or keep approvals as typed
+  decision refs plus checkpoint, receipt, and external approval refs?

package/dist/init/templates/default/loop.md

@@ -0,0 +1,160 @@
+---
+id: {{id}}
+type: loop
+title: {{title}}
+status: {{status}}
+priority: {{priority}}
+loop_mode: planning
+loop_role: scoped
+scope_refs: []
+scope_description: Set the repo folder goal or project area this loop governs.
+template_refs: []
+materialization_mode: default_children
+child_refs: []
+pre_run_questions: [scope_authority, local_cache_writes_approved, external_calls_approved]
+question_answer_refs: []
+pre_approved_actions: [read_source, run_local_discovery, create_mdkg_evidence]
+approval_gated_actions: [external_calls]
+required_actions: [read_source, run_local_discovery, create_mdkg_evidence]
+requested_actions: [read_source, run_local_discovery, create_mdkg_evidence]
+prohibited_actions: [functional_changes, push_publish_deploy]
+action_approval_refs: []
+evidence_lanes: [required_evidence, blocker_recovery, closeout_matrix]
+evidence_lane_refs: []
+lane_waiver_refs: []
+lane_waiver_decision_refs: []
+lane_waiver_approval_refs: []
+run_refs: []
+decision_refs: []
+output_refs: []
+approval_refs: []
+evaluation_refs: []
+definition_of_done: Loop required evidence lanes are complete or explicitly waived, and the closeout matrix records why the loop is done, blocked, or continuing.
+blocker_policy: spike_proposal_recommendation_continue
+epic: {{epic}}
+parent: {{parent}}
+prev: {{prev}}
+next: {{next}}
+tags: []
+owners: []
+links: []
+artifacts: []
+relates: []
+blocked_by: []
+blocks: []
+refs: []
+context_refs: []
+evidence_refs: []
+aliases: []
+skills: [pursue-mdkg-loop]
+created: {{created}}
+updated: {{updated}}
+---
+
+# Operating Model
+
+Describe the reusable process this loop represents and the work it should coordinate.
+
+# Scope
+
+State the repository, folder, goal, or project area this loop applies to.
+
+# Definition Of Done
+
+Define the high bar this loop must reach before it can close. A loop must not
+close merely because follow-up nodes were created.
+
+# Required Evidence Lanes
+
+List the lanes the loop must complete or explicitly waive.
+
+| Lane | Required | Evidence Needed | Status | Blocker | Recovery Node | Decision Or Waiver |
+| --- | --- | --- | --- | --- | --- | --- |
+| example lane | yes | source-grounded evidence | todo | none | none | none |
+
+# Pre-Run Questions
+
+Ask these before execution when the loop needs configuration or approval.
+
+- Which scope is authoritative for this run?
+- Are external network, provider, registry, security, browser, or multi-agent
+  calls approved?
+- Are local test/build commands approved when they write caches or generated
+  outputs outside committed source?
+
+# Pre-Approved Read-Only Actions
+
+- Read source, docs, mdkg graph, package metadata, configs, and tests.
+- Run local discovery commands and local tests/builds when allowed by the loop
+  or user.
+- Create mdkg evidence, spike, proposal, task, test, checkpoint, and
+  open-question nodes.
+- Make provisional triage decisions and record them for human or orchestrator
+  approval.
+
+# Approval-Gated Actions
+
+- Functional source, docs, template, generated command, or runtime changes.
+- Push, publish, tag, deploy, DNS, analytics, provider, or external registry
+  actions.
+- External calls that disclose repository, package, dependency, user, or
+  provider metadata.
+- Subagent or privileged tool delegation unless explicitly approved.
+
+# Child Node Materialization
+
+- Default child nodes to create immediately.
+- Planning-only or no-child mode expectations.
+
+# Template Lineage
+
+- Template source.
+- Forked scope.
+- Local specialization.
+- Reusable improvements to promote back.
+
+# Run And Evidence Model
+
+- Run records or event streams.
+- Evidence, observations, findings, decisions, outputs, and receipts.
+
+# Blocker Continuation Policy
+
+When a branch is blocked, classify it as `recoverable_now`, `branch_blocked`,
+`definition_blocking`, or `residual`.
+
+- `recoverable_now`: request approval, use an approved local proof path, or run
+  an already authorized tool.
+- `branch_blocked`: create or update a spike/proposal/options node, record
+  blocker evidence, and continue other linked work.
+- `definition_blocking`: keep the loop open until the missing lane is completed
+  or explicitly waived.
+- `residual`: create follow-up work, mark it non-blocking, and allow closeout
+  only if all required lanes are otherwise satisfied.
+
+Whole-loop blocked state is allowed only when no authorized, useful, in-scope
+linked work remains across the loop graph.
+
+# Waiver And Decision Policy
+
+- Use proposal or open-question nodes for candidate waivers.
+- Use `decision_refs` for accepted design, product, or policy waivers.
+- Use `approval_refs` for concrete human/orchestrator approval receipts,
+  artifacts, or future approval nodes.
+- A simple body section is transitional MVP evidence only; prefer durable linked
+  nodes for long-lived waivers.
+
+# Closeout Matrix
+
+Before marking the loop done or blocked, update the required evidence lane table
+and explain why each lane is complete, waived, residual, or blocking.
+
+# Validation Plan
+
+- Parser and template validation.
+- Search, show, list, index, and pack visibility.
+- Fork provenance and child materialization checks.
+
+# Current State
+
+- Not run yet.

package/dist/init/templates/loops/backend-api-cli-bloat-audit.loop.md

@@ -0,0 +1,117 @@
+---
+id: loop-3
+type: loop
+title: Backend API CLI Bloat Audit
+status: todo
+priority: 1
+loop_mode: readonly
+loop_role: template
+scope_refs: []
+scope_description: Backend service API or CLI surface selected for modularity and bloat review.
+template_refs: []
+materialization_mode: default_children
+child_refs: []
+pre_run_questions: [scope_surface, local_cache_writes_approved, external_compatibility_checks_approved, optimization_priority]
+question_answer_refs: []
+pre_approved_actions: [read_source, inspect_help_and_contracts, run_local_inventory, create_mdkg_evidence]
+approval_gated_actions: [external_compatibility_checks, downstream_repo_checks]
+required_actions: [read_source, inspect_help_and_contracts, run_local_inventory, create_mdkg_evidence]
+requested_actions: [read_source, inspect_help_and_contracts, run_local_inventory, create_mdkg_evidence]
+prohibited_actions: [functional_changes, push_publish_deploy]
+action_approval_refs: []
+evidence_lanes: [public_command_api_inventory, flag_option_sprawl, ownership_boundaries, duplicated_command_logic, compatibility_risk, simplification_proposals]
+evidence_lane_refs: []
+lane_waiver_refs: []
+lane_waiver_decision_refs: []
+lane_waiver_approval_refs: []
+run_refs: []
+decision_refs: []
+output_refs: []
+approval_refs: []
+evaluation_refs: []
+definition_of_done: Backend API or CLI complexity lanes are reviewed or explicitly waived, and simplification recommendations are source-grounded.
+blocker_policy: spike_proposal_recommendation_continue
+tags: [loop-template, audit, backend, api, cli]
+owners: []
+links: []
+artifacts: []
+relates: []
+blocked_by: []
+blocks: []
+refs: []
+context_refs: []
+evidence_refs: []
+aliases: [backend-cli-bloat-audit-loop]
+skills: [pursue-mdkg-loop]
+created: 2026-07-06
+updated: 2026-07-06
+---
+
+# Operating Model
+
+Run a read-only audit for backend, API, and CLI design bloat. Look for sprawling flags, mixed ownership, duplicated command logic, weak module boundaries, and overly broad abstractions.
+
+# Default Child Nodes
+
+- Spike for command/API inventory.
+- Proposal node for simplification paths.
+- Task nodes for focused refactors that preserve behavior.
+
+# Definition Of Done
+
+- Public surfaces and core ownership boundaries are inventoried.
+- Bloat or coupling risks are tied to concrete source locations.
+- Command/API flag sprawl, mixed ownership, duplicate handlers, module
+  cohesion, and output/help consistency are reviewed or explicitly waived.
+- Recommendations preserve compatibility unless explicitly accepted otherwise.
+- Follow-up work is classified as definition-blocking or residual.
+
+# Required Evidence Lanes
+
+| Lane | Required | Evidence Needed | Status | Blocker | Recovery Node | Decision Or Waiver |
+| --- | --- | --- | --- | --- | --- | --- |
+| public command/API inventory | yes | command/API list and source refs | todo | none | none | none |
+| flag and option sprawl | yes | flagged commands/options with rationale | todo | none | none | none |
+| ownership boundaries | yes | module/command boundary notes | todo | none | none | none |
+| duplicated command logic | yes | repeated handlers or helpers | todo | none | none | none |
+| compatibility risk | yes | behavior-preserving recommendations | todo | external behavior may need proof | spike/proposal | none |
+| simplification proposals | yes | at least three paths for major changes | todo | none | none | none |
+
+# Pre-Run Questions
+
+- Which command, API, package, or backend surface is in scope?
+- Are local tests/builds approved when they write caches or generated outputs?
+- Are external compatibility checks, service calls, or downstream repo checks
+  approved?
+- Should recommendations optimize for compatibility, simplicity, performance, or
+  public CLI ergonomics first?
+
+# Pre-Approved Read-Only Actions
+
+- Inspect source, command registration, help text, tests, docs, generated command
+  references, and package metadata.
+- Run local CLI help, local tests/builds, `rg`, `mdkg show/search/pack/validate`,
+  and static command/API inventory scripts.
+- Create mdkg spikes, proposals, tasks, tests, checkpoints, and open questions.
+
+# Approval-Gated Actions
+
+- Functional code, docs, template, generated command, or public CLI behavior
+  changes.
+- External service calls or downstream compatibility checks.
+- Push, publish, tag, deploy, or provider-side actions.
+
+# Blocker Continuation
+
+If external service behavior or compatibility impact cannot be proven, create a
+spike, propose at least three viable paths, recommend one path, record blocker
+evidence, and continue local source, docs, help, and test analysis.
+
+Do not mark the whole loop blocked while another command/API lane remains
+actionable. Do not close the loop until required lanes are complete or linked to
+accepted `decision_refs` or `approval_refs`.
+
+# Closeout Matrix
+
+Classify follow-up work as compatibility-blocking, simplification residual,
+accepted waiver, or false positive before marking the loop done or blocked.

package/dist/init/templates/loops/design-frontend-ux-audit.loop.md

@@ -0,0 +1,117 @@
+---
+id: loop-2
+type: loop
+title: Design Frontend UX Audit
+status: todo
+priority: 1
+loop_mode: readonly
+loop_role: template
+scope_refs: []
+scope_description: Frontend application or user flow selected for design and UX audit.
+template_refs: []
+materialization_mode: default_children
+child_refs: []
+pre_run_questions: [target_surface, design_standard, browser_checks_approved, accessibility_priority]
+question_answer_refs: []
+pre_approved_actions: [read_source, inspect_design_tokens, capture_local_screenshots, create_mdkg_evidence]
+approval_gated_actions: [external_design_tools]
+required_actions: [read_source, inspect_design_tokens, capture_local_screenshots, create_mdkg_evidence]
+requested_actions: [read_source, inspect_design_tokens, capture_local_screenshots, create_mdkg_evidence]
+prohibited_actions: [visual_redesign_changes, deploy_preview_changes, push_publish_deploy]
+action_approval_refs: []
+evidence_lanes: [visual_consistency, accessibility_contrast, responsive_layout, interaction_ergonomics, design_system_fit, recommendations]
+evidence_lane_refs: []
+lane_waiver_refs: []
+lane_waiver_decision_refs: []
+lane_waiver_approval_refs: []
+run_refs: []
+decision_refs: []
+output_refs: []
+approval_refs: []
+evaluation_refs: []
+definition_of_done: UX and visual quality lanes are audited or explicitly waived against product design system and accessibility expectations.
+blocker_policy: spike_proposal_recommendation_continue
+tags: [loop-template, audit, design, ux, frontend]
+owners: []
+links: []
+artifacts: []
+relates: []
+blocked_by: []
+blocks: []
+refs: []
+context_refs: []
+evidence_refs: []
+aliases: [design-ux-audit-loop]
+skills: [pursue-mdkg-loop]
+created: 2026-07-06
+updated: 2026-07-06
+---
+
+# Operating Model
+
+Run a read-only design and frontend UX audit. Compare the current interface against the local design system, product intent, accessibility expectations, contrast, responsive behavior, and interaction polish.
+
+# Default Child Nodes
+
+- Spike for product/design context and screenshot inventory.
+- Test nodes for accessibility, contrast, and responsive checks.
+- Proposal node for prioritized UX improvements.
+
+# Definition Of Done
+
+- Screens or flows are inspected with evidence.
+- Design-system drift, accessibility issues, and UX friction are identified.
+- Contrast, responsive behavior, interaction states, copy clarity, and visual
+  hierarchy are reviewed or explicitly waived.
+- Recommendations are prioritized by user impact and implementation risk.
+- Follow-up work is classified as definition-blocking or residual.
+
+# Required Evidence Lanes
+
+| Lane | Required | Evidence Needed | Status | Blocker | Recovery Node | Decision Or Waiver |
+| --- | --- | --- | --- | --- | --- | --- |
+| route/screen inventory | yes | screens, flows, or source routes | todo | none | none | none |
+| design-system alignment | yes | local tokens/components/standards review | todo | none | none | none |
+| accessibility and contrast | yes | local proof or code-level review | todo | visual runtime may be unavailable | spike/proposal | none |
+| responsive behavior | yes | viewport proof or source-grounded review | todo | browser/runtime may be unavailable | spike/proposal | none |
+| interaction states | scope-dependent | hover/focus/error/loading review | todo | none | none | none |
+| prioritized recommendations | yes | user impact and risk ordering | todo | none | none | none |
+
+# Pre-Run Questions
+
+- Which routes, screens, or flows are in scope?
+- Is browser/runtime proof approved or available?
+- Are local builds/tests approved when they write caches or generated outputs?
+- Should the audit optimize toward current local design, ChatGPT/Codex-inspired
+  interaction polish, accessibility, density, or conversion?
+
+# Pre-Approved Read-Only Actions
+
+- Inspect frontend source, design docs, tokens, CSS, components, screenshots,
+  generated static output, and local docs.
+- Run local builds/tests, static accessibility checks, `rg`, mdkg commands, and
+  browser checks when available locally.
+- Create mdkg findings, screenshots/artifact refs, proposals, tasks, tests, and
+  open questions.
+
+# Approval-Gated Actions
+
+- Functional UI/code/docs changes.
+- External design tools, provider calls, deploys, analytics, or production
+  browser-session actions.
+
+# Blocker Continuation
+
+If visual runtime proof is blocked, write a spike with source-grounded options,
+propose at least three ways to obtain evidence, recommend one path, mark blocker
+evidence, and continue code-level design-system, accessibility, and interaction
+analysis.
+
+Do not mark the whole loop blocked while another UX lane remains actionable. Do
+not close the loop until required lanes are complete or linked to accepted
+`decision_refs` or `approval_refs`.
+
+# Closeout Matrix
+
+Classify follow-up work as definition-blocking UX evidence, residual polish,
+accepted waiver, or false positive before marking the loop done or blocked.

package/dist/init/templates/loops/duplicate-code-and-linting-audit.loop.md

@@ -0,0 +1,114 @@
+---
+id: loop-5
+type: loop
+title: Duplicate Code And Linting Audit
+status: todo
+priority: 1
+loop_mode: readonly
+loop_role: template
+scope_refs: []
+scope_description: Repository package or folder selected for duplication lint and static-quality review.
+template_refs: []
+materialization_mode: default_children
+child_refs: []
+pre_run_questions: [target_scope, local_lint_checks_approved, generated_output_policy]
+question_answer_refs: []
+pre_approved_actions: [read_source, run_local_lint_inventory, inspect_duplicates, create_mdkg_evidence]
+approval_gated_actions: []
+required_actions: [read_source, run_local_lint_inventory, inspect_duplicates, create_mdkg_evidence]
+requested_actions: [read_source, run_local_lint_inventory, inspect_duplicates, create_mdkg_evidence]
+prohibited_actions: [automatic_refactors, formatter_rewrites, dependency_changes, push_publish_deploy]
+action_approval_refs: []
+evidence_lanes: [duplicate_code_inventory, linting_baseline, refactor_candidates, false_positive_triage, recommendations]
+evidence_lane_refs: []
+lane_waiver_refs: []
+lane_waiver_decision_refs: []
+lane_waiver_approval_refs: []
+run_refs: []
+decision_refs: []
+output_refs: []
+approval_refs: []
+evaluation_refs: []
+definition_of_done: Duplicate logic and static-quality lanes are reviewed or explicitly waived with practical follow-up recommendations.
+blocker_policy: spike_proposal_recommendation_continue
+tags: [loop-template, audit, duplicate-code, linting]
+owners: []
+links: []
+artifacts: []
+relates: []
+blocked_by: []
+blocks: []
+refs: []
+context_refs: []
+evidence_refs: []
+aliases: [duplicate-lint-audit-loop]
+skills: [pursue-mdkg-loop]
+created: 2026-07-06
+updated: 2026-07-06
+---
+
+# Operating Model
+
+Run a read-only duplication and linting audit. Use static analysis, existing linters, search, and source review to find repeated logic, inconsistent patterns, and preventable quality drift.
+
+# Default Child Nodes
+
+- Spike for duplicated pattern inventory.
+- Test nodes for lint or static-analysis coverage.
+- Task nodes for low-risk consolidation opportunities.
+
+# Definition Of Done
+
+- Duplicate or near-duplicate logic is identified with source evidence.
+- Linting and formatting gaps are reviewed.
+- Existing static-quality tools, repeated utility patterns, and avoidable
+  divergence are reviewed or explicitly waived.
+- Recommendations avoid broad refactors without measurable payoff.
+- Follow-up work is classified as definition-blocking or residual.
+
+# Required Evidence Lanes
+
+| Lane | Required | Evidence Needed | Status | Blocker | Recovery Node | Decision Or Waiver |
+| --- | --- | --- | --- | --- | --- | --- |
+| duplicate logic search | yes | repeated functions/modules/source refs | todo | none | none | none |
+| lint/format config review | yes | tool configs and current command behavior | todo | local tools may fail | spike/proposal | none |
+| repeated utility patterns | yes | consolidation candidates and tradeoffs | todo | none | none | none |
+| generated/vendor exclusions | yes | exclusion rationale | todo | none | none | none |
+| recommendations | yes | scoped payoff/risk notes | todo | none | none | none |
+
+# Pre-Run Questions
+
+- Which folders or packages are in scope?
+- Are local lint/test/build commands approved when they write caches or generated
+  outputs?
+- Which generated, vendor, fixture, or snapshot folders should be excluded?
+
+# Pre-Approved Read-Only Actions
+
+- Inspect source, tests, configs, scripts, generated references, and mdkg graph.
+- Run local search, lint, format check, tests/builds, and static analysis tools
+  that do not call external services.
+- Create mdkg evidence, consolidation proposals, tasks, tests, and open
+  questions.
+
+# Approval-Gated Actions
+
+- Functional refactors, formatting rewrites, generated updates, or dependency
+  changes.
+- External tools or service calls.
+
+# Blocker Continuation
+
+If tools cannot run locally, create a spike, propose at least three options for
+proof, recommend one path, mark blocker evidence, and continue search-based
+source review and config inspection.
+
+Do not mark the whole loop blocked while another duplicate/lint lane remains
+actionable. Do not close the loop until required lanes are complete or linked to
+accepted `decision_refs` or `approval_refs`.
+
+# Closeout Matrix
+
+Classify follow-up work as definition-blocking tool evidence, residual
+consolidation, accepted waiver, or false positive before marking the loop done
+or blocked.