@jaybeeuu/agent-cortex 2.0.0 → 2.2.0

package/skills/workflow/run-pipeline-stage/playbooks/code.md

@@ -16,4 +16,15 @@
 - Set `OUTCOME: BLOCKED` if tests fail or requirements cannot be met.
 - If blocked, list issues under `BLOCKING_ISSUES`.
 - `FILES_CHANGED` lists all modified source/test files.
+
+## Remediation and close
+
+- You own this leaf bead: append notes, write the progress log, and `bd close <id> --reason=...`
+  on both outcomes (see `prompts/stage-runner.md`).
+- `OUTCOME: SUCCESS` — create nothing; the orchestrator routes to `verify`.
+- `OUTCOME: BLOCKED` — count the parent's existing `stage:fix` children against
+  `maxFixRounds` in `skills/planning/create-task/pipeline.json`. Under cap, create a
+  `stage:fix` chore **plus a fresh `stage:code` chore** blocked on it (`bd dep add <fresh>
+  <fix> --type blocks`), and re-block later stages behind the fresh bead. At cap, block the
+  parent and create nothing.
 - Report `COMMIT`, `PUSHED`, and `PR` (`PR: none` outside the document stage).

package/skills/workflow/run-pipeline-stage/playbooks/document.md

@@ -18,4 +18,16 @@
 - Set `OUTCOME: BLOCKED` if unable to update or content guidance is unclear.
 - If blocked, list issues under `BLOCKING_ISSUES`.
 - `FILES_CHANGED` lists docs touched, or `none` if no doc change is needed.
+
+## Remediation and close
+
+- You own this leaf bead: append notes, write the progress log, and `bd close <id> --reason=...`
+  on both outcomes (see `prompts/stage-runner.md`).
+- `OUTCOME: SUCCESS` — create nothing; the orchestrator opens the feature PR and updates the
+  HITL gate bead.
+- `OUTCOME: BLOCKED` — count the parent's existing `stage:fix` children against
+  `maxFixRounds` in `skills/planning/create-task/pipeline.json`. Under cap, create a
+  `stage:fix` chore **plus a fresh `stage:document` chore** blocked on it
+  (`bd dep add <fresh> <fix> --type blocks`) so documentation is retried after the fix. At cap,
+  block the parent and create nothing.
 - Report `COMMIT`, `PUSHED`, and the feature `PR` URL.

package/skills/workflow/run-pipeline-stage/playbooks/fix.md

@@ -16,4 +16,16 @@
 - Set `OUTCOME: BLOCKED` if unable to apply changes or guidance is unclear.
 - If blocked, list issues under `BLOCKING_ISSUES`.
 - `FILES_CHANGED` lists files updated to address requested changes.
+
+## Remediation and close
+
+- You own this leaf bead: append notes, write the progress log, and `bd close <id> --reason=...`
+  on both outcomes (see `prompts/stage-runner.md`).
+- `OUTCOME: SUCCESS` — create nothing; closing this bead unblocks the fresh stage chore that
+  was wired behind it.
+- `OUTCOME: BLOCKED` — count the parent's existing `stage:fix` children against
+  `maxFixRounds` in `skills/planning/create-task/pipeline.json`. Under cap, create another
+  `stage:fix` chore carrying what remains **plus a fresh `stage:fix` chore** blocked on it
+  (`bd dep add <fresh> <fix> --type blocks`) and leave the downstream re-run chore blocked on
+  the fresh fix. At cap, block the parent and create nothing.
 - Report `COMMIT`, `PUSHED`, and `PR` (`PR: none`).

package/skills/workflow/run-pipeline-stage/playbooks/review.md

@@ -17,3 +17,14 @@
 - Set `OUTCOME: BLOCKED` if changes are requested.
 - If blocked, enumerate required changes under `BLOCKING_ISSUES`.
 - `FILES_CHANGED` should be `none`.
+
+## Remediation and close
+
+- You own this leaf bead: append notes, write the progress log, and `bd close <id> --reason=...`
+  on both outcomes (see `prompts/stage-runner.md`).
+- `OUTCOME: SUCCESS` — create nothing; the orchestrator routes to `document`.
+- `OUTCOME: BLOCKED` — count the parent's existing `stage:fix` children against
+  `maxFixRounds` in `skills/planning/create-task/pipeline.json`. Under cap, create a
+  `stage:fix` chore carrying the full `BLOCKING_ISSUES` list **plus a fresh `stage:review`
+  chore** blocked on it (`bd dep add <fresh> <fix> --type blocks`), and re-block `document`
+  behind the fresh bead. At cap, block the parent and create nothing.

package/skills/workflow/run-pipeline-stage/playbooks/verify.md

@@ -12,3 +12,16 @@
 - Set `OUTCOME: BLOCKED` when any command fails.
 - If blocked, summarize failures under `BLOCKING_ISSUES`.
 - `FILES_CHANGED` should be `none`.
+
+## Remediation and close
+
+- You own this leaf bead: append notes, write the progress log, and `bd close <id> --reason=...`
+  on both outcomes (see `prompts/stage-runner.md`). This is the stage that most often fails —
+  closing it is not a failure of the pipeline.
+- `OUTCOME: SUCCESS` — create nothing; the orchestrator routes to `review`.
+- `OUTCOME: BLOCKED` — count the parent's existing `stage:fix` children against
+  `maxFixRounds` in `skills/planning/create-task/pipeline.json`. Under cap, create a
+  `stage:fix` chore carrying the failure list **plus a fresh `stage:verify` chore** blocked on
+  it (`bd dep add <fresh> <fix> --type blocks`) — the chore you are closing can never verify
+  the fix — and re-block `review` behind the fresh bead. At cap, block the parent and create
+  nothing.

package/skills/workflow/run-pipeline-stage/prompts/stage-runner.md

@@ -4,6 +4,8 @@ Run `bd prime` if you need project-level context (conventions, tech stack, goals
 ## Stage metadata
 - Stage: `<stage>`
 - Playbook: `skills/workflow/run-pipeline-stage/playbooks/<stage>.md`
+- Leaf execution bead: `<bead-id>` — **you own its lifecycle**. No orchestrator,
+  dispatcher, or parent agent writes to it or closes it.
 
 ## Bead specification
 <bd show <id> output — verbatim>
@@ -24,7 +26,57 @@ bd update <id> --append-notes "[<ISO-timestamp>] [<stage>] <what changed / what'
 
 Use `--append-notes` — plain `--notes` overwrites the trail. Record start, milestones, decisions
 (with rejected options), blocks, and discoveries. One or two lines per entry: a checkpoint trail,
-not a transcript. The REPORT below remains the authoritative stage outcome.
+not a transcript.
+
+## Leaf bead lifecycle (yours to close)
+
+1. **Chain before close.** Build remediation children (below) *before* you close the bead, so
+   the parent never shows a later stage as ready while remediation is outstanding.
+2. **Close on both outcomes** — success and failure alike:
+   ```bash
+   bd close <bead-id> --reason="<SUCCESS|BLOCKED>: <one-line outcome>"
+   ```
+   The outcome lives in the close reason, the milestone notes, and the REPORT. A closed bead
+   with a `BLOCKED` reason is a completed stage, not abandoned work.
+3. **Do not create the next stage on success.** Routing forward is the orchestrator's job.
+
+## Remediation (only when your outcome is BLOCKED)
+
+A fresh instance of this stage is required: the bead you are closing cannot re-run itself.
+
+1. **Cap check.** Read `maxFixRounds` from `skills/planning/create-task/pipeline.json` and count
+   the parent's existing fix rounds (closed ones count):
+   ```bash
+   fix_rounds=$(bd children <parent-id> --json | grep -c '"stage:fix"')
+   ```
+2. **At cap** (`fix_rounds >= maxFixRounds`): create **nothing**. Block the parent and record why:
+   ```bash
+   bd update <parent-id> --status blocked \
+     --append-notes "[<ISO-timestamp>] max fix rounds reached (<fix_rounds>/<maxFixRounds>) after <stage> BLOCKED"
+   ```
+   Then close your own bead and report `OUTCOME: BLOCKED`.
+3. **Under cap**: create the fix chore plus the fresh stage, then wire the ordering.
+   `--parent` sets the parent-child dep and inherits the parent's labels.
+   ```bash
+   fix_id=$(bd create "[<parent-id>] Fix (round <fix_rounds + 1>)" \
+     --type chore --priority <parent-priority> --parent <parent-id> \
+     --labels stage:fix \
+     --description "Requirements: see <parent-id> (bd show <parent-id>).
+
+<BLOCKING_ISSUES from your run>" --silent)
+   fresh_id=$(bd create "[<parent-id>] <Stage title> (re-run <fix_rounds + 1>)" \
+     --type chore --priority <parent-priority> --parent <parent-id> \
+     --labels stage:<stage> \
+     --description "<this stage's description from pipeline.json>" --silent)
+   bd dep add $fresh_id $fix_id --type blocks        # fresh stage waits for the fix
+   ```
+4. **Re-block the later stages.** Any not-yet-run stage chore of the same parent is already
+   unblocked by your bead closing. Wire each one behind the fresh stage:
+   ```bash
+   bd dep add <downstream-chore-id> $fresh_id --type blocks
+   ```
+   Skip stages that already ran (closed) and the HITL PR gate bead.
+5. Do **not** dispatch anything yourself — the new beads flow through `bd ready`.
 
 ## Deliver before reporting
 
@@ -41,3 +93,23 @@ dirty worktree counts as a failed stage whatever the outcome line claims.
 1. Read and follow the playbook file listed above.
 2. Treat the bead as the source-of-truth specification (not a prompt script).
 3. Keep output factual and stage-scoped.
+
+## Report
+
+End your response with a `---REPORT---` block in exactly this format:
+
+```
+---REPORT---
+BEAD_ID: <id>
+STAGE_COMPLETED: <code|verify|review|document|fix>
+SUMMARY: <2-3 sentence summary of what was done>
+FILES_CHANGED: <comma-separated list, or "none">
+COMMIT: <sha of the stage commit, or "none">
+PUSHED: <yes|no>
+PR: <feature PR url, or "none">
+OUTCOME: <SUCCESS|BLOCKED>
+BLOCKING_ISSUES:                              <- only if OUTCOME is BLOCKED
+- <specific blocking issue>
+```
+
+Report facts only — do not suggest or predict the next step.

package/token-map.README.md

@@ -62,10 +62,15 @@ rather than inventing a dotted form:
   actually runs from. A literal home path in substituted files would break under
   cache-copy, so the installer passes the env form through verbatim.
 - **`agents`** — the `agent-cortex:` name-prefix convention per harness (claude strips the
-  prefix during conversion) and the deferred-agent exception (claude's `ralph` is authored
-  natively, never generated). Agent names themselves do not get per-row mappings because
-  the prefix rule covers all of them; the deferred list captures the only structural
-  difference.
+  prefix during conversion). Agent names themselves do not get per-row mappings because
+  the prefix rule covers all of them — every agent is composed from `agents/<name>/` for
+  every harness, so there is no structural exception to record.
+- **`wake`** — the completion mechanism per harness (`pi`: blocking-wait,
+  `claude`: event-driven). Informational only — no installer substitutes a
+  token from it. It records the fact that the shared ralph body deliberately does not
+  state, so `{{SECTION:wake}}` → `agents/ralph/<harness>/wake.md` is the single place
+  harness specifics live, and the mechanism stays checkable instead of being inferred from
+  prose. `agents/README.md` carries the same table for humans.
 - **Deliberately not mapped:** hook patterns, MCP servers, and tool descriptions. Those
   differ *structurally* per harness (different hook event names, different config files),
   not by a single substitutable token; each installer already hardcodes its own shape. The

package/token-map.json

@@ -46,12 +46,20 @@
       "claude": "",
       "pi": "agent-cortex:"
     },
-    "deferred": {
-      "ralph": ["claude"]
-    },
     "sources": {
       "pi": "agents/<name>/ composable dirs (canonical) — composed at runtime by the agent-modes extension",
-      "claude": "agents/<name>/ composable dirs (canonical) — composed by bin/installers/claude.mjs (install-time generator, the only generator — the generated claude/ plugin subtree is not committed), plus agents-native/*.md for deferred agents"
+      "claude": "agents/<name>/ composable dirs (canonical) — composed by bin/installers/claude.mjs (install-time generator, the only generator — the generated claude/ plugin subtree is not committed)"
+    }
+  },
+  "wake": {
+    "description": "How each harness tells ralph that a background worker finished. `{{SECTION:wake}}` in agents/ralph/agent.md resolves to agents/ralph/<harness>/wake.md; this table is the machine-readable form of the same fact, so the mechanism is recorded rather than inferred from prose (see the wake table in agents/README.md).",
+    "mechanism": {
+      "pi": "blocking-wait",
+      "claude": "event-driven"
+    },
+    "notes": {
+      "pi": "Blocking wait: wait_for_agents returns as soon as one worker finishes, carrying its result inline. No timer to start, nothing to kill — there is no poll loop.",
+      "claude": "Event-driven: the harness re-invokes ralph when a worker completes and delivers the result inline. No poll timer, no sleep, no log flush."
     }
   },
   "notes": {
@@ -70,8 +78,7 @@
       "claude": "plugin_root stays ${CLAUDE_PLUGIN_ROOT} (env var) for the materialised plugin — never a literal ~/.agent-cortex/claude. Claude Code copies marketplace-installed plugins (including local directory sources like ~/.agent-cortex/claude) into its own cache and expands the env var per context, so a literal home path in substituted files would break under cache-copy; the installer passes the env form through verbatim."
     },
     "agents": {
-      "prefix": "Claude strips the agent-cortex: name prefix during conversion (NAME_PREFIX in bin/installers/claude.mjs): pi agents are agent-cortex:<slug>, claude agents are <slug>.",
-      "deferred": "ralph has no generated claude counterpart — it is authored natively as agents-native/ralph.md (its event-driven orchestration cannot be produced by section composition from the polling pi source)."
+      "prefix": "Claude strips the agent-cortex: name prefix during conversion (NAME_PREFIX in bin/installers/claude.mjs): pi agents are agent-cortex:<slug>, claude agents are <slug>."
     }
   },
   "contract": {

package/.agents/skills/style-versioning/SKILL.md

@@ -1,172 +0,0 @@
----
-name: style-versioning
-description: Automated release workflow using changesets. Use when completing work that needs a release, asking "how do I version this?", or when any change needs to be shipped to npm.
----
-
-# style-versioning
-
-This repo uses **changesets** for fully automated versioning and publishing. No manual version bumps, no manual releases.
-
-## When to use
-
-Trigger this skill when:
-- Completing work that needs a release
-- Asking "how do I version this change?"
-- Creating a PR that changes shipped behaviour
-
-## Creating a changeset (agent instructions)
-
-**Do NOT run `pnpm changeset`** — it is interactive and will waste tokens on prompts and ANSI codes. Instead, write the changeset file directly.
-
-### File format
-
-A changeset is a markdown file in `.changeset/` with YAML frontmatter:
-
-```markdown
----
-"@jaybeeuu/agent-cortex": <bump>
----
-
-<Short description of the change>
-```
-
-Where `<bump>` is one of: `patch`, `minor`, or `major`.
-
-### How to create one
-
-1. Choose a descriptive kebab-case filename (e.g., `fix-status-bug.md`, `add-webhook-skill.md`)
-2. Choose the bump type:
-   - `patch` — bug fix, clarification, no behaviour change
-   - `minor` — new skill, agent, feature, or meaningful behaviour change
-   - `major` — breaking change (removed skill, renamed agent, incompatible workflow)
-3. Write the file directly using the `write` tool:
-
-```
-write(".changeset/fix-status-bug.md", `---
-"@jaybeeuu/agent-cortex": patch
----
-
-Fix status bead showing wrong priority after update
-`)
-```
-
-4. Commit the changeset file along with the code changes
-
-### Rules
-
-- **Every PR adds a changeset.** CI fails otherwise. The only opt-out is the
-  `no-publish` label (see below).
-- The frontmatter package name must match exactly: `"@jaybeeuu/agent-cortex"`
-- The description should be one or two sentences, user-facing (it goes into CHANGELOG.md)
-- One changeset per PR. If a PR has multiple unrelated changes, use multiple changeset files.
-- The filename doesn't matter to changesets — only the frontmatter and description do.
-
-## The PR gate
-
-`changeset-check` runs on every pull request and fails it unless the PR adds a
-`.changeset/*.md` file. **Publishing is the default; `no-publish` is the only
-opt-out** — skipping a release is an explicit, reviewable decision, never an accident.
-
-| Exemption | Applies to |
-|---|---|
-| `changeset-release/*` head branch, or actor `github-actions[bot]` | the changesets bot's Version Packages PR — it consumes changesets and adds none of its own |
-| `no-publish` label | a PR that genuinely ships nothing |
-
-The `no-publish` label must exist in the repository's label settings — a one-off
-human step (`gh label create no-publish`), not something a PR can ship. If the gate
-fails and the PR really ships nothing, ask for the label; do not manufacture a
-changeset to make it green.
-
-## After merge to main
-
-The `release` job in `.github/workflows/ci.yml` handles everything automatically:
-
-1. **Detects new changesets** on main
-2. **Creates a "Version Packages" PR** — the `version` step runs `pnpm version-packages` (`changeset version`), which bumps `package.json` and rewrites `CHANGELOG.md`. That is the whole release surface: every plugin this package ships is materialised at install time with the package version, so there is no generated output to regenerate and no drift gates to satisfy on a version bump
-3. **When "Version Packages" is merged**:
-   - Creates a git tag
-   - Publishes to npm — `pnpm publish-package` packs with `pnpm pack` and publishes with `npm publish --provenance --access public`. Authenticates via npm Trusted Publishing (OIDC): the release job's `id-token` permission lets npm exchange a GitHub OIDC token for a short-lived npm token at publish time, so no `NPM_TOKEN` secret or `.npmrc` auth config is required — only the one-time npm-side Trusted Publishing setup on npmjs.com (package → Access → Trusted Publishing → GitHub repo `jaybeeuu/agent-cortex` + workflow `.github/workflows/ci.yml`)
-   - Creates a GitHub release automatically
-
-`changesets/action` execs the `version`/`publish` inputs without a shell, so each
-must be a single unquoted command token — keep release logic in pnpm scripts
-(`version-packages`, `publish-package`, `publish-noop`), never inline shell strings.
-
-### Approve CI on the Version Packages PR
-
-The version PR arrives `BLOCKED` with an empty check list, and nothing is broken:
-`changesets/action` pushes that branch with `GITHUB_TOKEN`, so GitHub parks the CI
-run the push creates behind **“Approve workflows to run”** (`action_required`, zero
-jobs). A parked run reports no checks, so the five required contexts are
-unsatisfiable until someone approves it. Approve it from the PR's merge box, or:
-
-```bash
-run=$(gh run list --branch changeset-release/main --limit 20 \
-  --json databaseId,conclusion --jq 'map(select(.conclusion=="action_required"))[0].databaseId')
-gh api -X POST "repos/{owner}/{repo}/actions/runs/$run/approve"
-```
-
-An approval is per head commit. Every merge to `main` force-updates the version
-branch and starts a fresh parked run, so approve immediately before merging the
-version PR — not once per release. Do not reach for a PAT or GitHub App token to
-skip this: one click is cheaper than a long-lived credential in repository
-secrets, and the `GITHUB_TOKEN` the job already holds cannot approve its own run.
-
-Which of the two publish scripts runs is decided per push, not hard-coded: labels are
-invisible on a push event, so the job resolves the PR merged for the pushed commit via
-the GitHub API and reads its labels — `publish-noop` when the PR carried `no-publish`,
-`publish-package` otherwise. That needs no new secret or scope; the job already holds
-`GITHUB_TOKEN` and `pull-requests: write`. A direct push with no merged PR resolves to
-no labels and so publishes, which keeps a genuine publish of an already-published
-version failing loudly — there is deliberately no idempotency guard.
-
-### Merge method and commit signatures
-
-Land a Version Packages PR with `gh pr merge <n> --squash`. Agent and human commits here are
-GPG-signed by the environment and verify as `valid`; the `github-actions[bot]` commit is
-`unsigned` because `GITHUB_TOKEN` cannot sign. The commit that lands is signed by GitHub,
-which is why `main`'s history reads `valid`: PR #161's unsigned head `fe7ef84` landed as
-`dd347471b1` with `committer=GitHub`, `verified=true`.
-
-Squash re-signs the landing commit; it does not escape an enforced signature rule. GitHub
-evaluates a pull request by creating a test merge commit and checking the commits it
-introduces — head-branch commits included — so an enforced `required_signatures` rule blocks
-a squash merge too, and the remedy is then a signed commit on the branch, not another merge
-method. `allow_merge_commit` is off and `required_linear_history` is on, so a merge commit is
-not an option — squash or rebase only, and only squash lands a commit GitHub signs.
-
-See `docs/commit-signing.md` for the evidence, the ruleset reads that show only
-repository-level rules applying to `main` (a read that covers organization rules too), and the
-human-only follow-ups, including the merge probe that closes AC1.
-
-### Version lockstep
-
-Two files carry the version, in lockstep automatically:
-
-1. `package.json` → bumped by changesets
-2. `CHANGELOG.md` → generated by changesets
-
-**Never bump versions manually.** Always create a changeset file.
-
-## Common mistakes
-
-- **Running `pnpm changeset`**: Interactive, wastes tokens. Write the file directly.
-- **Bumping versions manually**: Don't touch `"version"` in `package.json`. Create a changeset.
-- **Omitting the changeset**: CI fails the PR. Publishing is the default; the only
-  opt-out is the `no-publish` label, which must already exist in the repo's settings.
-- **Wrong bump type**: `patch` for fixes, `minor` for additions, `major` for breakage. When in doubt, ask the user.
-- **Wrong package name in frontmatter**: Must be `"@jaybeeuu/agent-cortex"` exactly.
-- **Merging a Version Packages PR with anything but squash**: the bot's commit is unsigned,
-  and squash is the path this repo has landed on (a rebase merge adds the head-branch commit
-  without signature verification).
-  Squash does not, however, bypass an enforced signature rule — if one is confirmed, the
-  branch needs a signed commit. See `docs/commit-signing.md`.
-
-## What changed from the old workflow
-
-| Before (manual) | After (changesets) |
-|---|---|
-| Agent bumps versions locally | Agent writes a changeset file |
-| Manual GitHub release creation | Automated by the `release` job in `ci.yml` |
-| `publish.yml` triggered by release | `ci.yml` release job on push to main |
-| Version files synced by hand | changesets bumps `package.json` + `CHANGELOG.md` |

package/.changeset/README.md

@@ -1,8 +0,0 @@
-# Changesets
-
-Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
-with multi-package repos, or single-package repos to help you version and publish your code. You can
-find the full documentation for it [in our repository](https://github.com/changesets/changesets).
-
-We have a quick list of common questions to get you started engaging with this project in
-[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md).

package/.changeset/config.json

@@ -1,11 +0,0 @@
-{
-  "$schema": "https://unpkg.com/@changesets/config@3.1.4/schema.json",
-  "changelog": "@changesets/cli/changelog",
-  "commit": false,
-  "fixed": [],
-  "linked": [],
-  "access": "public",
-  "baseBranch": "main",
-  "updateInternalDependencies": "patch",
-  "ignore": []
-}