chore(release): bump to v0.21.0

Two-axis release: v0.19.2 retro action items + two pk-doctor
silent-zero correctness fixes that surfaced when the owner ran
/pk-doctor in an aibox-derived project and got falsely-clean
results.

Retro batch:
- WildLake   fix: mcp[cli] + jsonschema in pk_retro PEP 723 header
- ToughAnt   docs: Sub-agent delegation section in AGENTS.md
- SwiftLynx  feat: compliance-ack TTL auto-renew + dynamic version
- BraveBird  feat: reload_schemas MCP tool on 4 schema-active servers
- MightyFjord fix: pk-doctor --fix=schema_filename for CalmAnt-class
- KeenFern   feat: 20 missing specialist+expert seed bindings
- #11        fix: product/retrospective → product/sprint-retrospective

pk-doctor portability fixes (added late per DEC-StoutCliff):
- HappyReef  fix: schema_filename schemas-dir fallback (silent zero)
- DeepMoss   fix: migrations layout fallback (silent zero)

Cancelled / superseded:
- SharpBrook → BraveBird + RapidSwan (deferred to v0.22+)
- SnappyBird → MightyFjord (narrow only; general path not built)

aibox.lock processkit pin v0.20.0 → v0.21.0; CHANGELOG finalised
(Added / Changed / Fixed / Deferred); MCP-config manifest
regenerated (aggregate unchanged at 92d6eedc...);
src/PROVENANCE.toml stamped for v0.21.0; pk-doctor + drift green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: claude

CHANGELOG.md

@@ -5,6 +5,137 @@ Versions follow [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [v0.21.0] — 2026-04-25
+
+Five fixes spanning the v0.19.2 retro action items and two
+correctness bugs in pk-doctor that surfaced when the owner ran
+`/pk-doctor` inside an aibox-derived project and got a falsely-clean
+report.  Both pk-doctor bugs were silent-zero failures: the checks
+silently no-op'd in derived projects and hid every entity-hygiene
+problem they were supposed to catch.
+
+The two heavier retro items (SharpBrook MCP schema hot-reload,
+SnappyBird append-only LogEntry repair) were worked through design
+discussions (DISC-DaringBird, DISC-WiseLily) and split or narrowed
+per DEC-QuickPine and DEC-BrightHawk.
+
+### Added
+
+- **feat(_lib + 4 servers): `reload_schemas` MCP tool.**  Each of
+  the schema-active servers (workitem-management, decision-record,
+  event-log, artifact-management) gains a thin tool that calls a
+  shared helper in `_lib/processkit/schema.py::reload_caches()`,
+  clearing the in-process `load_schema` and
+  `state_machine.load` `lru_cache`es so a disk-level schema or
+  state-machine edit becomes visible without a server restart.
+  Returns `{ok, cleared: {schemas, state_machines}}`.  PEP 723
+  dep-header edits are NOT addressed (the `uv`-resolved venv is
+  pinned at process start — tracked separately by
+  `BACK-RapidSwan` for v0.22.0+).  Closes
+  `BACK-20260424_0128-BraveBird-reload-schemas-mcp-tool` per
+  `DEC-20260424_0127-QuickPine`.
+- **feat(model-recommender): 20 specialist + expert seed bindings.**
+  The v0.19.0 roster declared a 5-level seniority ladder
+  (junior → specialist → expert → senior → principal), but the
+  default-bindings pack seeded only 3 levels.  As a result,
+  `resolve_model(<role>, "specialist"|"expert")` returned
+  `no viable model` across all 10 seeded roles — 20 missing
+  combinations.  KeenFern adds seeds inheriting from the nearest
+  covered neighbour: `specialist` → junior's (model, effort band),
+  `expert` → senior's (model, effort band).  MANIFEST.yaml grew from
+  30 → 50 seeds.  New regression test
+  `test_default_bindings_coverage.py` asserts every seeded role
+  covers all 5 ladder levels and fires loudly on any future gap.
+  Closes `BACK-20260424_0134-KeenFern-fill-model-assignment-seniority`.
+- **docs(AGENTS.md): "Sub-agent delegation" section.**  Codifies
+  the read-only / mutating split for harness `Agent`-tool sub-agents
+  (delegate read-only; keep mutating writes on the main session).
+  Closes `BACK-20260424_0038-ToughAnt-ephemeral-sub-agent-defaults`.
+- **docs(AGENTS.md): "LogEntry repair" Skill-guards entry.**
+  Documents the narrow hand-edit escape hatch for schema-invalid
+  LogEntries and points to `pk-doctor --fix=schema_filename` as
+  the preferred path.  Part of MightyFjord.
+
+### Changed
+
+- **feat(skill-gate): compliance-ack TTL is now an idle timeout.**
+  `_any_valid_marker()` rewrites the matching marker's
+  `acknowledged_at` to `now` on every successful gate check.
+  Sessions actively making compliant writes never expire mid-flow
+  (the v0.19.2 midnight-span pain pattern); idle sessions
+  (> `_ACK_LIFETIME_HOURS`, default 12 h) still must re-acknowledge.
+  Touch failures are non-fatal.  Closes
+  `BACK-20260424_0038-SwiftLynx-compliance-contract-acknowledgement-ttl`.
+
+### Fixed
+
+- **fix(pk-doctor): `schema_filename` schemas-dir fallback (HappyReef).**
+  `schema_filename.py` resolved the schemas dir as
+  `<repo_root>/src/context/schemas/` only — a path that exists
+  exclusively in the processkit dogfood repo.  In every derived
+  project (aibox-installed) schemas live at `<repo_root>/context/
+  schemas/`, so the check silently walked 0 entity files and
+  reported 0 ERROR / 0 WARN regardless of how many malformed
+  entities were on disk.  The new `_resolve_schemas_dir()` tries
+  the dogfood path first, then falls back to `context/schemas/`,
+  and surfaces a single WARN when neither exists.  Verified
+  against an aibox checkout: the check now walks 186 entity files
+  and reports the real findings (filename-date mismatches on
+  `_0000` placeholder filenames, missing-`actor` ERRORs, etc.).
+  Closes `BACK-20260425_1041-HappyReef-pk-doctor-schema-filename`.
+- **fix(pk-doctor): `migrations` layout fallback (DeepMoss).**
+  Companion to HappyReef.  The `migrations` check looked only in
+  `context/migrations/pending/` (processkit dogfood convention).
+  Derived projects (aibox) keep pending migrations at the top
+  level of `context/migrations/` and only move *applied* ones into
+  `applied/`.  The new `_candidate_pending_paths()` probes
+  `pending/` first; if absent, walks `context/migrations/*.md`
+  minus `applied/`, `INDEX.md`, and aibox-CLI upgrade-doc
+  filenames (`<YYYYMMDD>_<HHMM>_<from>-to-<to>.md`).  `_list_pending`
+  also filters by `kind: Migration` so non-Migration markdown
+  alongside migrations is ignored.  Closes
+  `BACK-20260425_1041-DeepMoss-pk-doctor-migrations-detect`.
+- **fix(pk-doctor): `--fix=schema_filename` for the CalmAnt-class
+  pattern (MightyFjord).**  New `run_fix` on
+  `schema_filename.py` patches LogEntries missing the required
+  `actor` field by inserting `actor: system`, validates
+  post-patch, and rolls back on failure.  Behind `--fix=schema_filename
+  --yes`, never default.  Closes
+  `BACK-20260424_0128-MightyFjord-pk-doctor-fix-schema` per
+  `DEC-20260424_0128-BrightHawk`.
+- **fix(skill-gate): remediation text uses on-disk contract version.**
+  `_remediation_msg()` parses the leading `<!-- pk-compliance vN -->`
+  marker rather than hard-coding `v1`.  Part of SwiftLynx.
+- **fix(retrospective): `/pk-retro --auto-workitems` no longer fails
+  with `ModuleNotFoundError: No module named 'mcp'`.**  Added
+  `mcp[cli]>=1.0` and `jsonschema>=4.0` to `pk_retro.py`'s PEP 723
+  header so `uv run --script pk_retro.py` resolves the in-process
+  MCP loader's transitive imports automatically.  Closes
+  `BACK-20260424_0038-WildLake-pk-retro-auto-workitems`.
+- **fix(skills): resolve cross-category `retrospective` skill basename
+  collision.**  `product/retrospective` is renamed to
+  `product/sprint-retrospective`; the processkit-category
+  `retrospective` (release-scope, `/pk-retro`) keeps the bare name.
+  Closes [#11].
+
+### Deferred
+
+- `BACK-20260424_0128-RapidSwan-pk-doctor-server-header` — pk-doctor
+  `server_header_drift` check (PEP 723 dep drift detection,
+  WARN-only).  Targeted v0.22.0+.
+- `BACK-20260424_0037-SharpBrook-mcp-servers-cache-schemas`
+  (cancelled; superseded by BraveBird + RapidSwan per
+  `DEC-20260424_0127-QuickPine`).
+- `BACK-20260424_0038-SnappyBird-data-repair-path-for`
+  (cancelled; replaced by the narrow MightyFjord run_fix per
+  `DEC-20260424_0128-BrightHawk`; general data-fix migration kind
+  not built — revisit only if >2 more recurrences in a calendar
+  quarter).
+
+[#11]: https://github.com/projectious-work/processkit/issues/11
+
+---
+
 ## [v0.20.0] — 2026-04-24
 
 Retro follow-up batch: fixes the three lightest action items from the

aibox.lock

@@ -4,7 +4,7 @@ synced_at = "2026-04-19T08:03:58.481219+00:00"
 
 [processkit]
 source = "https://github.com/projectious-work/processkit.git"
-version = "v0.20.0"
+version = "v0.21.0"
 src_path = "src"
 release_asset_sha256 = "3c6bf672e3a4ac2bf8c0b807c2e5fe948ff27906b6a0aa0ff73d36a1b2f7c98c"
 installed_at = "2026-04-19T08:03:58.481219+00:00"

context/.processkit-mcp-manifest.json

@@ -1,6 +1,6 @@
 {
   "aggregate_sha256": "92d6eedc1755a7ce9d69a1013393e36cc616e411d1daa4c9c5484cefe4536651",
-  "generated_at": "2026-04-24T01:12:08Z",
+  "generated_at": "2026-04-25T10:57:34Z",
   "per_skill": [
     {
       "path": "context/skills/processkit/actor-profile/mcp/mcp-config.json",
@@ -75,6 +75,6 @@
       "sha256": "a4ae7e26a980aeebed953f3cc2e761cde6dd8692fb033c81c9e3c8927e8b5898"
     }
   ],
-  "processkit_version": "v0.20.0",
+  "processkit_version": "v0.21.0",
   "version": 1
 }

context/decisions/DEC-20260425_1040-StoutCliff-expand-v0-21-0.md

@@ -0,0 +1,37 @@
+---
+apiVersion: processkit.projectious.work/v1
+kind: DecisionRecord
+metadata:
+  id: DEC-20260425_1040-StoutCliff-expand-v0-21-0
+  created: '2026-04-25T10:40:50+00:00'
+spec:
+  title: 'Expand v0.21.0 scope: add two pk-doctor portability fixes for derived projects
+    (silent-zero schema_filename + migrations layout fallback)'
+  state: accepted
+  decision: 'Add two new fixes to the v0.21.0 release before cutting: (1) `pk-doctor
+    schema_filename` resolves the schemas dir with a fallback chain (`src/context/schemas/`
+    → `context/schemas/`) so it actually validates entities in derived projects instead
+    of silently walking 0 files; (2) `pk-doctor migrations` accepts both layouts (processkit
+    `context/migrations/pending/` AND top-level + `applied/`) so it actually counts
+    pending migrations in derived projects. File two WIs against v0.21.0 to track
+    each.'
+  context: 'Owner ran `/pk-doctor` inside the aibox derived-project container and
+    got 0 ERROR / 0 WARN despite obvious schema and migration issues. Investigation
+    revealed both checks silently no-op on derived projects: schema_filename hard-codes
+    `src/context/schemas/` (which only exists in the processkit dogfood repo), and
+    migrations hard-codes `context/migrations/pending/` (which does not match aibox''s
+    top-level + `applied/` convention). Together these two bugs make pk-doctor falsely
+    reassuring on every derived install — the exact failure mode the user just hit.'
+  rationale: These are silent-correctness bugs, not feature gaps. Shipping v0.21.0
+    without them means every derived-project pk-doctor run is misleading. The fixes
+    are small (path fallback chains in two places) and self-contained, so adding them
+    to the release in flight is a much better trade than waiting for v0.21.1.
+  consequences: v0.21.0 scope grows by two small tasks. Cut is delayed by maybe an
+    hour. After release, derived projects on processkit ≥ v0.21.0 will get faithful
+    pk-doctor results out of the box. Existing derived projects on v0.18.1–v0.20.0
+    keep getting silent zeros until they bump.
+  deciders:
+  - TEAMMEMBER-thrifty-otter
+  - TEAMMEMBER-cora
+  decided_at: '2026-04-25T10:40:50+00:00'
+---

context/logs/2026/04/LOG-20260425_1000-StoutRobin-workitem-transitioned.md

@@ -0,0 +1,15 @@
+---
+apiVersion: processkit.projectious.work/v1
+kind: LogEntry
+metadata:
+  id: LOG-20260425_1000-StoutRobin-workitem-transitioned
+  created: '2026-04-25T10:00:39+00:00'
+spec:
+  event_type: workitem.transitioned
+  timestamp: '2026-04-25T10:00:39+00:00'
+  summary: Transitioned WorkItem 'BACK-20260424_0134-KeenFern-fill-model-assignment-seniority'
+    from 'review' to 'done'
+  subject: BACK-20260424_0134-KeenFern-fill-model-assignment-seniority
+  subject_kind: WorkItem
+  actor: BACK-20260424_0134-KeenFern-fill-model-assignment-seniority
+---

context/logs/2026/04/LOG-20260425_1040-DaringSwan-decision-created.md

@@ -0,0 +1,16 @@
+---
+apiVersion: processkit.projectious.work/v1
+kind: LogEntry
+metadata:
+  id: LOG-20260425_1040-DaringSwan-decision-created
+  created: '2026-04-25T10:40:50+00:00'
+spec:
+  event_type: decision.created
+  timestamp: '2026-04-25T10:40:50+00:00'
+  summary: 'Created DecisionRecord ''DEC-20260425_1040-StoutCliff-expand-v0-21-0'':
+    ''Expand v0.21.0 scope: add two pk-doctor portability fixes for derived projects
+    (silent-zero schema_filename + migrations layout fallback)'''
+  subject: DEC-20260425_1040-StoutCliff-expand-v0-21-0
+  subject_kind: DecisionRecord
+  actor: DEC-20260425_1040-StoutCliff-expand-v0-21-0
+---

context/logs/2026/04/LOG-20260425_1041-HappyTiger-workitem-created.md

@@ -0,0 +1,15 @@
+---
+apiVersion: processkit.projectious.work/v1
+kind: LogEntry
+metadata:
+  id: LOG-20260425_1041-HappyTiger-workitem-created
+  created: '2026-04-25T10:41:11+00:00'
+spec:
+  event_type: workitem.created
+  timestamp: '2026-04-25T10:41:11+00:00'
+  summary: 'Created WorkItem ''BACK-20260425_1041-DeepMoss-pk-doctor-migrations-detect'':
+    ''pk-doctor migrations: detect both layouts (pending/ subdir AND top-level + applied/)'''
+  subject: BACK-20260425_1041-DeepMoss-pk-doctor-migrations-detect
+  subject_kind: WorkItem
+  actor: BACK-20260425_1041-DeepMoss-pk-doctor-migrations-detect
+---

context/logs/2026/04/LOG-20260425_1041-QuickFox-workitem-created.md

@@ -0,0 +1,16 @@
+---
+apiVersion: processkit.projectious.work/v1
+kind: LogEntry
+metadata:
+  id: LOG-20260425_1041-QuickFox-workitem-created
+  created: '2026-04-25T10:41:01+00:00'
+spec:
+  event_type: workitem.created
+  timestamp: '2026-04-25T10:41:01+00:00'
+  summary: 'Created WorkItem ''BACK-20260425_1041-HappyReef-pk-doctor-schema-filename'':
+    ''pk-doctor schema_filename: derived-project schemas-dir fallback (fix silent-zero
+    walk)'''
+  subject: BACK-20260425_1041-HappyReef-pk-doctor-schema-filename
+  subject_kind: WorkItem
+  actor: BACK-20260425_1041-HappyReef-pk-doctor-schema-filename
+---

context/logs/2026/04/LOG-20260425_1041-SureTiger-workitem-transitioned.md

@@ -0,0 +1,15 @@
+---
+apiVersion: processkit.projectious.work/v1
+kind: LogEntry
+metadata:
+  id: LOG-20260425_1041-SureTiger-workitem-transitioned
+  created: '2026-04-25T10:41:15+00:00'
+spec:
+  event_type: workitem.transitioned
+  timestamp: '2026-04-25T10:41:15+00:00'
+  summary: Transitioned WorkItem 'BACK-20260425_1041-HappyReef-pk-doctor-schema-filename'
+    from 'backlog' to 'in-progress'
+  subject: BACK-20260425_1041-HappyReef-pk-doctor-schema-filename
+  subject_kind: WorkItem
+  actor: BACK-20260425_1041-HappyReef-pk-doctor-schema-filename
+---

context/logs/2026/04/LOG-20260425_1042-CalmHawk-workitem-transitioned.md

@@ -0,0 +1,15 @@
+---
+apiVersion: processkit.projectious.work/v1
+kind: LogEntry
+metadata:
+  id: LOG-20260425_1042-CalmHawk-workitem-transitioned
+  created: '2026-04-25T10:42:49+00:00'
+spec:
+  event_type: workitem.transitioned
+  timestamp: '2026-04-25T10:42:49+00:00'
+  summary: Transitioned WorkItem 'BACK-20260425_1041-DeepMoss-pk-doctor-migrations-detect'
+    from 'backlog' to 'in-progress'
+  subject: BACK-20260425_1041-DeepMoss-pk-doctor-migrations-detect
+  subject_kind: WorkItem
+  actor: BACK-20260425_1041-DeepMoss-pk-doctor-migrations-detect
+---