agentplane 0.3.29 → 0.4.1

package/assets/policy/examples/unit-test-pattern.md

@@ -1,3 +1,5 @@
+<!-- ap:fragment id="policy.examples.unit-test-pattern.example.example.unit.test.pattern" slot="example" mutability="replaceable" -->
+
 # Example: Unit Test Pattern
 
 ```ts
@@ -17,3 +19,5 @@ describe("policy routing check", () => {
   });
 });
 ```
+
+<!-- /ap:fragment -->

package/assets/policy/governance.md

@@ -1,5 +1,10 @@
+<!-- ap:fragment id="policy.governance.body.policy.governance" slot="body" mutability="replaceable" -->
+
 # Policy Governance
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="policy.governance.source_of_truth.incident.source.of.truth" slot="source_of_truth" mutability="replaceable" -->
+
 ## Incident source of truth
 
 - `.agentplane/policy/incidents.md` is the active incident registry for unresolved incidents that still need operator attention or follow-up engineering work.
@@ -11,6 +16,9 @@
 - Normal startup MUST NOT bulk-load `incidents.md`; targeted lookup for analogous work is allowed through `task start-ready` and `agentplane incidents advise`.
 - Closed incidents MAY be removed from `.agentplane/policy/incidents.md`, but only after their final state and evidence have been preserved in `docs/developer/incident-archive.mdx`.
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="policy.governance.hard_constraint.stabilization.criteria" slot="hard_constraint" mutability="append_only" -->
+
 ## Stabilization criteria
 
 Use `stabilized` only when the same failure class recurs at least 2 times in 30 days.
@@ -23,19 +31,29 @@ Promotion from `incidents.md` into canonical policy modules is allowed only when
 2. Enforcement is defined (`CI`, `test`, `lint`, or policy check script).
 3. Policy gateway load rules are updated if routing behavior changes.
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="policy.governance.hard_constraint.canonical.module.immutability" slot="hard_constraint" mutability="append_only" -->
+
 ## Canonical module immutability
 
 - Canonical modules are immutable by default during feature delivery tasks.
 - Canonical modules MAY be changed only in a dedicated policy task with explicit user approval.
 - Every canonical policy edit MUST include `node .agentplane/policy/check-routing.mjs` in verification evidence.
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="policy.governance.hard_constraint.policy.budget" slot="hard_constraint" mutability="append_only" -->
+
 ## Policy budget
 
 - The policy gateway file (`AGENTS.md` or `CLAUDE.md`) MUST remain compact (target <= 250 lines).
 - Detailed procedures MUST be placed in canonical modules listed in the gateway file.
 - If a policy change needs >20 new lines in the gateway file, move detail to a module and keep only routing + hard gate in gateway.
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="policy.governance.hard_constraint.rule.quality" slot="hard_constraint" mutability="append_only" -->
+
 ## Rule quality
 
 - MUST rules should be enforceable by tooling where possible.
 - Non-enforceable guidance should be marked as SHOULD and kept out of hard-gate sections.
+<!-- /ap:fragment -->

package/assets/policy/incidents.md

@@ -1,22 +1,12 @@
 # Policy Incidents Log
 
 - Append-only. Required fields: `id`, `date`, `scope`, `failure`, `rule`, `evidence`, `enforcement`, `state`; optional: `tags`, `match`, `advice`, `source_task`, `fixability`.
-- id: INC-20260417-01 | date: 2026-04-17 | scope: Remove version drift by updating packages/recipes version surfaces, dependency pins, and generated references to the current 0.3.13 workspace version. | tags: code, recipes, workflow | match: code, recipes, workflow, remove, version, drift, updating, packages, surfaces, dependency, pins, and, generated, references, the, current | failure: Updated recipes package metadata, dependency pins, docs reference, and release parity checks to include @agentplaneorg/recipes. | advice: Aligned version surfaces to 0.3.13 and extended the parity checker plus tests to enforce recipes parity going forward. | rule: Analogous Remove version drift by updating packages/recipes version surfaces, dependency pins, and generated references to the current 0.3.13 workspace version. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604171154-1WZZJK; commit 45ed50d51883 | enforcement: manual | fixability: external | state: open
-- id: INC-20260417-02 | date: 2026-04-17 | scope: Remove version drift by updating packages/recipes version surfaces, dependency pins, and generated references to the current 0.3.13 workspace version. | tags: code, recipes, workflow | match: code, recipes, workflow, remove, version, drift, updating, packages, surfaces, dependency, pins, and, generated, references, the, current | failure: Aligned recipes version metadata, dependency pins, lockfile, and release check scripts so both parity and npm availability treat @agentplaneorg/recipes as a first-class release package. | advice: Updated release parity and npm availability scripts plus tests, then re-ran focused release checks. | rule: Analogous Remove version drift by updating packages/recipes version surfaces, dependency pins, and generated references to the current 0.3.13 workspace version. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604171154-1WZZJK; commit 45ed50d51883 | enforcement: manual | fixability: external | state: open
-- id: INC-20260417-03 | date: 2026-04-17 | scope: Remove scenario-centric commands and help from the public recipes product surface so recipes stop presenting a second parallel runtime model. | tags: code, recipes, workflow | match: code, recipes, workflow, remove, scenario, centric, commands, and, help, from, the, public, product, surface, stop, presenting | failure: Removed recipes scenario commands from the public command catalog, regenerated CLI/docs inventory, and updated user/developer guidance plus help/tests to treat scenario assets as recipe-owned internals. | advice: Regenerated CLI reference and recipes inventory, updated prompt assets, and reran focused command-catalog/help tests plus freshness checks. | rule: Analogous Remove scenario-centric commands and help from the public recipes product surface so recipes stop presenting a second parallel runtime model. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604171155-V21N6H; commit e6b8c732614a | enforcement: manual | fixability: external | state: open
-- id: INC-20260417-04 | date: 2026-04-17 | scope: Make overlay when matching conjunctive, propagate command context into runtime matching, and either fully support or remove dead command matching fields. | tags: code, recipes, workflow | match: code, recipes, workflow, make, overlay, when, matching, conjunctive, propagate, command, context, into, runtime, and, either, fully | failure: Overlay fragments with combined when predicates now require every configured predicate, and runner prompt assembly forwards command context. | advice: Replaced else-if matching with conjunctive checks, added command propagation from runner target, and covered both layers with focused tests. | rule: Analogous Make overlay when matching conjunctive, propagate command context into runtime matching, and either fully support or remove dead command matching fields. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604171154-4M51J8; commit b09dcb42e0d3 | enforcement: manual | fixability: external | state: open
-- id: INC-20260419-01 | date: 2026-04-19 | scope: Make pr open tolerate an already-published branch and continue PR creation when remote HEAD already matches the local branch, instead of failing on an unnecessary internal push path. | tags: workflow | match: workflow, make, open, tolerate, already, published, branch, and, continue, creation, when, remote, head, matches, the, local | failure: pr open always retried git push before remote PR creation, even when origin already had the same branch head. | advice: Compare the local branch tip to the remote push target after a publish failure, accept an exact match, and cover it with a regression test. | rule: Analogous Make pr open tolerate an already-published branch and continue PR creation when remote HEAD already matches the local branch, instead of failing on an unnecessary internal push path. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604191200-N6XPEJ; commit 7ed61866fbab | enforcement: manual | fixability: external | state: open
-- id: INC-20260419-02 | date: 2026-04-19 | scope: Short-circuit manual close-tail and hosted-close-pr flows when the canonical close commit is already present on main, so branch_pr users cannot create obsolete closure PRs after hosted automation has already closed the task. | tags: workflow | match: workflow, short, circuit, manual, close, tail, and, hosted, flows, when, the, canonical, commit, already, present, main | failure: After hosted closure landed on main, both manual finish --close-commit and task hosted-close-pr could still generate obsolete closure tails or PRs. | advice: Treat base-side canonical closure as a first-class no-op condition: skip branch_pr close-tail materialization when no fresh task artifacts remain, and short-circuit hosted-close-pr before any remote recovery calls when task status/commit already match the merged commit. | rule: Analogous Short-circuit manual close-tail and hosted-close-pr flows when the canonical close commit is already present on main, so branch_pr users cannot create obsolete closure PRs after hosted automation has already closed the task. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604191200-G7YHZY; commit fbc5422f0dfb | enforcement: manual | fixability: external | state: open
-- id: INC-20260419-03 | date: 2026-04-19 | scope: Epic E′. Migrate the remaining CLI test consumers away from run-cli.test-helpers.ts and delete the shim once no imports remain. | tags: code, refactor, testkit | match: code, refactor, testkit, epic, migrate, the, remaining, cli, test, consumers, away, from, run, helpers, and, delete | failure: No imports reference run-cli.test-helpers.js under packages/agentplane/src; heavy CLI suites passed after rerunning unstable PR-flow files in single-worker mode; framework bootstrap refreshed the repo-local runtime after shim deletion. | advice: Validated the migrated CLI batches, removed the shim, rebuilt the repo-local runtime, and recorded the single-worker workaround needed for the two slow PR-flow suites. | rule: Analogous Epic E′. Migrate the remaining CLI test consumers away from run-cli.test-helpers.ts and delete the shim once no imports remain. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604191639-7SDT2H; commit e32f55f97171 | enforcement: manual | fixability: external | state: open
-- id: INC-20260419-04 | date: 2026-04-19 | scope: Epic E′. Add shared tempRepo, mockTaskBackend, mockPrApi, and mockConfig fixtures in @agentplane/testkit and replace duplicated local helpers. | tags: code, refactor, testkit | match: code, refactor, testkit, epic, add, shared, temprepo, mocktaskbackend, mockprapi, and, mockconfig, fixtures, agentplane, replace, duplicated, local | failure: Introduced tempRepo, mockConfig, mockTaskBackend, and fake GH PR helpers in @agentplane/testkit; extended the agentplane testing compatibility layer; task-backend and targeted pr-flow PR consumers now use the shared fixtures and pass. | advice: Added shared fixture modules, exported them through testkit and the compatibility layer, then validated the new surface with testkit build plus focused task-backend and pr-flow PR tests. | rule: Analogous Epic E′. Add shared tempRepo, mockTaskBackend, mockPrApi, and mockConfig fixtures in @agentplane/testkit and replace duplicated local helpers. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604191639-DPNT53; commit 14c41a30bcdc | enforcement: manual | fixability: external | state: open
-- id: INC-20260419-05 | date: 2026-04-19 | scope: Epic E′. Move describeWhenEnvPresent, describeCritical, and describeWhenNotHook helpers into @agentplane/testkit with typed exports. | tags: code, refactor, testkit | match: code, refactor, testkit, epic, move, describewhenenvpresent, describecritical, and, describewhennothook, helpers, into, agentplane, with, typed, exports, publish | failure: Added describeWhenEnvPresent, describeWhenNotHook, and describeCritical to @agentplane/testkit, exported them through the compatibility surface, and migrated the current redmine live, release/upgrade hook-gated, and CLI critical suites. | advice: Implemented typed wrappers in testkit, added explicit compatibility re-exports, rebuilt testkit, and validated all current consumers with focused Vitest coverage. | rule: Analogous Epic E′. Move describeWhenEnvPresent, describeCritical, and describeWhenNotHook helpers into @agentplane/testkit with typed exports. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604191639-PVRQFY; commit ad42ce782481 | enforcement: manual | fixability: external | state: open
-- id: INC-20260419-06 | date: 2026-04-19 | scope: Epic A′. Switch config loading to the canonical Zod validator and keep compare-mode safety where still needed. | tags: code, refactor, schemas | match: code, refactor, schemas, epic, switch, config, loading, the, canonical, zod, validator, and, keep, compare, mode, safety | failure: Focused config tests, core typecheck, and core build all passed after the import and export surface change. | advice: No further action in this atom; remaining A′ work can build on the direct schema implementation surface. | rule: Analogous Epic A′. Switch config loading to the canonical Zod validator and keep compare-mode safety where still needed. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604191639-STZFC6; commit 82a313b2cab1 | enforcement: manual | fixability: external | state: open
-- id: INC-20260420-01 | date: 2026-04-20 | scope: Audit CLI path resolution for global-install style layouts, fix any repo-local script path defects, and add regression tests that fail when installed CLI code resolves repository scripts from the global package location. | tags: bugfix, code, hooks | match: bugfix, code, hooks, audit, cli, path, resolution, for, global, install, style, layouts, fix, any, repo, local | failure: Audited import.meta.url/fileURLToPath candidates touching scripts/bin paths. The real repo-script risk was pre-push fallback returning a non-existent global prefix path; workflow-playbook's bin path is package-bundled and covered by existing workflow tests. | advice: Pre-push script resolution now returns repository-local script first, existing bundled fallback second, otherwise null with an actionable repository-local error message. | rule: Analogous Audit CLI path resolution for global-install style layouts, fix any repo-local script path defects, and add regression tests that fail when installed CLI code resolves repository scripts from the global package location. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604200850-9T6FTC; commit d30a706ce568 | enforcement: manual | fixability: external | state: open
-- id: INC-20260422-01 | date: 2026-04-22 | scope: Runner prompt assembly only. Do not cache task-specific prompt content or mutable task state. | tags: cache, perf, runner | match: cache, perf, runner, prompt, assembly, only, not, task, specific, content, mutable, state, source, avoid, repeated, scanning | failure: Cached bundled agent templates, bundled policy gateway templates, and framework runner prompt assembly; repo-local policy/profile reads use mtime/size validation so changed files are not stale. | advice: Added regression coverage for repeated static prompt reuse and repo-local prompt cache invalidation. | rule: Analogous Runner prompt assembly only. Do not cache task-specific prompt content or mutable task state. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604220255-AQHZT4; commit 268c42af4447 | enforcement: manual | fixability: external | state: open
-- id: INC-20260422-02 | date: 2026-04-22 | scope: Publish the next patch release containing the init cached recipe manifest compatibility fix and restored interactive init ASCII logo. | tags: ci, init, release | match: ci, init, release, publish, the, next, patch, containing, cached, recipe, manifest, compatibility, fix, and, restored, interactive | failure: Pre-push release-mode hook failed when inherited test execution changed shared git core.bare=true; restored local core.bare=false and confirmed remote tag v0.3.19 points at main merge commit 45ba9c57. | advice: Use hosted release workflow as publication evidence; record local hook pollution as a release-process follow-up rather than blocking this hotfix. | rule: Analogous Publish the next patch release containing the init cached recipe manifest compatibility fix and restored interactive init ASCII logo. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604221605-SQYRNQ; commit 45ba9c57f939 | enforcement: manual | fixability: external | state: open
-- id: INC-20260422-03 | date: 2026-04-22 | scope: Create an executable v0.4 implementation task graph for modular prompt assembly, grouped into epics with atomic tasks and dependencies. | tags: architecture, planning, prompt-assembly, v0.4 | match: architecture, planning, prompt-assembly, v0.4, create, executable, implementation, task, graph, for, modular, prompt, assembly, grouped, into, epics | failure: task graph contains 30 new planned tasks plus the active decomposition task | advice: Validated with task list filtering, task file count, agentplane doctor, and git diff whitespace check | rule: Analogous Create an executable v0.4 implementation task graph for modular prompt assembly, grouped into epics with atomic tasks and dependencies. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604221536-1Z90V4; commit 3047ee2197c0 | enforcement: manual | fixability: external | state: open
-- id: INC-20260423-01 | date: 2026-04-23 | scope: commit allowlist staging behavior and diagnostics for active task artifacts. Out of scope: broad commit policy rewrites or protected path model changes. | tags: code, git, workflow | match: code, git, workflow, commit, allowlist, staging, behavior, and, diagnostics, for, active, task, artifacts, out, scope, broad | failure: Ran bun run test:project -- cli-core packages/agentplane/src/cli/run-cli.core.guard.commit-wrapper.test.ts; bun run test:project -- guard; Prettier check for changed files. | advice: Added non-empty-index staging before guard validation and regression coverage. | rule: Analogous commit allowlist staging behavior and diagnostics for active task artifacts. Out of scope: broad commit policy rewrites or protected path model changes. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604230838-598K1H; commit afa741361351 | enforcement: manual | fixability: external | state: open
-- id: INC-20260423-02 | date: 2026-04-23 | scope: generated guidance and default examples for test commands. Out of scope: rewriting historical release notes or changing user-supplied task verify commands. | tags: code, guidance, testing | match: code, guidance, testing, generated, and, default, examples, for, test, commands, out, scope, rewriting, historical, release, notes | failure: Ran bun run test:project -- cli-core packages/agentplane/src/cli/run-cli.core.tasks.scaffold-derive.test.ts; bun run workflows:command-check; bun run docs:cli:check; Prettier check for changed files. | advice: Updated task derive example/test fixture and expanded workflow command contract scanning to command specs. | rule: Analogous generated guidance and default examples for test commands. Out of scope: rewriting historical release notes or changing user-supplied task verify commands. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604230839-Y92ZJJ; commit 7e088c735372 | enforcement: manual | fixability: external | state: open
-- id: INC-20260423-03 | date: 2026-04-23 | scope: Move managed hook shim readiness checks out of doctor/workspace.ts so hotspot gate passes after installed-user diagnostics additions. | tags: code, quality | match: code, quality, move, managed, hook, shim, readiness, checks, out, doctor, workspace, hotspot, gate, passes, after, installed | failure: Ran bun run hotspots:check; bun run test:project -- agentplane packages/agentplane/src/commands/doctor.command.runtime.test.ts; Prettier check for changed files. | advice: Extracted hook readiness diagnostics to doctor/hook-readiness.ts and updated oversized test baseline for already-grown warning files. | rule: Analogous Move managed hook shim readiness checks out of doctor/workspace.ts so hotspot gate passes after installed-user diagnostics additions. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604230949-E1BG2Q; commit 2fc331ddf503 | enforcement: manual | fixability: external | state: open
-- id: INC-20260424-01 | date: 2026-04-24 | scope: Collapse parallel init UI routes into a single orchestrator, preserve non-TTY preset behavior, and remove obsolete interactive init compatibility flags. | tags: cli, init, v0.3 | match: cli, init, v0.3, collapse, into, single, orchestrator, preserve, non, tty, preset, behavior, and, remove, obsolete, interactive | failure: Unified orchestrator now uses one answer/apply flow for Clack, --yes, plain prompt mode, and non-TTY setup profiles. | advice: Remove legacy compatibility aliases from the public init surface; keep default TTY, --yes, non-TTY, and AGENTPLANE_PROMPTS=plain routes covered. | rule: Analogous Collapse parallel init UI routes into a single orchestrator, preserve non-TTY preset behavior, and remove obsolete interactive init compatibility flags. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604241136-RTDFZS; commit 174837465c08 | enforcement: manual | fixability: external | state: open
-- id: INC-20260424-02 | date: 2026-04-24 | scope: Implement repo-neutral workflow scope, artifact and package gates, sanitized build manifest, init recipe install paths, roadmap 0.6, and current-code documentation cleanup. | tags: code | match: code, implement, repo, neutral, workflow, scope, artifact, and, package, gates, sanitized, build, manifest, init, recipe, install | failure: node .agentplane/policy/check-routing.mjs, artifact/task/package gates, local tarball install smoke, docs freshness checks, focused init/runtime tests, typecheck, lint, doctor, and bun run release:ci-check all passed. | advice: Implemented gates, docs/runtime updates, sanitized npm manifest flow, init recipe install path capture, and roadmap 0.6 eval-system entry. | rule: Analogous Implement repo-neutral workflow scope, artifact and package gates, sanitized build manifest, init recipe install paths, roadmap 0.6, and current-code documentation cleanup. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604241914-FRBSYS; commit 2315c795be6a | enforcement: manual | fixability: external | state: open
+- 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
+- id: INC-20260430-01 | date: 2026-04-30 | scope: Make release hygiene pass by reconciling generated project agent and policy mirrors with canonical framework prompt assets after the fragmented prompt migration. Scope is limited to sync output and any minimal follow-up needed for agents:check. | tags: agents, policy, release | match: agents, policy, release, make, hygiene, pass, reconciling, generated, project, agent, and, mirrors, with, canonical, framework, prompt | failure: bun run agents:check initially failed because target .agentplane agent and policy mirrors lagged the canonical fragmented prompt assets. | advice: Ran bun run agents:sync and verified the generated mirror output. | rule: Analogous Make release hygiene pass by reconciling generated project agent and policy mirrors with canonical framework prompt assets after the fragmented prompt migration. Scope is limited to sync output and any minimal follow-up needed for agents:check. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604300724-ZTGZYT; commit ac0e1ff930ed | enforcement: manual | fixability: external | state: open
+- id: INC-20260429-01 | date: 2026-04-29 | scope: recipe manifest/project overlay parsing for prompt module declarations and mutation sets. | tags: code, prompt-assembly, recipes, schemas | match: code, prompt-assembly, recipes, schemas, recipe, manifest, project, overlay, parsing, for, prompt, module, declarations, and, mutation, sets | failure: Checks passed: bun test packages/agentplane/src/commands/recipes/impl/project-installed-recipes.test.ts packages/agentplane/src/commands/recipes/impl/resolver.test.ts packages/agentplane/src/commands/recipes.transaction.test.ts packages/agentplane/src/runtime/prompt-modules/mutations.test.ts; bun run typecheck; git diff --check; bun run framework:dev:bootstrap; agentplane doctor; extra bun test packages/recipes/src/index.test.ts packages/recipes/src/overlay.test.ts; targeted eslint on touched files. | advice: No prompt graph application was added in this step; that remains for the dependent recipe application task. | rule: Analogous recipe manifest/project overlay parsing for prompt module declarations and mutation sets. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604291531-Z6XH6Q; commit c69211301720 | enforcement: manual | fixability: external | state: open
+- id: INC-20260429-02 | date: 2026-04-29 | scope: apply active recipe prompt module mutations during project overlay/prompt graph refresh. | tags: code, prompt-assembly, recipes, workflow | match: code, prompt-assembly, recipes, workflow, apply, active, recipe, prompt, module, mutations, during, project, overlay, graph, refresh, compiled | failure: Checks passed: agentplane doctor; bun run framework:dev:bootstrap; bun run typecheck; bun test packages/agentplane/src/commands/recipes/impl/overlay-project.test.ts packages/agentplane/src/commands/recipes.transaction.test.ts packages/agentplane/src/commands/recipes.catalog-install.test.ts packages/agentplane/src/runtime/prompt-modules/compiler.test.ts; git diff --check; extra bun test packages/agentplane/src/commands/recipes/impl/project-installed-recipes.test.ts; targeted eslint on touched files. | advice: Runner/runtime consumption and drift diagnostics remain scoped to the following diagnostic task. | rule: Analogous apply active recipe prompt module mutations during project overlay/prompt graph refresh. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604291531-N0H28A; commit ac327dd2b0c1 | enforcement: manual | fixability: external | state: open
+- id: INC-20260430-02 | date: 2026-04-30 | scope: Add an automated docs information-architecture guard that checks docs/index.mdx and website/sidebars.ts alignment, catches orphan current docs, and fails on markdown references to repository paths that no longer exist. | tags: code, docs-ia, tooling | match: code, docs-ia, tooling, add, automated, docs, information, architecture, guard, that, checks, index, mdx, and, website, sidebars | failure: docs:site:typecheck emits untracked website/\*.js files in this repo; they were removed before docs:site:build. Build then passed. | advice: Task implementation commit is 7a95d2ca with generated task artifact refresh c5166206. | rule: Analogous Add an automated docs information-architecture guard that checks docs/index.mdx and website/sidebars.ts alignment, catches orphan current docs, and fails on markdown references to repository paths that no longer exist. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604301955-HKY8NW; commit 00031a6f3ac9 | enforcement: manual | fixability: external | state: open
+- id: INC-20260430-03 | date: 2026-04-30 | scope: Add an automated docs information-architecture guard that checks docs/index.mdx and website/sidebars.ts alignment, catches orphan current docs, and fails on markdown references to repository paths that no longer exist. | tags: code, docs-ia, tooling | match: code, docs-ia, tooling, add, automated, docs, information, architecture, guard, that, checks, index, mdx, and, website, sidebars | failure: Remote Docs CI failed before this fix on docs/developer/project-layout.mdx referencing packages/agentplane/dist/. That path is generated output, not a required tracked source path. | advice: Follow-up fix commit is 4ab6c548 with artifact refresh 5685436b. | rule: Analogous Add an automated docs information-architecture guard that checks docs/index.mdx and website/sidebars.ts alignment, catches orphan current docs, and fails on markdown references to repository paths that no longer exist. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604301955-HKY8NW; commit 00031a6f3ac9 | enforcement: manual | fixability: external | state: open
+- id: INC-20260501-01 | date: 2026-05-01 | scope: Run final integrated verification for the refactor wave and record any residual gaps. | tags: code | match: code, run, final, integrated, verification, for, the, refactor, wave, and, record, any, residual, gaps, normalized, compiled | failure: ci:local:full passed after focused init/platform-critical regression checks; framework:dev:bootstrap, agentplane doctor, policy routing, and spec:examples smoke also passed. | advice: Normalized compiled init prompt asset output to one trailing newline and updated the direct-mode agent-template expectation to account for policy gateway rendering. | rule: Analogous Run final integrated verification for the refactor wave and record any residual gaps. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202605010645-3W3EXR; commit b48a260fa73d | enforcement: manual | fixability: external | state: open
+- id: INC-20260501-02 | date: 2026-05-01 | scope: Submit a GitHub PR adding AgentPlane to brandonhimpfen/awesome-ai-coding-agents as workflow infrastructure for AI coding agents after checking scope alignment, formatting, and category placement. | tags: docs | match: docs, submit, github, adding, agentplane, brandonhimpfen, awesome, coding, agents, workflow, infrastructure, for, after, checking, scope, alignment | failure: Added AgentPlane to brandonhimpfen/awesome-ai-coding-agents under Agent Infrastructure using repo-local AI coding-agent workflow wording. Opened https://github.com/brandonhimpfen/awesome-ai-coding-agents/pull/8 with --body-file and verified gh pr view body renders with Markdown line breaks. Ran git diff --check, python3 .github/scripts/awesome_list_lint.py, python3 .github/scripts/detect_duplicate_links.py, python3 check_readme_links.py README.md --timeout 8, node .agentplane/policy/check-routing.mjs, and agentplane doctor. | advice: Upstream PR is open. Target repo link checker confirmed the AgentPlane URL as 200 but exits non-zero because the pre-existing agentcoder/AgentCoder entry returns 404; this is disclosed in the PR body. | rule: Analogous Submit a GitHub PR adding AgentPlane to brandonhimpfen/awesome-ai-coding-agents as workflow infrastructure for AI coding agents after checking scope alignment, formatting, and category placement. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202605011518-PH7024; commit cb1fe303f97a | enforcement: manual | fixability: external | state: open

package/assets/policy/security.must.md

@@ -1,3 +1,5 @@
+<!-- ap:fragment id="policy.security.must.hard_constraint.security.must.rules" slot="hard_constraint" mutability="append_only" -->
+
 # Security MUST Rules
 
 - MUST NOT commit secrets, credentials, or private keys.
@@ -5,3 +7,4 @@
 - MUST NOT perform network actions when approval is required and not granted.
 - MUST NOT modify auth/crypto/security-critical codepaths without explicit scope approval.
 - MUST report security-sensitive drift immediately and stop before mutation.
+<!-- /ap:fragment -->

package/assets/policy/workflow.branch_pr.md

@@ -1,7 +1,12 @@
+<!-- ap:fragment id="policy.workflow.branch_pr.workflow.workflow.branch_pr" slot="workflow" mutability="replaceable" -->
+
 # Workflow: branch_pr
 
 Use this module when `workflow_mode=branch_pr`.
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="policy.workflow.branch_pr.workflow.required.sequence" slot="workflow" mutability="replaceable" -->
+
 ## Required sequence
 
 1. CHECKPOINT A: plan/approve on base checkout.
@@ -14,6 +19,9 @@ Use this module when `workflow_mode=branch_pr`.
 8. CHECKPOINT C: finish task(s) on base with verification evidence.
 9. Remove merged task branches/worktrees once the hosted-close/finish route has landed.
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="policy.workflow.branch_pr.commands.command.contract" slot="commands" mutability="replaceable" -->
+
 ## Command contract
 
 ```bash
@@ -26,6 +34,9 @@ agentplane integrate <task-id> --branch task/<task-id>/<slug> --run-verify
 agentplane finish <task-id> --author INTEGRATOR --body "Verified: ..." --result "..." --commit <git-rev> --close-commit
 ```
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="policy.workflow.branch_pr.hard_constraint.constraints" slot="hard_constraint" mutability="append_only" -->
+
 ## Constraints
 
 - MUST NOT perform mutating actions before explicit user approval.
@@ -40,3 +51,4 @@ agentplane finish <task-id> --author INTEGRATOR --body "Verified: ..." --result
 - Planning and closure happen on base checkout.
 - Do not export task snapshots from task branches.
 - After merged closure, remove stale task branches/worktrees via the cleanup route instead of leaving orphaned local state behind.
+<!-- /ap:fragment -->

package/assets/policy/workflow.direct.md

@@ -1,7 +1,12 @@
+<!-- ap:fragment id="policy.workflow.direct.workflow.workflow.direct" slot="workflow" mutability="replaceable" -->
+
 # Workflow: direct
 
 Use this module when `workflow_mode=direct`.
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="policy.workflow.direct.workflow.required.sequence" slot="workflow" mutability="replaceable" -->
+
 ## Required sequence
 
 1. CHECKPOINT A: run preflight and publish summary.
@@ -17,6 +22,9 @@ Use this module when `workflow_mode=direct`.
 8. Record verification result (`agentplane verify ...`) for the task scope.
 9. CHECKPOINT C: finish task with traceable evidence.
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="policy.workflow.direct.commands.command.contract" slot="commands" mutability="replaceable" -->
+
 ## Command contract
 
 ```bash
@@ -28,6 +36,9 @@ agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."
 agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --result "..." --commit <git-rev>
 ```
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="policy.workflow.direct.workflow.error.recovery" slot="workflow" mutability="replaceable" -->
+
 ## ERROR RECOVERY
 
 If any step fails:
@@ -40,6 +51,9 @@ If any step fails:
 4. Request re-approval before scope/risk changes.
 5. If failure is external/process-related and should become reusable advice, record a structured `Observation` / `Impact` / `Resolution` block in `Findings` and mark it with `Fixability: external` (or `IncidentExternal: true`); plain prose in `Findings` stays task-local and does not update `.agentplane/policy/incidents.md`.
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="policy.workflow.direct.hard_constraint.constraints" slot="hard_constraint" mutability="append_only" -->
+
 ## Constraints
 
 - MUST NOT perform mutating actions before explicit user approval.
@@ -51,3 +65,4 @@ If any step fails:
 - MUST stop and request re-approval on material drift.
 - Do not use worktrees in direct mode.
 - Do not perform `branch_pr`-only operations.
+<!-- /ap:fragment -->

package/assets/policy/workflow.md

@@ -1,3 +1,5 @@
+<!-- ap:fragment id="policy.workflow.workflow.workflow.policy.index" slot="workflow" mutability="replaceable" -->
+
 # Workflow Policy Index
 
 This document is an index for workflow procedures.
@@ -7,3 +9,4 @@ Use `AGENTS.md` load rules to decide which module to read.
 - Branch PR workflow: `.agentplane/policy/workflow.branch_pr.md`
 - Release workflow: `.agentplane/policy/workflow.release.md`
 - Upgrade workflow: `.agentplane/policy/workflow.upgrade.md`
+<!-- /ap:fragment -->

package/assets/policy/workflow.release.md

@@ -1,7 +1,12 @@
+<!-- ap:fragment id="policy.workflow.release.workflow.workflow.release" slot="workflow" mutability="replaceable" -->
+
 # Workflow: release
 
 Use this module when task touches release/version/publish flows.
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="policy.workflow.release.workflow.required.sequence" slot="workflow" mutability="replaceable" -->
+
 ## Required sequence
 
 1. CHECKPOINT A: confirm clean tracked tree and approved scope.
@@ -11,6 +16,9 @@ Use this module when task touches release/version/publish flows.
 5. CHECKPOINT C: choose the workflow-specific publication route after all gates pass.
 6. Record release evidence (commands, outputs, resulting version/tag).
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="policy.workflow.release.commands.command.contract" slot="commands" mutability="replaceable" -->
+
 ## Command contract
 
 ```bash
@@ -24,6 +32,9 @@ agentplane verify <task-id> --ok|--rework --by <ROLE> --note "Release checks: ..
 agentplane finish <task-id> --author <ROLE> --body "Verified: release" --result "Release <v> published" --commit <git-rev> --close-commit
 ```
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="policy.workflow.release.hard_constraint.constraints" slot="hard_constraint" mutability="append_only" -->
+
 ## Constraints
 
 - MUST NOT perform irreversible release actions before explicit approval.
@@ -31,4 +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 -->

package/assets/policy/workflow.upgrade.md

@@ -1,7 +1,12 @@
+<!-- ap:fragment id="policy.workflow.upgrade.workflow.workflow.upgrade" slot="workflow" mutability="replaceable" -->
+
 # Workflow: upgrade
 
 Use this module when task runs `agentplane upgrade` or touches `.agentplane/.upgrade/**`.
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="policy.workflow.upgrade.workflow.required.sequence" slot="workflow" mutability="replaceable" -->
+
 ## Required sequence
 
 1. Run upgrade command and capture run directory.
@@ -14,7 +19,11 @@ Use this module when task runs `agentplane upgrade` or touches `.agentplane/.upg
 6. Verify policy/agent consistency and routing checks.
 7. Record run path and reviewed files in task notes.
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="policy.workflow.upgrade.check.minimum.verification" slot="check" mutability="append_only" -->
+
 ## Minimum verification
 
 - `node .agentplane/policy/check-routing.mjs`
 - `agentplane agents`
+<!-- /ap:fragment -->

package/dist/.build-manifest.json

@@ -2,7 +2,7 @@
   "schema_version": 1,
   "manifest_kind": "package",
   "package_name": "agentplane",
-  "package_version": "0.3.29",
-  "git_head": "a4aa33ce12fedb462fdbb69d48a639101382ddd0",
-  "watched_runtime_snapshot_hash": "b88790734dcf856620028536210b6391ea348d8d0dfafde7ec9b371233a9cf9b"
+  "package_version": "0.4.1",
+  "git_head": "62153d7eedd49b356e67aee92d713ad9b7b8485c",
+  "watched_runtime_snapshot_hash": "2a5f3b1f84ea38e8747a50e72b94b46fe874f0fa72eaa0a4babba30323524007"
 }