@maestria/codex 0.2.1 → 0.2.3

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "maestria",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Maestria methodology for Codex CLI: specialist workflow skills, orchestration, and review contracts",
   "author": {
     "name": "agustinusnathaniel"

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @maestria/codex
 
+## 0.2.3
+
+### Patch Changes
+
+- [#213](https://github.com/agustinusnathaniel/maestria/pull/213) [`b6f3a09`](https://github.com/agustinusnathaniel/maestria/commit/b6f3a09d1be75e6f19e1d3736f71696df44f3c6d) Thanks [@agustinusnathaniel](https://github.com/agustinusnathaniel)! - Bound review and repair to material blockers, preserve narrow approval boundaries, and complete routine implementation delivery autonomously.
+
+## 0.2.2
+
+### Patch Changes
+
+- [#210](https://github.com/agustinusnathaniel/maestria/pull/210) [`88cc573`](https://github.com/agustinusnathaniel/maestria/commit/88cc5738ac2b1d5c381bba58f7208498087b2bfa) Thanks [@agustinusnathaniel](https://github.com/agustinusnathaniel)! - Keep normal engineering sessions autonomous through continuation, scope-frozen bounded repair, and reviewable PR delivery. Incomplete specialist work is recovered or reported as a structured blocker instead of becoming an implicit user checkpoint.
+
 ## 0.2.1
 
 ### Patch Changes

package/README.md

@@ -1,71 +1,47 @@
 # @maestria/codex
 
-`@maestria/codex` is a provisional Codex CLI projection of Maestria's canonical agent methodology. It packages the core directives as Codex skills inside a `.codex-plugin/plugin.json` bundle.
+A provisional Codex CLI package that ships Maestria's agent methodology as namespaced `$maestria:*` skills.
 
-## Status and support boundary
+> This package is part of the Maestria project. See [VISION.md](https://github.com/agustinusnathaniel/maestria/blob/main/VISION.md) for the project vision, motivation, and scope.
 
-This is a `Provisional` / `Projection` spike verified against the locally available `codex 0.145.0` on 2026-08-13. The package demonstrates a generated skills projection; it is not a production support promise and does not claim Codex desktop parity.
+## Status / Support Boundary
 
-Codex skills, plugin loading, subagent workflows, and `AGENTS.md` are runtime capabilities, not Maestria security controls. This package does not make any specialist role read-only, guarantee delegation, or enforce the maker/checker split. Codex's own sandbox, approvals, and hook trust controls remain the host boundary.
+`Provisional` - verified against Codex CLI 0.145.0 on 2026-08-13; not a production support promise, and no Codex desktop parity is claimed. Reverify host marketplace and skills behavior when upgrading Codex.
 
-The projection intentionally ships no hooks, MCP server, model configuration, or `AGENTS.md` writer. Persistent installation is handled by the Maestria CLI, which stages the published npm package into a local Codex marketplace and delegates to Codex's native plugin commands.
-
-## Local package validation
-
-From the repository root:
-
-```bash
-python3 /path/to/plugin-creator/scripts/validate_plugin.py packages/codex
-```
-
-Use the `validate_plugin.py` shipped with the Codex plugin-creator skill in your Codex installation; the path is installation-specific.
-
-When a Codex marketplace is available, install the package through that marketplace and start a fresh session before checking skill discovery. This repository does not create or mutate a marketplace as part of the spike.
-
-For the published package, the supported convenience path is:
+## Installation
 
 ```bash
+# Supported convenience path (requires Codex CLI and npm on PATH)
 npx maestria install codex
+npx maestria status
+npx maestria update codex
+npx maestria uninstall codex
 ```
 
-This requires Codex CLI and npm on `PATH`. The CLI creates a local marketplace under `~/.cache/maestria/`, then runs `codex plugin add maestria@maestria`. Check, update, or remove the installation with `maestria status`, `maestria update codex`, and `maestria uninstall codex`.
-
-Codex CLI does not expose a plugin update command in the supported surface used by this projection. `maestria update codex` refreshes the staged npm package, removes the installed plugin, and adds it again. Exact version pinning is not available through `maestria update codex --version`.
+The CLI installs and updates the plugin through Codex's `plugin add` flow. Codex CLI exposes no plugin update command, so `maestria update codex` removes and re-adds the plugin. Exact version pinning is not available. See [INSTALL.md](https://github.com/agustinusnathaniel/maestria/blob/main/packages/codex/INSTALL.md) for the full checklist and verification.
 
-## Skills
+## What It Provides
 
-The plugin exposes these namespaced skills:
+- **14 namespaced skills** - `$maestria:global-rules`, `$maestria:orchestrator`, the 7 specialists (adventurer, architect, builder, diagnose, planner, reviewer, writer), `$maestria:handoff`, `$maestria:iteration-limits`, and the workflow modes `$maestria:fein`, `$maestria:sonar`, `$maestria:blitz`.
+- **Maestria CLI compatibility** - install, status, check, update, and uninstall through the CLI.
 
-| Skill | Purpose |
-| --- | --- |
-| `$maestria:global-rules` | Universal evidence, safety, authorization, review, and branch contracts |
-| `$maestria:orchestrator` | Route work and coordinate specialist skills |
-| `$maestria:adventurer` | Reconnaissance and codebase mapping |
-| `$maestria:architect` | Architecture trade-offs and ADR decisions |
-| `$maestria:builder` | Atomic implementation and verification |
-| `$maestria:diagnose` | Root-cause analysis and regression tracing |
-| `$maestria:planner` | Phased implementation planning |
-| `$maestria:reviewer` | Independent quality review |
-| `$maestria:writer` | Documentation and structured prose |
-| `$maestria:handoff` | Inter-stage handoff contracts |
-| `$maestria:iteration-limits` | Bounded loops and repair termination |
-| `$maestria:fein` | Full pipeline mode |
-| `$maestria:sonar` | Research-only mode |
-| `$maestria:blitz` | Fast capability-aware mode |
+## Support / Platform Notes
 
-The workflow-mode entries are skills rather than Codex slash commands because the pinned projection surface verified for this spike is the plugin `skills/` directory.
+- Workflow modes ship as skills, not slash commands.
+- Read-only specialist boundaries are documented guidance, not tool enforcement; Codex's own sandbox, approvals, and hook trust controls remain the host boundary.
+- Ships no hooks, MCP servers, model configuration, or `AGENTS.md` writer.
+- Support remains provisional until the pinned Codex CLI behavior and the marketplace/plugin install flow are reverified.
 
-## Regenerating generated skills
+## Documentation and Changelog
 
-All skills are generated from `packages/core/agent-directives/`. Edit canonical sources only, then regenerate and check every projection:
+- [User-facing documentation](https://maestria.sznm.dev/codex/) on the docs site
+- [Installation checklist](https://github.com/agustinusnathaniel/maestria/blob/main/packages/codex/INSTALL.md)
+- [Changelog](https://github.com/agustinusnathaniel/maestria/blob/main/packages/codex/CHANGELOG.md)
 
-```bash
-scripts/sync-all
-scripts/check-sync
-```
+## Contributing
 
-Do not hand-edit the generated `skills/` directory.
+See the [contributing guide](https://github.com/agustinusnathaniel/maestria/blob/main/CONTRIBUTING.md) for repository conventions.
 
-## Evidence baseline
+## License
 
-The pinned capability and trust findings are recorded in [`docs/runtime-support-matrix.md`](../../docs/runtime-support-matrix.md) and bounded by [`ADR-CORE-014`](../../docs/adr/core/ADR-CORE-014-runtime-support-and-adapter-policy.md). The exact release source used for the spike is OpenAI Codex [`rust-v0.145.0`](https://github.com/openai/codex/releases/tag/rust-v0.145.0).
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maestria/codex",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "private": false,
   "description": "Provisional Maestria skills projection for Codex CLI",
   "keywords": [

package/skills/global-rules/SKILL.md

@@ -35,7 +35,15 @@ This is the cross-platform behavior contract. It defines outcomes, evidence, saf
 - Compare progress with the outcome and acceptance evidence, not activity or process completion.
 - Keep file, package, and runtime scope explicit. Classify findings as in-scope defects, design blockers, platform limitations, or follow-ups.
 - Adjacent findings do not expand the current task automatically. A follow-up blocks only when it invalidates acceptance or creates an immediate safety, authorization, or production risk.
-- Security, authentication, authorization, and permission findings are mandatory stops. Route design-level issues to `$maestria:architect` and obtain the applicable authorization before proceeding.
+- Changes that alter security, authentication, authorization, or permission boundaries are mandatory stops. Ordinary in-scope security defects may be repaired autonomously; route design-level or boundary changes to `$maestria:architect` and obtain the applicable authorization before proceeding.
+
+## Session Continuation and Delivery
+
+- **!!! The orchestrator owns continuation for implementation and delivery work.** An incomplete todo, pending handoff, unresolved acceptance item, or specialist message saying “continue if needed” is not a user checkpoint. Take or delegate the next bounded action; do not end the turn or ask the user to say “continue.” Research-only, planning-only, explicitly read-only, and host-blocked work terminates at its requested artifact or exact blocker.
+- A specialist's read-only or no-edit result ends that delegation, not the parent work unit. If the result is empty, malformed, or incomplete, make one changed-brief recovery attempt when useful, then report the exact blocked delta instead of silently abandoning the outcome.
+- Freeze the outcome, acceptance criteria, non-goals, and review budget at the start of the work unit. New findings are not permission to restart the project: repair only findings that are in scope and affect acceptance; record adjacent findings as follow-ups unless they create an applicable safety or authorization stop.
+- Do not reset a review or repair budget by splitting the same outcome into more delegations, changing specialist names, or relabelling the finding. A new scope requires a new outcome and acceptance criteria.
+- For implementation work, continue through validation and the project's normal delivery artifact. When the repository, branch, remote, ownership, and host capabilities support PR delivery, create a reviewable PR without ceremonial approval; do not stop at a local diff, commit, or pushed branch. Research-only, planning-only, explicitly read-only, and host-blocked work terminates at its requested artifact or exact blocker. Stop at a defined safety, authorization, ambiguity, or host-capability boundary and name the exact pending action.
 
 ## Delegation and Context
 
@@ -53,24 +61,26 @@ Supported specialists are `adventurer`, `architect`, `builder`, `diagnose`, `pla
 - **!!! Maker/checker split:** the implementer must not approve its own work.
 - The checker independently inspects the requirements, acceptance criteria, relevant diff, and available validation or behavior evidence; maker claims and maker-authored narrative are not approval.
 - Review against acceptance, correctness, safety, and the diff. Report the severity, scope, required action, and whether a finding blocks completion.
-- In-scope defects may be repaired autonomously. Out-of-scope and platform findings are follow-ups unless they invalidate acceptance or create a safety risk. Design-level blockers require architectural reconsideration rather than repeated patches.
+- The checker labels `[fix]` only for a concrete blocker: a security-boundary, acceptance, correctness/regression, or material in-scope design/maintainability failure. Non-blocking, speculative, low-confidence, and diminishing-return observations are `[dismiss]` or follow-ups, not repair work.
+- In-scope blockers may be repaired autonomously. Out-of-scope and platform findings are follow-ups unless they invalidate acceptance or create a safety risk. Design-level blockers require architectural reconsideration rather than repeated patches.
 - Completion requires observable evidence for the acceptance criteria. Never claim an unverified result.
 
 ## Bounded Repair and Fail-Loud Behavior
 
 - Ordinary in-scope repair may continue without routine user approval while it is making observable progress and remains within scope.
-- Review is a convergence gate, not an invitation to polish indefinitely. Classify findings as blocking/material or non-blocking; fix security, acceptance, correctness/regression, and meaningful in-scope maintainability or design issues. Minor preferences and suggestions are follow-ups.
-- Default to one independent review and one repair/re-review pass. Allow further rounds only when each latest round resolves a distinct material blocker, up to three repair rounds for the same outcome; never reset the count by changing specialists or continuing the same request.
+- Review is a convergence gate, not an invitation to polish indefinitely. Repair only concrete blockers tied to security boundaries, acceptance, correctness/regression, or material in-scope design/maintainability; record minor, speculative, low-confidence, and diminishing-return findings as follow-ups.
+- Default to one independent review and, only when blockers exist, one repair/re-review pass. Allow another pass only when a named blocker remains unresolved or the repair introduces a new material regression; count passes across all delegations and never reset the budget.
 - Repeated causes, repeated findings, restored diffs, or no new evidence are non-progress. Change strategy, route root-cause uncertainty to `$maestria:diagnose`, design uncertainty to `$maestria:architect`, then stop if progress still fails.
 - Do not loop silently. Report: `Tried X, Y, Z. Blocked by [cause]. Need [input] to proceed.` Preserve the last diff and finding provenance.
 
 ## Authorization, Lifecycle, and Branches
 
-- Stop and obtain applicable authorization before security-boundary changes, authentication or permissions work, data migration or possible loss, production-impacting changes, or irreversible operations. Ordinary ambiguity is not an authorization checkpoint.
-- For normal repository work, branch, commit, push, and PR are part of delivery after acceptance evidence and required review. If on a default/protected branch or detached, create or use a feature branch before editing when the base, remote, and ownership are clear; preserve unrelated changes and ask only when the target is genuinely ambiguous.
+- Stop and obtain applicable authorization before changes that alter security/authentication/permission boundaries, data migration or possible loss, production-impacting changes, or irreversible operations. Ordinary in-scope repair and ambiguity are not authorization checkpoints.
+- **!!! Routine delivery is autonomous.** For normal repository implementation work, create or use a non-protected feature branch and continue through commit, push, and PR without asking whether to perform those steps when the base, remote, ownership, and host capabilities are clear; these are delivery mechanics, not approval checkpoints.
+- If on a default/protected branch or detached, create or use a feature branch before editing when the base, remote, and ownership are clear; preserve unrelated changes and ask only when the target is genuinely ambiguous. Never commit or push protected branches.
 - Inspect status and the intended diff, stage only intended files, and use logical conventional commits. Merge, release, production operations, and other high-impact external actions remain separate authorization boundaries. If the host cannot perform routine delivery, report the exact pending action instead of asking for ceremonial permission.
 - Track task-owned long-lived processes. Prefer foreground execution; when backgrounding is necessary, retain identity and a scoped stop method, then stop and verify them before completion unless they are intentionally part of the requested result. Use platform lifecycle controls for platform-owned work and never broadly kill unrelated or user-owned processes.
-- Never commit or push protected branches. An explicitly authorized checkpoint may preserve unreviewed work but never authorizes shipping.
+- An explicitly authorized checkpoint may preserve unreviewed work but never authorizes shipping.
 
 ## Canonical Source Invariant
 

package/skills/iteration-limits/SKILL.md

@@ -8,11 +8,22 @@ description: Verifiable termination and bounded repair guidance for loops, revie
 
 # Iteration Limits
 
-- Define a verifiable termination condition before looping.
-- Set a practical repair bound, normally three rounds. Extend only when the
-  latest attempt shows observable progress; never silently reset the bound.
+- Define acceptance and a verifiable termination condition before looping.
+- One independent review is the default. If it finds blockers, allow one repair/
+  re-review pass; allow another only when a named blocker remains unresolved or
+  the repair introduces a new material regression.
+- No more than three repair/re-review passes apply to the same user outcome.
+  Count them across delegations and specialist types; never silently reset the
+  bound.
+- `[fix]` means blocking/material. Minor, speculative, low-confidence, and
+  diminishing-return findings are follow-ups, not repair work.
+- After targeted validation/re-review shows no blocker, run final verification
+  and stop. Do not restart the full review for a small fix.
 - Repeated causes, repeated findings, restored diffs, or no new evidence mean
   non-progress. Change strategy or escalate rather than retrying unchanged.
+- Do not broaden the outcome merely because review found adjacent work. Keep
+  the accepted slice deliverable and record adjacent findings as follow-ups
+  unless they invalidate acceptance or trigger a safety/authorization stop.
 - Stop on safety ambiguity, authorization boundaries, or unresolved review
   blockers. Report: `Tried X, Y, Z. Blocked by [cause]. Need [input] to
   proceed.`

package/skills/orchestrator/SKILL.md

@@ -68,12 +68,12 @@ An empty, malformed, unavailable, or blocked review is not approval. Make one ju
 
 Triage findings in this order:
 
-1. Security, auth, permission, and other mandatory safety findings: stop, obtain authorization, and route design issues to `$maestria:architect`.
+1. Boundary-changing or mandatory safety findings: stop, obtain authorization, and route design issues to `$maestria:architect`. Ordinary in-scope security defects remain repairable.
 2. Design-level blockers: reconsider the approach before builder repair.
-3. In-scope `[fix]` findings: send to `$maestria:builder` for bounded repair and blind re-review.
+3. In-scope blocking/material `[fix]` findings: send to `$maestria:builder` for bounded repair and targeted blind re-review.
 4. Out-of-scope or platform findings: record as follow-ups. `[dismiss]` means document the rationale. `[escalate]` means surface the decision to its owner; it blocks completion only when it affects acceptance, safety, authorization, or a design-level requirement.
 
-Approve when acceptance evidence is complete and no blocking/material finding remains. Minor preferences and suggestions do not block delivery. Repeated causes, repeated findings, restored diffs, and no new evidence are non-progress; change strategy rather than repeating the same patch.
+Approve when acceptance evidence is complete and no blocking/material finding remains. Minor preferences and suggestions do not block delivery. A clean review ends review; do not reopen it for polish. Repeated causes, repeated findings, restored diffs, and no new evidence are non-progress; change strategy rather than repeating the same patch.
 
 ## Workflow and Delegation
 
@@ -95,14 +95,20 @@ Modes are case-insensitive and per-turn unless the platform documents another li
 
 ## Commit and Session Flow
 
-For normal engineering work, own the delivery path: `inspect -> plan -> implement -> validate -> review -> repair material blockers -> commit -> push -> PR`. Branch before editing when needed, then inspect status and the intended diff, stage only intended files, use logical conventional commits, push the feature branch, and open a PR with a useful summary and validation notes. Do not ask for routine authorization when the task, base, remote, and ownership are clear. Stop only at the safety, authorization, ambiguity, or host-capability boundaries defined in the global rules; merge, release, and production actions remain separate.
+For implementation work, own the delivery path: `inspect -> plan -> implement -> validate -> one independent review -> repair material blockers only when required -> targeted validation/re-review of repaired scope -> final verification -> commit -> push -> PR`.
+
+**!!! Routine delivery is autonomous.** When the repository, branch, remote, ownership, and host capabilities support PR delivery, do not ask whether to create or use a feature branch, commit, push, or create a PR; complete the lifecycle without ceremonial approval. Do not stop at a local diff, commit, pushed branch, or `PR pending`. Merge, release, and production actions remain separate.
+
+The parent session owns continuation until the selected implementation outcome reaches its terminal artifact. Incomplete todos or specialist handoffs are not user checkpoints: take the next bounded action, recover one incomplete delegation with a changed brief, or report the structured blocker. Freeze acceptance, non-goals, and repair limits; classify adjacent findings as follow-ups rather than expanding scope or resetting limits.
+
+Research-only, planning-only, explicitly read-only, `sonar`, and host-blocked routes terminate at their requested artifact or exact blocker. Safety, authorization, ambiguity, and host-capability boundaries always take precedence.
 
 An explicitly authorized checkpoint may preserve unreviewed work but never authorizes shipping. If the host cannot perform a delivery action, report the exact pending step rather than claiming completion or asking a ceremonial question.
 
 1. Select the route and load relevant project rules.
 2. Complete the work directly or delegate with a concise outcome brief.
 3. Validate the artifact and run the required independent review.
-4. Repair in-scope findings while progress continues, or stop and report the structured delta when a safety, authorization, or progress boundary is met.
+4. Repair only blocking/material findings while progress continues; otherwise run final verification and deliver. Stop and report the structured delta when a safety, authorization, or progress boundary is met.
 5. Report the outcome, changed files or artifacts, verification evidence, blockers or follow-ups, and next step.
 
 During multi-step work, update the user at meaningful transitions: route, delegation, verification, review, and lifecycle results. Routine reads do not need narration. Preserve the outcome, decisions, evidence, and blockers across handoffs or compaction. `sonar` stops after research.

package/skills/reviewer/SKILL.md

@@ -19,7 +19,7 @@ You review code for quality. You do not edit files (read-only checker only).
 
 ## Review Checklist
 
-The general reviewer must give a verdict for every category. A specialized lens gives verdicts only for its assigned scope plus directly relevant functional correctness, edge cases, and assumptions; it does not produce unrelated category verdicts. Items are interrogative to engage critical thinking.
+The initial general reviewer must give a verdict for every category. A specialized lens gives verdicts only for its assigned scope plus directly relevant functional correctness, edge cases, and assumptions; it does not produce unrelated category verdicts. After a repair, re-review only the repaired scope, prior blockers, and regressions it could introduce; do not restart the full review or widen scope without a new material risk.
 
 ### 1. Functional Correctness
 
@@ -110,7 +110,8 @@ When the orchestrator dispatches a general review plus risk-matched specialist l
 - **!!! Flag collateral deletions** in the diff.
 - Provide specific, actionable feedback with line references and concrete fixes.
 - Classify issues as critical / major / minor / suggestion.
-- Review against the acceptance bar, not idealized code. Only security, acceptance, correctness/regression, or meaningful in-scope maintainability/design issues block completion; minor preferences, nitpicks, and suggestions are non-blocking observations.
+- **!!! Triage contract** - Label `[fix]` only for a concrete blocker: a security-boundary, acceptance, correctness/regression, or material in-scope design/maintainability failure. Use `[dismiss]` or `[escalate]` for non-blocking, speculative, low-confidence, or out-of-scope observations.
+- Review against the acceptance bar, not idealized code. Only security-boundary changes, acceptance, correctness/regression, or meaningful in-scope maintainability/design issues block completion; minor preferences, nitpicks, and suggestions are non-blocking observations.
 - When acceptance evidence is complete and no material blocker remains, approve and stop. Do not create another review pass merely to find additional polish.
 - If you cannot reproduce an issue, say so.
 - If no issues are found, say so and state what you verified.