basilisk-labs · densmirnov · May 1, 2026 · May 1, 2026 · May 1, 2026 · May 1, 2026
diff --git a/.agentplane/config.json b/.agentplane/config.json
@@ -23,7 +23,7 @@
     "source": "https://github.com/basilisk-labs/agentplane",
     "last_update": null,
     "cli": {
-      "expected_version": "0.4.0"
+      "expected_version": "0.4.1"
     }
   },
   "tasks": {

diff --git a/.agentplane/policy/incidents.md b/.agentplane/policy/incidents.md
@@ -1,4 +1,5 @@
 # Policy Incidents Log
+
 - Append-only. Required fields: `id`, `date`, `scope`, `failure`, `rule`, `evidence`, `enforcement`, `state`; optional: `tags`, `match`, `advice`, `source_task`, `fixability`.
 - id: INC-20260422-02 | date: 2026-04-22 | scope: release-mode hook environment pollution | tags: ci, release, hooks | match: ci, release, hooks, pre-push, core.bare, git config, inherited, test, pollution | failure: A release-mode pre-push hook inherited test-modified git config (`core.bare=true`) and blocked local release verification until the repository config was manually restored. | advice: Isolate git config mutations in release/hook tests and make release-mode hook diagnostics identify polluted repository git config before treating the release payload as broken. | rule: Release and hook verification MUST distinguish polluted local git config from release payload failures. | evidence: task 202604221605-SQYRNQ; commit 45ba9c57f939 | enforcement: manual | fixability: repo-fixable | state: open
 - id: INC-20260428-01 | date: 2026-04-28 | scope: release and hosted-close verification evidence reconciliation | tags: branch-pr, release, hosted-close, verification | match: branch-pr, code, workflow, hosted, close, release, evidence, verification, pending, done | failure: Release evidence reconciliation is not fully fixed: `release-task-evidence apply` writes `verification.state=ok` for new evidence, but legacy `DONE` tasks with pending verification artifacts are widespread and need a migration-aware invariant. | advice: Add a scoped release/hosted evidence reconciliation check that applies only to new release tasks or provides an explicit baseline for legacy `DONE` plus pending artifacts. | rule: Release and hosted-close flows MUST NOT present newly closed tasks as `DONE` with pending verification when closure evidence exists. | evidence: task 202604281616-WG87DQ; commit c02ef92ed563 | enforcement: manual | fixability: repo-fixable | state: stabilized

diff --git a/.agentplane/policy/workflow.release.md b/.agentplane/policy/workflow.release.md
@@ -42,5 +42,5 @@ agentplane finish <task-id> --author <ROLE> --body "Verified: release" --result
 - MUST NOT bypass required notes validation.
 - MUST stop and request re-approval if release scope/tag/version changes.
 - In `direct`, `release apply --push --yes` is the publication route and may create/push the release tag.
-- In `branch_pr`, `release apply` is not the publication route; use `release candidate --push --yes`, merge the candidate into the protected base branch, then let hosted publish run from `main`.
+- In `branch_pr`, `release apply` is not the publication route; use `release candidate --push --yes`, merge the candidate into the protected base branch, then explicitly dispatch `Publish to npm` with the release commit `sha`.
 <!-- /ap:fragment -->
diff --git a/.agentplane/tasks/202605011419-H7MD9F/README.md b/.agentplane/tasks/202605011419-H7MD9F/README.md
@@ -0,0 +1,101 @@
+---
+id: "202605011419-H7MD9F"
+title: "Prepare v0.4.1 patch release"
+status: "DOING"
+priority: "high"
+owner: "CODER"
+revision: 7
+origin:
+  system: "manual"
+depends_on: []
+tags:
+  - "code"
+  - "release"
+verify: []
+plan_approval:
+  state: "approved"
+  updated_at: "2026-05-01T14:55:57.718Z"
+  updated_by: "ORCHESTRATOR"
+  note: null
+verification:
+  state: "pending"
+  updated_at: null
+  updated_by: null
+  note: null
+commit: null
+comments:
+  -
+    author: "CODER"
+    body: "Start: preparing the v0.4.1 branch_pr release candidate from current main, with release plan, notes, parity/prepublish checks, PR publication, and hosted publish evidence as the acceptance boundary."
+events:
+  -
+    type: "status"
+    at: "2026-05-01T14:20:47.054Z"
+    author: "CODER"
+    from: "TODO"
+    to: "DOING"
+    note: "Start: preparing the v0.4.1 branch_pr release candidate from current main, with release plan, notes, parity/prepublish checks, PR publication, and hosted publish evidence as the acceptance boundary."
+doc_version: 3
+doc_updated_at: "2026-05-01T14:55:47.195Z"
+doc_updated_by: "CODER"
+description: "Prepare the v0.4.1 release candidate from current main, including release plan, release notes, version parity, candidate branch, PR, hosted checks, and publication readiness evidence."
+sections:
+  Summary: |-
+    Prepare v0.4.1 patch release
+
+    Prepare the v0.4.1 release candidate from current main, including release plan, release notes, version parity, candidate branch, PR, hosted checks, and publication readiness evidence.
+  Scope: |-
+    - In scope: Prepare the v0.4.1 release candidate from current main, including release plan, release notes, version parity, candidate branch, PR, hosted checks, and publication readiness evidence.
+    - Out of scope: unrelated refactors not required for "Prepare v0.4.1 patch release".
+  Plan: "Release plan: version=0.4.1, tag=v0.4.1, scope=patch release from current main after v0.4.0. Additional approved scope from user: before continuing the release, correct the public recipes information architecture so the top-level Recipes section describes implemented installable signed recipes, and move Claude/Codex/Cursor/Aider/GitHub Actions/branch_pr copy-paste pages into workflow/integration guides instead of presenting them as installable recipes. Steps: generate release plan; consolidate recipe docs from implemented code and catalog inventory; write docs/releases/v0.4.1.md from v0.4.0..HEAD; run docs/recipes checks plus registry availability and release parity/prepublish gates; run branch_pr release candidate on dedicated worktree branch; open PR and wait for hosted checks; merge to main; verify hosted publish/tag/npm visibility or record exact blocker; clean stale merged task branches that are safe to remove. Out of scope: merging old backup/WIP local branches that are not proven release fixes."
+  Verify Steps: |-
+    1. Run `agentplane release plan --patch`. Expected: target is `0.4.1` / `v0.4.1` from current `v0.4.0` baseline.
+    2. Write and validate `docs/releases/v0.4.1.md` from `v0.4.0..HEAD`. Expected: release notes cover the release range and `node scripts/check-release-notes.mjs --version 0.4.1` passes.
+    3. Run registry/version gates. Expected: `node scripts/check-npm-version-availability.mjs --version 0.4.1`, `bun run release:parity`, and release candidate preflight pass.
+    4. Run `agentplane release candidate --push --yes` from the task worktree. Expected: versions and release artifacts are committed on the candidate branch, pushed, and no release tag is created locally before merge.
+    5. Open/merge the release PR after required hosted checks. Expected: `main` contains the release candidate and the task is closed through the branch_pr finish route.
+    6. Verify publication evidence. Expected: `v0.4.1` tag, GitHub Release or publish workflow outcome, and npm visibility for `agentplane`, `@agentplaneorg/core`, and `@agentplaneorg/recipes`; if hosted publish is still pending, record the exact workflow/blocker in Findings.
+  Verification: |-
+    <!-- BEGIN VERIFICATION RESULTS -->
+    <!-- END VERIFICATION RESULTS -->
+  Rollback Plan: |-
+    - Revert task-related commit(s).
+    - Re-run required checks to confirm rollback safety.
+  Findings: ""
+id_source: "generated"
+---
+## Summary
+
+Prepare v0.4.1 patch release
+
+Prepare the v0.4.1 release candidate from current main, including release plan, release notes, version parity, candidate branch, PR, hosted checks, and publication readiness evidence.
+
+## Scope
+
+- In scope: Prepare the v0.4.1 release candidate from current main, including release plan, release notes, version parity, candidate branch, PR, hosted checks, and publication readiness evidence.
+- Out of scope: unrelated refactors not required for "Prepare v0.4.1 patch release".
+
+## Plan
+
+Release plan: version=0.4.1, tag=v0.4.1, scope=patch release from current main after v0.4.0. Additional approved scope from user: before continuing the release, correct the public recipes information architecture so the top-level Recipes section describes implemented installable signed recipes, and move Claude/Codex/Cursor/Aider/GitHub Actions/branch_pr copy-paste pages into workflow/integration guides instead of presenting them as installable recipes. Steps: generate release plan; consolidate recipe docs from implemented code and catalog inventory; write docs/releases/v0.4.1.md from v0.4.0..HEAD; run docs/recipes checks plus registry availability and release parity/prepublish gates; run branch_pr release candidate on dedicated worktree branch; open PR and wait for hosted checks; merge to main; verify hosted publish/tag/npm visibility or record exact blocker; clean stale merged task branches that are safe to remove. Out of scope: merging old backup/WIP local branches that are not proven release fixes.
+
+## Verify Steps
+
+1. Run `agentplane release plan --patch`. Expected: target is `0.4.1` / `v0.4.1` from current `v0.4.0` baseline.
+2. Write and validate `docs/releases/v0.4.1.md` from `v0.4.0..HEAD`. Expected: release notes cover the release range and `node scripts/check-release-notes.mjs --version 0.4.1` passes.
+3. Run registry/version gates. Expected: `node scripts/check-npm-version-availability.mjs --version 0.4.1`, `bun run release:parity`, and release candidate preflight pass.
+4. Run `agentplane release candidate --push --yes` from the task worktree. Expected: versions and release artifacts are committed on the candidate branch, pushed, and no release tag is created locally before merge.
+5. Open/merge the release PR after required hosted checks. Expected: `main` contains the release candidate and the task is closed through the branch_pr finish route.
+6. Verify publication evidence. Expected: `v0.4.1` tag, GitHub Release or publish workflow outcome, and npm visibility for `agentplane`, `@agentplaneorg/core`, and `@agentplaneorg/recipes`; if hosted publish is still pending, record the exact workflow/blocker in Findings.
+
+## Verification
+
+<!-- BEGIN VERIFICATION RESULTS -->
+<!-- END VERIFICATION RESULTS -->
+
+## Rollback Plan
+
+- Revert task-related commit(s).
+- Re-run required checks to confirm rollback safety.
+
+## Findings
diff --git a/.agentplane/tasks/202605011419-H7MD9F/pr/diffstat.txt b/.agentplane/tasks/202605011419-H7MD9F/pr/diffstat.txt
@@ -0,0 +1,43 @@
+ .agentplane/config.json                            |   2 +-
+ .agentplane/policy/incidents.md                    |   1 +
+ .agentplane/policy/workflow.release.md             |   2 +-
+ .github/workflows/publish.yml                      |   2 +-
+ README.md                                          |  21 +-
+ .../documentation-information-architecture.mdx     |  14 +-
+ docs/developer/release-and-publishing.mdx          |   4 +-
+ docs/help/troubleshooting.mdx                      |   2 +-
+ docs/index.mdx                                     |  23 +-
+ docs/recipes/code-map.mdx                          |  89 ++++++++
+ docs/recipes/index.mdx                             | 101 ++++++---
+ docs/reference/generated-reference.mdx             |   6 +-
+ docs/releases/v0.4.1.md                            | 245 +++++++++++++++++++++
+ docs/user/cli-reference.generated.mdx              |   2 +-
+ docs/user/commands.mdx                             |   9 +-
+ docs/user/overview.mdx                             |   5 +-
+ docs/user/setup.mdx                                |   7 +-
+ docs/user/website-ia.mdx                           |  39 ++--
+ docs/{recipes => workflow-guides}/aider.mdx        |   0
+ docs/{recipes => workflow-guides}/branch-pr.mdx    |   0
+ docs/{recipes => workflow-guides}/claude-code.mdx  |   0
+ docs/{recipes => workflow-guides}/codex.mdx        |   0
+ docs/{recipes => workflow-guides}/cursor.mdx       |   0
+ .../github-actions.mdx                             |   0
+ docs/workflow-guides/index.mdx                     |  29 +++
+ packages/agentplane/README.md                      |  19 +-
+ packages/agentplane/assets/policy/incidents.md     |   1 +
+ .../agentplane/assets/policy/workflow.release.md   |   2 +-
+ packages/agentplane/package.json                   |   6 +-
+ .../src/commands/release/apply.command.ts          |   2 +-
+ .../commands/release/apply.pipeline/preflight.ts   |   2 +-
+ .../agentplane/src/commands/release/apply.spec.ts  |   2 +-
+ .../release/publish-workflow-contract.test.ts      |   3 +
+ packages/core/package.json                         |   2 +-
+ packages/recipes/package.json                      |   2 +-
+ packages/recipes/src/index.ts                      |   2 +-
+ packages/testkit/package.json                      |   2 +-
+ scripts/baselines/knip-baseline.json               | 150 ++++++++-----
+ scripts/check-docs-ia.mjs                          |  14 +-
+ scripts/generate-release-distribution.mjs          |   4 +-
+ website/sidebars.ts                                |  21 +-
+ website/src/data/homepage-content.ts               |   9 +-
+ 42 files changed, 663 insertions(+), 183 deletions(-)
diff --git a/.agentplane/tasks/202605011419-H7MD9F/pr/github-body.md b/.agentplane/tasks/202605011419-H7MD9F/pr/github-body.md
@@ -0,0 +1,75 @@
+## Summary
+
+Prepare v0.4.1 patch release
+
+Prepare the v0.4.1 release candidate from current main, including release plan, release notes, version parity, candidate branch, PR, hosted checks, and publication readiness evidence.
+
+## Scope
+
+- In scope: Prepare the v0.4.1 release candidate from current main, including release plan, release notes, version parity, candidate branch, PR, hosted checks, and publication readiness evidence.
+- Out of scope: unrelated refactors not required for "Prepare v0.4.1 patch release".
+
+## Verification
+
+- State: pending
+- Note: Not recorded yet.
+- Full verification checklist lives in local review.md.
+
+## Handoff Notes
+
+- No handoff notes recorded yet. Use `agentplane pr note ...` to append one.
+
+<details>
+<summary>Raw evidence</summary>
+
+- Updated: 2026-05-01T17:56:41.668Z
+- Branch: task/202605011419-H7MD9F/v0-4-1-release-candidate
+- Head: 4f050552ec34
+
+```text
+ .agentplane/config.json                            |   2 +-
+ .agentplane/policy/incidents.md                    |   1 +
+ .agentplane/policy/workflow.release.md             |   2 +-
+ .github/workflows/publish.yml                      |   2 +-
+ README.md                                          |  21 +-
+ .../documentation-information-architecture.mdx     |  14 +-
+ docs/developer/release-and-publishing.mdx          |   4 +-
+ docs/help/troubleshooting.mdx                      |   2 +-
+ docs/index.mdx                                     |  23 +-
+ docs/recipes/code-map.mdx                          |  89 ++++++++
+ docs/recipes/index.mdx                             | 101 ++++++---
+ docs/reference/generated-reference.mdx             |   6 +-
+ docs/releases/v0.4.1.md                            | 245 +++++++++++++++++++++
+ docs/user/cli-reference.generated.mdx              |   2 +-
+ docs/user/commands.mdx                             |   9 +-
+ docs/user/overview.mdx                             |   5 +-
+ docs/user/setup.mdx                                |   7 +-
+ docs/user/website-ia.mdx                           |  39 ++--
+ docs/{recipes => workflow-guides}/aider.mdx        |   0
+ docs/{recipes => workflow-guides}/branch-pr.mdx    |   0
+ docs/{recipes => workflow-guides}/claude-code.mdx  |   0
+ docs/{recipes => workflow-guides}/codex.mdx        |   0
+ docs/{recipes => workflow-guides}/cursor.mdx       |   0
+ .../github-actions.mdx                             |   0
+ docs/workflow-guides/index.mdx                     |  29 +++
+ packages/agentplane/README.md                      |  19 +-
+ packages/agentplane/assets/policy/incidents.md     |   1 +
+ .../agentplane/assets/policy/workflow.release.md   |   2 +-
+ packages/agentplane/package.json                   |   6 +-
+ .../src/commands/release/apply.command.ts          |   2 +-
+ .../commands/release/apply.pipeline/preflight.ts   |   2 +-
+ .../agentplane/src/commands/release/apply.spec.ts  |   2 +-
+ .../release/publish-workflow-contract.test.ts      |   3 +
+ packages/core/package.json                         |   2 +-
+ packages/recipes/package.json                      |   2 +-
+ packages/recipes/src/index.ts                      |   2 +-
+ packages/testkit/package.json                      |   2 +-
+ scripts/baselines/knip-baseline.json               | 150 ++++++++-----
+ scripts/check-docs-ia.mjs                          |  14 +-
+ scripts/generate-release-distribution.mjs          |   4 +-
+ website/sidebars.ts                                |  21 +-
+ website/src/data/homepage-content.ts               |   9 +-
+ 42 files changed, 663 insertions(+), 183 deletions(-)
+```
+
+</details>
diff --git a/.agentplane/tasks/202605011419-H7MD9F/pr/github-title.txt b/.agentplane/tasks/202605011419-H7MD9F/pr/github-title.txt
@@ -0,0 +1 @@
+release: Prepare v0.4.1 patch release (H7MD9F)
diff --git a/.agentplane/tasks/202605011419-H7MD9F/pr/meta.json b/.agentplane/tasks/202605011419-H7MD9F/pr/meta.json
@@ -0,0 +1,14 @@
+{
+  "base": "main",
+  "branch": "task/202605011419-H7MD9F/v0-4-1-release-candidate",
+  "created_at": "2026-05-01T14:20:47.251Z",
+  "head_sha": "4f050552ec342e2f99357dd1b1225858e695d1f9",
+  "last_verified_at": null,
+  "last_verified_sha": null,
+  "schema_version": 1,
+  "task_id": "202605011419-H7MD9F",
+  "updated_at": "2026-05-01T17:56:41.668Z",
+  "verify": {
+    "status": "skipped"
+  }
+}
diff --git a/.agentplane/tasks/202605011419-H7MD9F/pr/notes.jsonl b/.agentplane/tasks/202605011419-H7MD9F/pr/notes.jsonl