mdkg 0.4.2 → 0.5.1

package/dist/init/templates/loops/security-audit.loop.md

@@ -0,0 +1,140 @@
+---
+id: loop-1
+type: loop
+title: Security Audit
+status: todo
+priority: 1
+loop_mode: readonly
+loop_role: template
+scope_refs: []
+scope_description: Repository or package scope selected for a read-only security audit.
+template_refs: []
+materialization_mode: default_children
+child_refs: []
+pre_run_questions: [external_advisory_checks_approved, security_provider_workflow_approved, local_cache_writes_approved, audit_scope]
+question_answer_refs: []
+pre_approved_actions: [read_source, inspect_lockfiles, run_local_static_scans, create_mdkg_evidence]
+approval_gated_actions: [external_advisory_checks, security_provider_workflow]
+required_actions: [read_source, inspect_lockfiles, run_local_static_scans, create_mdkg_evidence]
+requested_actions: [read_source, inspect_lockfiles, run_local_static_scans, create_mdkg_evidence]
+prohibited_actions: [functional_changes, push_publish_deploy]
+action_approval_refs: []
+evidence_lanes: [source_security_review, credential_secret_exposure, dependency_advisories, public_exposure, package_export_surfaces, finding_triage]
+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: Security audit required lanes are complete or explicitly waived; residual follow-up is classified separately from definition-blocking gaps.
+blocker_policy: spike_proposal_recommendation_continue
+tags: [loop-template, audit, security]
+owners: []
+links: []
+artifacts: []
+relates: []
+blocked_by: []
+blocks: []
+refs: []
+context_refs: []
+evidence_refs: []
+aliases: [security-audit-loop]
+skills: [pursue-mdkg-loop]
+created: 2026-07-06
+updated: 2026-07-06
+---
+
+# Operating Model
+
+Run a read-only security review over the selected scope. Ground findings in source, configuration, dependency metadata, generated artifacts, and existing mdkg context. Do not make code changes from this loop.
+
+# Default Child Nodes
+
+- Spike for threat model and attack surface discovery.
+- Task or test nodes for validated remediation work.
+- Checkpoint for scan evidence and residual risk.
+
+# Definition Of Done
+
+- Source/security-sensitive code is reviewed with source-grounded evidence.
+- Credential and secret exposure checks are run or explicitly waived.
+- Dependency advisory checks cover all publish-relevant packages or are
+  explicitly waived.
+- Public/docs/demo exposure surfaces are reviewed when in scope.
+- Package, bundle, archive, subgraph, and publish surfaces are reviewed when in
+  scope.
+- Valid findings include affected files, impact, evidence, severity, and
+  remediation direction.
+- False positives, residual uncertainty, and non-blocking hardening work are
+  recorded.
+- Required lanes are complete or linked to accepted `decision_refs` or
+  `approval_refs`.
+
+# Required Evidence Lanes
+
+| Lane | Required | Evidence Needed | Status | Blocker | Recovery Node | Decision Or Waiver |
+| --- | --- | --- | --- | --- | --- | --- |
+| source security review | yes | files and source-grounded findings | todo | none | none | none |
+| credential/secret exposure | yes | local scan plus manual review notes | todo | none | none | none |
+| dependency advisories | yes | root and subpackage advisory receipts | todo | external registry approval may be needed | proposal or approval request | none |
+| public/docs/demo exposure | scope-dependent | reviewed public surfaces and claims | todo | none | none | none |
+| package/bundle/archive/subgraph surfaces | scope-dependent | package and graph export review | todo | none | none | none |
+| finding triage | yes | severity, impact, evidence, recommendation | todo | none | none | none |
+
+# Pre-Run Questions
+
+- Are external advisory checks such as `npm audit` approved for every package
+  that may send dependency metadata to a registry?
+- Is Codex Security or another multi-agent/security provider workflow approved?
+- Are local test/build commands approved when they write caches or generated
+  outputs outside committed source?
+- Is the audit pre-publish, local-only, or scoped to a smaller package/folder?
+
+# Pre-Approved Read-Only Actions
+
+- Read source, docs, mdkg graph, package metadata, lockfiles, configs, tests,
+  generated public surfaces, and local scripts.
+- Run local static scans, `rg`, `mdkg show/search/pack/validate`, local tests,
+  local builds, and package inspection commands that do not call external
+  services.
+- Create mdkg evidence, findings, spikes, proposals, tasks, tests, checkpoints,
+  and open questions.
+- Make provisional severity and priority calls for later human/orchestrator
+  review.
+
+# Approval-Gated Actions
+
+- External registry/advisory/security-provider calls.
+- Multi-agent delegation or privileged security tooling.
+- Functional source, docs, template, generated command, or runtime changes.
+- Push, publish, tag, deploy, DNS, analytics, or provider-side actions.
+
+# Blocker Continuation
+
+If a lane is blocked by missing credentials, private systems, external approval,
+or unavailable runtime state, write blocker evidence, create or update a spike
+and proposal with at least three viable paths, recommend one path, and continue
+every other authorized audit lane.
+
+Do not mark the whole loop blocked while any required or useful security audit
+lane remains actionable. Do not mark the loop done when a required lane is only
+represented as future work; it must be completed or explicitly waived.
+
+# Closeout Matrix
+
+Before closeout, update the required evidence lane table and classify every
+follow-up as one of:
+
+- definition-blocking: loop remains open until completed or waived;
+- residual hardening: follow-up can remain after loop closeout;
+- false positive: no action required, with evidence;
+- accepted waiver: linked through `decision_refs` or `approval_refs`.
+
+# Provisional Decisions And Open Questions
+
+Record security severity calls, waiver candidates, approval requests, and
+external-check questions here or in linked proposal/decision nodes before
+treating them as accepted.

package/dist/init/templates/loops/tech-stack-best-practices-audit.loop.md

@@ -0,0 +1,116 @@
+---
+id: loop-4
+type: loop
+title: Tech Stack Best Practices Audit
+status: todo
+priority: 1
+loop_mode: readonly
+loop_role: template
+scope_refs: []
+scope_description: Repository package or subsystem selected for stack-specific best-practices review.
+template_refs: []
+materialization_mode: default_children
+child_refs: []
+pre_run_questions: [target_stack, external_docs_allowed, local_tests_approved, compatibility_priority]
+question_answer_refs: []
+pre_approved_actions: [read_source, inspect_dependencies, run_local_checks, create_mdkg_evidence]
+approval_gated_actions: [external_docs_search]
+required_actions: [read_source, inspect_dependencies, run_local_checks, create_mdkg_evidence]
+requested_actions: [read_source, inspect_dependencies, run_local_checks, create_mdkg_evidence]
+prohibited_actions: [dependency_upgrades, architecture_changes, push_publish_deploy]
+action_approval_refs: []
+evidence_lanes: [stack_inventory, best_practice_gap_review, dependency_posture, compatibility_risk, 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: Stack-specific risks and improvement lanes are reviewed or explicitly waived against current project conventions.
+blocker_policy: spike_proposal_recommendation_continue
+tags: [loop-template, audit, best-practices, stack]
+owners: []
+links: []
+artifacts: []
+relates: []
+blocked_by: []
+blocks: []
+refs: []
+context_refs: []
+evidence_refs: []
+aliases: [tech-stack-audit-loop]
+skills: [pursue-mdkg-loop]
+created: 2026-07-06
+updated: 2026-07-06
+---
+
+# Operating Model
+
+Run a read-only audit against the technology stack in the selected scope. Prefer official docs, local conventions, package metadata, and existing tests over generic advice.
+
+# Default Child Nodes
+
+- Spike for stack inventory and version-sensitive guidance.
+- Test nodes for verification gaps.
+- Proposal node for prioritized modernization or hardening paths.
+
+# Definition Of Done
+
+- Stack versions, frameworks, and local conventions are identified.
+- Findings distinguish best-practice drift from acceptable project choices.
+- Package metadata, config, official guidance availability, local tests, and
+  upgrade/deprecation risks are reviewed or explicitly waived.
+- Recommendations are scoped and evidence-backed.
+- Follow-up work is classified as definition-blocking or residual.
+
+# Required Evidence Lanes
+
+| Lane | Required | Evidence Needed | Status | Blocker | Recovery Node | Decision Or Waiver |
+| --- | --- | --- | --- | --- | --- | --- |
+| stack inventory | yes | package/config/framework versions | todo | none | none | none |
+| local convention review | yes | source/docs/test convention evidence | todo | none | none | none |
+| official guidance check | scope-dependent | current official docs or waived external lookup | todo | network may need approval | spike/proposal | none |
+| package/deprecation risk | yes | local metadata and advisory/guidance notes | todo | external lookup may need approval | spike/proposal | none |
+| test/build fit | yes | local command receipts or rationale | todo | tool failure may occur | spike/proposal | none |
+| recommendations | yes | scoped risk/payoff notes | todo | none | none | none |
+
+# Pre-Run Questions
+
+- Which stack surfaces are in scope?
+- Are official documentation lookups or external advisory calls approved?
+- Are local tests/builds approved when they write caches or generated outputs?
+- Should recommendations optimize for stability, modernization, performance, or
+  maintenance cost?
+
+# Pre-Approved Read-Only Actions
+
+- Inspect source, package metadata, lockfiles, configs, tests, docs, and mdkg
+  graph.
+- Run local tests/builds, static discovery, version commands, and mdkg commands
+  that do not call external services.
+- Create mdkg findings, proposals, tasks, tests, and open questions.
+
+# Approval-Gated Actions
+
+- External official-doc/advisory calls when they disclose project metadata.
+- Dependency upgrades, config changes, generated updates, or functional source
+  edits.
+
+# Blocker Continuation
+
+If current external guidance or environment access is unavailable, create a
+spike with source-grounded assumptions, propose at least three options,
+recommend one path, and continue package/config/source/test review.
+
+Do not mark the whole loop blocked while another stack 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 evidence, residual stack
+improvement, accepted waiver, or false positive before marking the loop done or
+blocked.

package/dist/init/templates/loops/test-ci-skill-infrastructure-audit.loop.md

@@ -0,0 +1,116 @@
+---
+id: loop-6
+type: loop
+title: Test CI Skill Infrastructure Audit
+status: todo
+priority: 1
+loop_mode: readonly
+loop_role: template
+scope_refs: []
+scope_description: Repository or workspace selected for tests CI automation and SKILL.md infrastructure audit.
+template_refs: []
+materialization_mode: default_children
+child_refs: []
+pre_run_questions: [target_scope, local_ci_simulation_approved, skill_sync_allowed, generated_output_policy]
+question_answer_refs: []
+pre_approved_actions: [read_tests, inspect_ci_config, run_local_smokes, create_mdkg_evidence]
+approval_gated_actions: [external_ci_calls]
+required_actions: [read_tests, inspect_ci_config, run_local_smokes, create_mdkg_evidence]
+requested_actions: [read_tests, inspect_ci_config, run_local_smokes, create_mdkg_evidence]
+prohibited_actions: [ci_config_changes, skill_file_edits, push_publish_deploy]
+action_approval_refs: []
+evidence_lanes: [test_inventory, ci_gate_review, skill_infrastructure_review, gap_prioritization, 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: Test, CI, automation, and SKILL.md infrastructure lanes are reviewed or explicitly waived with prioritized improvements.
+blocker_policy: spike_proposal_recommendation_continue
+tags: [loop-template, audit, tests, ci, skills]
+owners: []
+links: []
+artifacts: []
+relates: []
+blocked_by: []
+blocks: []
+refs: []
+context_refs: []
+evidence_refs: []
+aliases: [test-ci-skill-audit-loop]
+skills: [pursue-mdkg-loop]
+created: 2026-07-06
+updated: 2026-07-06
+---
+
+# Operating Model
+
+Run a read-only audit of tests, CI gates, automation scripts, and SKILL.md infrastructure. Look for brittle coverage, slow or missing gates, duplicate skill guidance, and reusable workflow gaps.
+
+# Default Child Nodes
+
+- Spike for test and CI inventory.
+- Test nodes for missing coverage or smoke gates.
+- Proposal node for skill consolidation and automation improvements.
+
+# Definition Of Done
+
+- Current local and CI verification surfaces are inventoried.
+- Missing or weak gates are tied to user-facing or maintenance risk.
+- SKILL.md duplication and consolidation opportunities are identified.
+- Local smoke/unit/build commands, CI configuration, skill registry/mirrors, and
+  harness guidance are reviewed or explicitly waived.
+- Follow-up work is classified as definition-blocking or residual.
+
+# Required Evidence Lanes
+
+| Lane | Required | Evidence Needed | Status | Blocker | Recovery Node | Decision Or Waiver |
+| --- | --- | --- | --- | --- | --- | --- |
+| local test/build inventory | yes | package scripts and command receipts | todo | tool failure may occur | spike/proposal | none |
+| CI gate inventory | yes | workflow/config/provider evidence | todo | provider access may need approval | spike/proposal | none |
+| smoke coverage | yes | smoke scripts and gaps | todo | none | none | none |
+| SKILL.md registry and mirrors | yes | canonical and mirrored skill review | todo | none | none | none |
+| harness guidance gaps | yes | missing/duplicated instructions | todo | none | none | none |
+| prioritized improvements | yes | risk/payoff ordering | todo | none | none | none |
+
+# Pre-Run Questions
+
+- Is CI provider access approved, or should the audit stay local-only?
+- Are local tests/builds approved when they write caches or generated outputs?
+- Should skill changes be in scope, or should this audit only create proposals?
+- Which runtime/client mirrors must be considered authoritative projections?
+
+# Pre-Approved Read-Only Actions
+
+- Inspect package scripts, tests, CI configs, smoke scripts, skills, mirrors,
+  generated docs, and mdkg graph.
+- Run local tests/builds/smokes and mdkg validation commands that do not call
+  external services.
+- Create mdkg evidence, skill-improvement proposals, tasks, tests, and open
+  questions.
+
+# Approval-Gated Actions
+
+- CI provider/API calls.
+- Skill edits, mirror sync, source/test changes, generated updates, or
+  dependency changes unless the loop scope explicitly allows implementation.
+
+# Blocker Continuation
+
+If CI provider access or external logs are unavailable, create a spike, propose
+at least three ways to obtain evidence, recommend one path, record blocker
+evidence, and continue local test, smoke, script, and skill review.
+
+Do not mark the whole loop blocked while another test/CI/skill 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 gate evidence, residual
+automation improvement, accepted waiver, or false positive before marking the
+loop done or blocked.

package/dist/init/templates/loops/user-story-audit-and-recommendations.loop.md

@@ -0,0 +1,116 @@
+---
+id: loop-7
+type: loop
+title: User Story Audit And Recommendations
+status: todo
+priority: 1
+loop_mode: planning
+loop_role: template
+scope_refs: []
+scope_description: Product area feature set or repository selected for user story audit and recommendations.
+template_refs: []
+materialization_mode: default_children
+child_refs: []
+pre_run_questions: [target_audience, product_surface, evidence_sources, recommendation_scope]
+question_answer_refs: []
+pre_approved_actions: [read_docs, inspect_existing_stories, review_mdkg_graph, create_mdkg_evidence]
+approval_gated_actions: [external_research_calls]
+required_actions: [read_docs, inspect_existing_stories, review_mdkg_graph, create_mdkg_evidence]
+requested_actions: [read_docs, inspect_existing_stories, review_mdkg_graph, create_mdkg_evidence]
+prohibited_actions: [public_copy_changes, roadmap_reprioritization, push_publish_deploy]
+action_approval_refs: []
+evidence_lanes: [story_inventory, persona_alignment, gap_analysis, recommendation_options, followup_work]
+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: User story and product outcome lanes are reviewed or explicitly waived with actionable recommendations.
+blocker_policy: spike_proposal_recommendation_continue
+tags: [loop-template, audit, planning, user-stories]
+owners: []
+links: []
+artifacts: []
+relates: []
+blocked_by: []
+blocks: []
+refs: []
+context_refs: []
+evidence_refs: []
+aliases: [user-story-audit-loop]
+skills: [pursue-mdkg-loop]
+created: 2026-07-06
+updated: 2026-07-06
+---
+
+# Operating Model
+
+Run a planning-oriented audit of user stories, product flows, acceptance criteria, and unresolved requirements. Prefer existing docs, source behavior, tests, issue references, and current mdkg decisions.
+
+# Default Child Nodes
+
+- Spike for story and flow inventory.
+- Proposal node with at least three viable product or implementation paths where gaps exist.
+- Task or test nodes for accepted story improvements.
+
+# Definition Of Done
+
+- Existing user stories and implied product outcomes are mapped.
+- Missing personas, edge cases, acceptance criteria, and risks are documented.
+- Source/docs behavior, known decisions, open questions, and recommendation
+  tradeoffs are reviewed or explicitly waived.
+- Recommendations are ordered by user value and implementation leverage.
+- Follow-up work is classified as definition-blocking or residual.
+
+# Required Evidence Lanes
+
+| Lane | Required | Evidence Needed | Status | Blocker | Recovery Node | Decision Or Waiver |
+| --- | --- | --- | --- | --- | --- | --- |
+| story/outcome inventory | yes | stories, docs, goals, source behavior | todo | none | none | none |
+| persona and journey gaps | yes | missing actors/flows/risk notes | todo | product context may be missing | spike/proposal | none |
+| acceptance criteria | yes | criteria gaps and testability notes | todo | none | none | none |
+| edge cases and failure modes | yes | grounded edge-case list | todo | none | none | none |
+| decision/open-question mapping | yes | linked decisions/proposals/questions | todo | product approval may be needed | proposal | none |
+| prioritized recommendations | yes | value/leverage/risk ordering | todo | none | none | none |
+
+# Pre-Run Questions
+
+- Which product area, user journey, or repo scope is in scope?
+- Are assumptions allowed when product context is missing, or should the loop
+  request decisions first?
+- Are local tests/builds approved when they write caches or generated outputs?
+- Should recommendations create implementation tasks, proposal nodes, or both?
+
+# Pre-Approved Read-Only Actions
+
+- Inspect docs, mdkg goals/decisions, source behavior, tests, issues captured in
+  the repo, and product notes.
+- Run local tests/builds and mdkg commands that do not call external services.
+- Create mdkg stories, proposals, tasks, tests, spikes, and open questions.
+- Make provisional prioritization recommendations for human/orchestrator
+  approval.
+
+# Approval-Gated Actions
+
+- Product-scope changes, implementation changes, public copy changes, deploys,
+  analytics, provider calls, or external issue-tracker mutations.
+
+# Blocker Continuation
+
+If product context is missing, create a spike with grounded assumptions, propose
+at least three viable paths, recommend one path, mark blocker evidence, and
+continue source, docs, workflow, and acceptance-criteria review.
+
+Do not mark the whole loop blocked while another story/product 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 product decision, residual story
+improvement, accepted waiver, or false positive before marking the loop done or
+blocked.

package/dist/pack/order.js

@@ -17,14 +17,16 @@ const FALLBACK_TYPES = [
     "proposal",
     "archive",
     "goal",
+    "loop",
     "epic",
     "feat",
     "task",
     "bug",
     "spike",
     "checkpoint",
+    "test",
 ];
-const WORK_TYPES = ["goal", "epic", "feat", "task", "bug", "spike", "checkpoint"];
+const WORK_TYPES = ["goal", "loop", "epic", "feat", "task", "bug", "spike", "checkpoint", "test"];
 function idNumber(id) {
     const match = id.match(/-(\d+)$/);
     if (!match) {