diff --git a/docs/changelog.d/+mikado-finalization-cleanup.doc.md b/docs/changelog.d/+mikado-finalization-cleanup.doc.md new file mode 100644 index 0000000..a1e736e --- /dev/null +++ b/docs/changelog.d/+mikado-finalization-cleanup.doc.md @@ -0,0 +1 @@ +Clarify that all mikado frontmatter is removed during chain finalization; clean up stale frontmatter from closed chains; fix ai-docs exit code after plans directory retirement. diff --git a/docs/how-to/agent-change-process.md b/docs/how-to/agent-change-process.md index a83737e..ed7702d 100644 --- a/docs/how-to/agent-change-process.md +++ b/docs/how-to/agent-change-process.md @@ -1,6 +1,6 @@ --- title: Agent Change Process -modified: 2026-03-03 +modified: 2026-03-04 last-reviewed: 2026-02-23 tags: - how-to @@ -203,10 +203,11 @@ When you discover a new prerequisite **or encounter an error** during code work, When the final leaf node is closed and no `status: active` cards remain: 1. **Rewrite all Mikado cards** to reflect their nature as historical documentation: + - **Remove all Mikado frontmatter** from every card in the chain: `requires:`, `status:`, and `branch:`. Cards become "just documentation" — the Mikado metadata served its purpose during the chain and should not persist. + - Cards can (and should) still link to one another via wiki-links in their body text, just not via frontmatter dependencies. - Remove transient technical details (specific version numbers, temporary workarounds) that won't matter in the future - Frame the content as "what to do if someone wanted to repeat this process" - Add appropriate context about what was learned - - Remove `branch:` from the goal card frontmatter 2. **Add changelog information** in `docs/changelog.d/` 3. Commit as `C2(): finalize ...` — this is the one permitted exception to the invariant's "no card changes after code" rule 4. The user reviews and merges the PR @@ -253,8 +254,9 @@ tags: ``` - `status: active` marks in-progress work; remove when done (this is the ONLY way a card is marked complete) -- `branch` is set on goal cards only, linking the card to its `mikado/` branch. A goal card with `status: active` but no `branch` indicates a chain that is planned but not yet started. Remove `branch` when the chain is finalized. -- `requires` lists card stems (filenames without `.md`) that must be completed first. **Keep `requires` permanently** even after prerequisites are done — it documents the dependency graph history +- `branch` is set on goal cards only, linking the card to its `mikado/` branch. A goal card with `status: active` but no `branch` indicates a chain that is planned but not yet started. +- `requires` lists card stems (filenames without `.md`) that must be completed first. +- **During finalization**, remove all Mikado frontmatter (`requires`, `status`, `branch`) from every card in the chain. Use wiki-links in body text to preserve cross-references. - `required-by` is NOT stored — it's computed by `docs-mikado` ### Writing Cards diff --git a/docs/how-to/authentik/authentik-api-client-generation.md b/docs/how-to/authentik/authentik-api-client-generation.md index 6127636..480d9c7 100644 --- a/docs/how-to/authentik/authentik-api-client-generation.md +++ b/docs/how-to/authentik/authentik-api-client-generation.md @@ -2,8 +2,6 @@ title: Generate Authentik API Clients modified: 2026-03-01 last-reviewed: 2026-03-01 -requires: - - mirror-authentik-build-deps tags: - how-to - authentik diff --git a/docs/how-to/authentik/authentik-go-server-derivation.md b/docs/how-to/authentik/authentik-go-server-derivation.md index afa30dc..8cb7335 100644 --- a/docs/how-to/authentik/authentik-go-server-derivation.md +++ b/docs/how-to/authentik/authentik-go-server-derivation.md @@ -2,9 +2,6 @@ title: Build Authentik Go Server modified: 2026-03-02 last-reviewed: 2026-03-02 -requires: - - authentik-api-client-generation - - authentik-python-backend-derivation tags: - how-to - authentik diff --git a/docs/how-to/authentik/authentik-python-backend-derivation.md b/docs/how-to/authentik/authentik-python-backend-derivation.md index d372a30..4e2c240 100644 --- a/docs/how-to/authentik/authentik-python-backend-derivation.md +++ b/docs/how-to/authentik/authentik-python-backend-derivation.md @@ -2,8 +2,6 @@ title: Build Authentik Python Backend modified: 2026-03-01 last-reviewed: 2026-03-02 -requires: - - mirror-authentik-build-deps tags: - how-to - authentik diff --git a/docs/how-to/authentik/authentik-web-ui-derivation.md b/docs/how-to/authentik/authentik-web-ui-derivation.md index a8ddf4a..3a9572b 100644 --- a/docs/how-to/authentik/authentik-web-ui-derivation.md +++ b/docs/how-to/authentik/authentik-web-ui-derivation.md @@ -2,8 +2,6 @@ title: Build Authentik Web UI modified: 2026-03-01 last-reviewed: 2026-03-02 -requires: - - authentik-api-client-generation tags: - how-to - authentik diff --git a/docs/how-to/authentik/build-authentik-from-source.md b/docs/how-to/authentik/build-authentik-from-source.md index d4411e3..1f526df 100644 --- a/docs/how-to/authentik/build-authentik-from-source.md +++ b/docs/how-to/authentik/build-authentik-from-source.md @@ -2,10 +2,6 @@ title: Build Authentik from Source modified: 2026-03-01 last-reviewed: 2026-03-02 -requires: - - authentik-go-server-derivation - - authentik-web-ui-derivation - - authentik-python-backend-derivation tags: - how-to - authentik diff --git a/docs/how-to/authentik/deploy-authentik.md b/docs/how-to/authentik/deploy-authentik.md index 20fc552..bbbbfd8 100644 --- a/docs/how-to/authentik/deploy-authentik.md +++ b/docs/how-to/authentik/deploy-authentik.md @@ -2,11 +2,6 @@ title: Deploy Authentik Identity Provider modified: 2026-02-23 last-reviewed: 2026-02-23 -requires: - - build-authentik-container - - provision-authentik-database - - create-authentik-secrets - - migrate-grafana-to-authentik tags: - how-to - authentik diff --git a/docs/how-to/forgejo-runner/upgrade-k8s-runner.md b/docs/how-to/forgejo-runner/upgrade-k8s-runner.md index 2b5d4c5..3d285ac 100644 --- a/docs/how-to/forgejo-runner/upgrade-k8s-runner.md +++ b/docs/how-to/forgejo-runner/upgrade-k8s-runner.md @@ -1,8 +1,5 @@ --- title: Upgrade K8s Forgejo Runner to v12 -requires: - - validate-workflows-against-v12 - - review-runner-config-v12 modified: 2026-02-27 last-reviewed: 2026-02-27 tags: diff --git a/docs/how-to/grafana/upgrade-grafana.md b/docs/how-to/grafana/upgrade-grafana.md index 547e726..39af369 100644 --- a/docs/how-to/grafana/upgrade-grafana.md +++ b/docs/how-to/grafana/upgrade-grafana.md @@ -1,8 +1,5 @@ --- title: Upgrade Grafana -requires: - - kustomize-grafana-deployment - - build-grafana-container modified: 2026-03-04 last-reviewed: 2026-03-04 tags: diff --git a/docs/how-to/zot/add-container-version-sync-check.md b/docs/how-to/zot/add-container-version-sync-check.md index 2ebe3d8..7c98492 100644 --- a/docs/how-to/zot/add-container-version-sync-check.md +++ b/docs/how-to/zot/add-container-version-sync-check.md @@ -1,10 +1,6 @@ --- title: Add Container Version Sync Check modified: 2026-02-20 -requires: - - pin-container-versions - - add-dagger-nix-build - - fix-ntfy-nix-version tags: - how-to - containers diff --git a/docs/how-to/zot/add-dagger-nix-build.md b/docs/how-to/zot/add-dagger-nix-build.md index 2598839..40841a8 100644 --- a/docs/how-to/zot/add-dagger-nix-build.md +++ b/docs/how-to/zot/add-dagger-nix-build.md @@ -1,7 +1,6 @@ --- title: Add Dagger Nix Build Function modified: 2026-02-20 -status: tags: - how-to - containers diff --git a/docs/how-to/zot/adopt-commit-based-container-tags.md b/docs/how-to/zot/adopt-commit-based-container-tags.md index c8b1087..82c90fc 100644 --- a/docs/how-to/zot/adopt-commit-based-container-tags.md +++ b/docs/how-to/zot/adopt-commit-based-container-tags.md @@ -1,9 +1,6 @@ --- title: Adopt Commit-Based Container Tags modified: 2026-02-20 -requires: - - add-container-version-sync-check - - install-dagger-on-nix-runner tags: - how-to - containers diff --git a/mise-tasks/ai-docs b/mise-tasks/ai-docs index 2782a6a..c7e1d06 100755 --- a/mise-tasks/ai-docs +++ b/mise-tasks/ai-docs @@ -13,8 +13,6 @@ FILES=( "$DOCS_DIR/reference/reference.md" "$DOCS_DIR/how-to/how-to.md" "$DOCS_DIR/how-to/operations/troubleshooting.md" - "$DOCS_DIR/how-to/plans/plans.md" - "$DOCS_DIR/how-to/plans/completed/completed.md" "$DOCS_DIR/explanation/explanation.md" "$DOCS_DIR/explanation/architecture.md" "$DOCS_DIR/tutorials/tutorials.md" diff --git a/mise-tasks/mikado-branch-invariant-check b/mise-tasks/mikado-branch-invariant-check index 81e855b..d8443ba 100755 --- a/mise-tasks/mikado-branch-invariant-check +++ b/mise-tasks/mikado-branch-invariant-check @@ -107,7 +107,7 @@ def is_mikado_card(content: str) -> bool: """Check if file content has Mikado card frontmatter. A file is a Mikado card if its YAML frontmatter contains any of: - - requires: (dependency list, kept permanently on cards) + - requires: (dependency list for active chain cards) - status: (e.g. 'active' for in-progress cards) - branch: mikado/... (goal cards linking to their branch) """