[medium] Release 1.1.0: Codex activation and evidence-based agent handoffs

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "webdev-agent-kit",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Portable frontend workflow skills for planning, implementation, review, and visual QA.",
   "author": {
     "name": "Yevgeniy Tyan"

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "webdev-agent-kit",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Frontend workflow skills for React and Next.js planning, implementation, review, and visual QA.",
   "skills": "./skills/"
 }

.github/workflows/quality-ci.yml

@@ -38,12 +38,12 @@ jobs:
       - name: Ruff lint
         run: |
           set -o pipefail
-          ruff check scripts skills/agent-rules-skill-author/scripts skills/project-onboarding-adapter/scripts 2>&1 | tee ruff-lint.log
+          ruff check scripts skills/agent-rules-skill-author/scripts skills/project-onboarding-adapter/scripts skills/frontend-quality-reviewer/scripts 2>&1 | tee ruff-lint.log
 
       - name: Ruff format check
         run: |
           set -o pipefail
-          ruff format --diff scripts skills/agent-rules-skill-author/scripts skills/project-onboarding-adapter/scripts 2>&1 | tee ruff-format.log
+          ruff format --diff scripts skills/agent-rules-skill-author/scripts skills/project-onboarding-adapter/scripts skills/frontend-quality-reviewer/scripts 2>&1 | tee ruff-format.log
 
       - name: YAML lint
         run: |

.github/workflows/skill-pack-ci.yml

@@ -28,6 +28,7 @@ jobs:
           python -m py_compile scripts/*.py
           python -m py_compile skills/agent-rules-skill-author/scripts/*.py
           python -m py_compile skills/project-onboarding-adapter/scripts/*.py
+          python -m py_compile skills/frontend-quality-reviewer/scripts/*.py
 
       - name: Validate schemas
         id: validate_schemas
@@ -152,6 +153,9 @@ jobs:
       - name: Build portable targets
         run: python scripts/build_skill_targets.py
 
+      - name: Validate exact review handoffs and packaged helper
+        run: python scripts/validate_review_handoffs.py --generated
+
       - name: Validate generated runtime policy layers
         run: python scripts/validate_runtime_layers.py --generated
 
@@ -202,3 +206,22 @@ jobs:
       - name: Fail if full validation failed
         if: steps.validate_full.outputs.status != '0'
         run: exit ${{ steps.validate_full.outputs.status }}
+
+  runtime-helpers:
+    name: Native helper regressions (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    env:
+      PYTHONUTF8: '1'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Test documented onboarding and configuration recovery
+        run: python -m unittest discover -s scripts -p test_model_routing.py -v
+      - name: Test real Git review snapshots
+        run: python -m unittest discover -s scripts -p test_review_package.py -v

CHANGELOG.md

@@ -11,6 +11,7 @@ tags:
     - 'release-management'
 parent: []
 related:
+    - '[[docs/release/1.1.0-checklist]]'
     - '[[docs/release/1.0.0-checklist|1.0.0 GPT Routing Validation]]'
     - '[[docs/release/0.5.0-checklist|0.5.0 Release Checklist]]'
     - '[[README|WebDev Agent Kit README]]'
@@ -31,6 +32,57 @@ Use this changelog for source-bundle and distribution-target changes that affect
 
 ### Added
 
+- Workload-based Luna/Terra/Sol/Astra capability selection with independent
+  effort guidance, explicit architecture coverage and bounded light/deep variants.
+- Backward-compatible optional native roles; additive setup preserves existing
+  files and bindings, verifies new paths, and rejects implicit role removal.
+- Automatic missing project-local subagent setup during full Codex onboarding,
+  with schema-backed key selection, bounded preview and read-only inspection.
+- Self-contained delegated task/report templates and a local review packager for
+  complete task commits or scoped staged, unstaged and untracked changes.
+- Plan-scoped artifact identity, precise repair re-review and retained completion
+  evidence without making small tasks use agents or durable plans.
+- Regression and documented-example checks, packaged-helper validation and live
+  scenarios for activation, missing permissions, recovery and review evidence.
+
+### Changed
+
+- Onboarding separates configuration, client refresh/discovery and observed
+  per-role activation; absence of pre-setup delegation no longer skips setup.
+- Full onboarding no longer needs a separate GPT setup confirmation. Facts-only,
+  no-model-change, Plan Mode and update requests preserve model configuration.
+- Named-role and explicit model/effort dispatch use actual tool signatures and
+  separate runtime evidence; direct dispatch does not certify native role loading.
+- Existing task, review and authoring skills adopt file-based handoffs and
+  structural-versus-behavioral evidence distinctions without overriding test scope.
+- User guides, README, upgrade notes and release checklist describe actual limits.
+- Source and portable-target version metadata advance to 1.1.0 with 21 skills.
+
+### Fixed
+
+- Reject Windows junction/reparse-point escapes in role configuration, recovery
+  and review-artifact paths, including host-root ancestry, on Python 3.11+.
+- Protect Windows recovery journals with verified current-user ACLs before sensitive
+  writes, rather than assuming POSIX chmod bits apply; retain POSIX mode checks.
+- Persist only journal DACL changes through native .NET access control, avoiding
+  Windows PowerShell Set-Acl's unnecessary SeSecurityPrivilege requirement.
+- The installer no longer ignores an explicit `features.multi_agent = false`.
+  Both known disabling gates are checked; only the selected approved local key
+  may change. Trust, managed policy, global and primary model settings are untouched.
+- Review snapshots no longer depend on a last-commit assumption or omit owned
+  uncommitted work when working-tree mode is explicitly selected.
+
+### Validation Scope
+
+- Offline tests validate real configuration/helper behavior and documentation
+  examples, not authenticated Codex models. Live scenarios remain unverified
+  until an authorized client run supplies actual child metadata and assessment.
+- Existing schema-1 requests/state and normal single-agent fallback remain valid.
+
+## 1.0.0
+
+### Added
+
 - Opt-in instruction-driven GPT model routing for supported local Codex clients:
   bounded lookup, implementation, complex reasoning and independent review roles.
 - Evidence-gated onboarding that selects available GPT IDs and supported efforts

README.md

@@ -10,7 +10,7 @@
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/Skills-19-0ea5e9?style=flat-square" alt="Skills: 19">
+  <img src="https://img.shields.io/badge/Skills-21-0ea5e9?style=flat-square" alt="Skills: 21">
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache--2.0-blue?style=flat-square" alt="License: Apache-2.0"></a>
 </p>
 
@@ -200,6 +200,30 @@ CI, or actual verification results. Stale facts must be updated. The kit does
 not promise a fixed token-savings percentage; it reduces waste by avoiding
 unnecessary context and repeated repository scans.
 
+## Economical GPT Subagents And Review Handoffs
+
+Full Codex onboarding configures missing project-local roles for bounded lookup,
+implementation, complex reasoning and independent review. Models and reasoning
+efforts come from the actual client catalog, not hardcoded production IDs.
+Version 1.1.0 also previews and applies a narrow supported native subagent
+activation field when needed. The primary model, global configuration, MCP,
+trust and security settings remain unchanged.
+
+No separate setup command or second confirmation is needed. Existing working
+bindings remain unchanged; facts-only/no-model-change requests and Plan Mode
+exclude model setup and canaries. A written TOML is only configured: refresh the
+client and verify the actual child model, effort and permissions. Missing runtime
+evidence retains the ordinary single-agent workflow. Named-role and direct
+model/effort dispatch are verified separately for the actual client surface. See the
+[GPT routing guide](docs/install/gpt-model-routing.md) for commands and diagnosis.
+
+For justified delegated work, compact task packets preserve criteria, interfaces,
+owned files and retry budgets. Exact review packages cover all task commits or
+an explicitly scoped working-tree snapshot; repeat review focuses on fixes and
+their consequences. These artifacts stay local and do not burden small edits.
+The [design notes](docs/architecture/superpowers-adoption.md) explain what was
+adapted from Superpowers and which heavier workflows were deliberately excluded.
+
 ## Verifying the Installation
 
 Use this read-only smoke prompt:

adapters/codex.md

@@ -35,7 +35,9 @@ Use the active tool registry or validated project facts as capability evidence.
 Native tools can satisfy capabilities without MCP. Keep sandbox and approvals
 separate; never bypass either. Report blocked checks after bounded fallback.
 
-For approved GPT setup, onboarding uses its `references/codex-model-bootstrap.md`.
+Full onboarding uses `references/codex-model-bootstrap.md` for automatic local
+GPT setup, unless explicitly excluded. Inspect the live delegation signature:
+named-role and explicit-binding are separate verified dispatch modes, not aliases.
 For task delegation with a local model-routing profile, load
 `common/codex-model-routing-policy.md` before broad context. No config writes
 during ordinary work, silent model upgrades, or changes to global defaults.

bundle-manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "webdev-agent-kit",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "license": "Apache-2.0",
   "description": "Internal source and distribution inventory for the WebDev Agent Kit skill bundle.",
   "portable_core": "common/core/runtime-core-policy.md",

common/checkpoint-rules.md

@@ -53,3 +53,13 @@ The active plan remains the canonical planning state. Progress, decision, and
 loop-memory files record evidence and resume pointers; they must not duplicate
 or independently redefine criteria, slices, coverage states, or convergence
 findings.
+
+## Delegated Artifact Identity
+
+For durable delegation follow `common/subagent-handoff-rules.md`: plan-scoped
+briefs, reports and review evidence are local artifacts, not a competing plan.
+Before resuming, compare recorded repository/worktree, plan hash, commits and
+covered file state with reality. Preserve the completion status and evidence
+pointers in the canonical progress record; a cleaned scratch folder or an old
+checkbox must not cause completed work to be redispatched or reverted work to
+be treated as verified.

common/codex-model-routing-policy.md

@@ -11,6 +11,7 @@ tags:
 parent:
     - '[[AGENTS]]'
 related:
+    - '[[common/subagent-handoff-rules]]'
     - '[[common/bounded-retry-rules]]'
     - '[[common/independent-review-rules]]'
     - '[[skills/project-onboarding-adapter/references/codex-model-bootstrap]]'
@@ -25,27 +26,30 @@ instructions can change the model of a running response.
 
 ## Activation
 
-Apply only in Codex with callable native delegation and approved, runtime-verified
-roles in local `project/model-routing-profile.md`. Check that its client, auth
-mode, configuration fingerprint and role evidence still match the current
-session. Missing, stale, disabled or unavailable routing leaves the existing
-single-agent workflow intact; report limits only when they affect the task.
+Apply only in Codex with callable delegation and approved, runtime-verified
+roles in `project/model-routing-profile.md`. Match client, auth, fingerprint and
+role evidence. Missing, stale or disabled routing retains single-agent work.
 Never create configuration during ordinary work. Configuration syntax alone,
 a model self-report, a skill name and `agents/openai.yaml` are not runtime proof.
 
 ## Executor Selection
 
-Classify the next action using existing workflow rules before broad context
-loading. Keep trivial work inline when coordination would cost more than it
-saves. Use tools directly for deterministic commands. Do not bind an entire
-skill or workflow level permanently to a model.
+Classify before broad reading. Keep trivial work inline and deterministic
+commands on tools. Never bind a whole skill or workflow level to a model.
 
 | Executor | Suitable action | Boundary |
 | --- | --- | --- |
 | `wdk_lookup` | Bounded read-heavy evidence gathering | No edits or fixers |
 | `wdk_worker` | Explicit low-risk implementation slice | Assigned files only |
 | `wdk_complex` | Ambiguous cause or cross-boundary reasoning | No scope expansion |
 | `wdk_reviewer` | Material-risk independent review | No implementation |
+| `wdk_architect` | Consequential architecture and migration design | Read-only; user owns decisions |
+
+For model/effort selection use
+`skills/project-onboarding-adapter/references/model-workload-matrix.md`.
+It covers Luna, Terra, Sol, Astra, effort and optional light/deep roles.
+Architecture risk can require Astra directly; tiny architecture-adjacent edits
+stay inline. Do not confuse workflow weight, model capability and effort.
 
 Choose the least costly verified adequate role, considering uncertainty,
 consequences, tool access, input modalities, context size and verification.
@@ -55,12 +59,18 @@ user's primary model and approved cost ceiling. No silent expensive fallback.
 
 ## Delegation Contract
 
-Use the actual native delegation tool and the configured role name. A custom
-role's fixed model and effort are not overridden by prose; escalation selects
-a different approved role. Pass only the selected skill, goal and acceptance
+Use the verified dispatch mode for this client surface. `named-role` selects a
+discovered custom role; `explicit-binding` passes its confirmed model AND effort
+and role instructions through supported parameters. A task name is not a role
+selector. Direct-binding evidence does not prove native configuration loading.
+Never invent parameters or reuse another surface's verification. A fixed role
+binding is not overridden by prose. Pass only the selected skill, goal and acceptance
 criteria, owned paths, constraints, decisive evidence, required tools, checks,
 and remaining attempt budget. Do not forward the full parent transcript.
 
+Use `common/subagent-handoff-rules.md` for self-contained task/report packets
+and batching independent same-shape mechanical edits.
+
 Only the coordinator delegates. Default to sequential work; use at most two
 concurrent children only for independent, explicitly bounded assignments, and
 honor stricter client limits. Never allow overlapping writers. Reuse returned

common/codex-official-docs-policy.md

@@ -74,7 +74,7 @@ The Docs MCP is read-only and documentation-only. It cannot call the OpenAI API,
 
 - Treat `AGENTS.md` as durable guidance that Codex reads before work; keep repository-level instructions small enough to stay inside discovery limits.
 - Treat skills as progressive-disclosure workflows: frontmatter names and descriptions are the trigger surface; detailed instructions and references are loaded only after selection.
-- Treat `.codex/config.toml` as configuration, not runtime policy text. Do not create or change it without explicit user approval.
+- Treat `.codex/config.toml` as configuration, not runtime policy text. A full Codex onboarding request covers the narrow model bootstrap described by the onboarding skill; facts-only/Plan Mode requests do not. Other changes require explicit user approval.
 - Treat sandbox and approval policy as separate controls: sandbox defines technical boundaries, and approval policy defines when Codex must ask before crossing them.
 - Treat MCP configuration as explicit tool setup. Verify official install sources and ask for approval before installing servers or changing configuration.
 

common/independent-review-rules.md

@@ -94,3 +94,13 @@ claiming independent verification of those repairs.
 Independent review is valid only when it evaluates the acceptance criteria and
 evidence instead of merely restating the implementer's summary. Review findings
 must not add, remove, reorder, renumber, or mark plan slices.
+
+## Scoped Repair Review
+
+For delegated durable review use `common/subagent-handoff-rules.md` and
+`skills/frontend-quality-reviewer/references/review-handoffs.md`. The review
+surface must include all task commits or the actual uncommitted snapshot, not
+only the last commit. Re-review the open findings and repair-induced risk; widen
+only for concrete dependent-interface, security, or outcome evidence. Unrelated
+preferences never extend a repair loop. Preserve required failed criteria at
+the attempt cap; completion is not manufactured by deferring mandatory work.

common/subagent-handoff-rules.md

@@ -0,0 +1,71 @@
+---
+id: "agents.common.subagent-handoff-rules"
+title: "Subagent Handoff Rules"
+doc_type: "common-rule"
+layer: "common"
+status: "active"
+publishable: true
+local_only: false
+tags: []
+parent:
+  - "[[AGENTS]]"
+related:
+  - "[[common/codex-model-routing-policy]]"
+  - "[[common/independent-review-rules]]"
+  - "[[templates/subagent-task]]"
+  - "[[templates/subagent-report]]"
+depends_on: []
+---
+
+# Subagent Handoff Rules
+
+Apply only when existing routing and risk rules justify actual delegation.
+A small edit stays inline; this rule never mandates agents, plans, or reviews.
+
+## Task Packet
+
+Pass the smallest self-contained assignment, using
+`templates/subagent-task.md` when a durable handoff is needed. Preserve the
+canonical plan's `S-###` and `AC-###`; include exact global constraints and
+interfaces consumed/produced, owned files, decisive evidence, available tools,
+verification and the remaining shared attempt budget. Reference the source plan
+and its revision/hash. Do not send the full plan or parent transcript by default.
+The worker may request a missing fact; it must not invent an interface.
+
+Keep existing canonical planning files. Store briefs, reports and review
+packages only in local, git-ignored `project/runs/<plan-id>/`; scope the ID to
+the repository/worktree and canonical plan path. Never mix another plan's files.
+The review helper derives its namespace from that path. Reuse the returned
+namespace for related task artifacts. No automatic migration of older plans.
+Use native file tools if a helper is unavailable; do not install a runtime.
+
+## Dispatch And Return
+
+Only the coordinator dispatches; one writer owns each path. Batch independent
+same-shape mechanical edits with shared constraints and verification into one
+assignment when that reduces overhead. Do not batch unrelated risky interfaces.
+Choose an approved adequate role per action, not by skill name or token price.
+
+Use `templates/subagent-report.md` for durable work. The return status is
+`done`, `done-with-concerns`, `needs-context`, or `blocked`, with evidence and a
+report path. None alone marks an acceptance criterion verified. Missing context
+calls for a targeted fact, environment denial for a blocker, and demonstrated
+reasoning mismatch for an approved escalation. Neither a new worker nor a new
+model resets the retry budget. Reuse a worker for a scoped repair when supported;
+otherwise pass its report and open findings to a fresh one.
+
+## Review And Recovery
+
+Pass the brief, report and exact review surface to an actually isolated reviewer
+when `common/independent-review-rules.md` requires independence. Include binding
+constraints without telling the reviewer which conclusions to reach. Evidence
+must match the reviewed revision or working-tree snapshot; a previously green
+check is reusable only for the unchanged covered state and environment.
+
+Use `skills/frontend-quality-reviewer/references/review-handoffs.md` for packages
+and scoped re-review. Record decisions, unresolved findings, evidence locations
+and next action in the canonical progress state before switching tasks. On
+resume reconcile that state with Git and actual file hashes; never trust a
+checkbox after a rollback. Preserve completion and evidence pointers after
+finishing. Do not delete all traces of a run or mark failed criteria verified
+because the attempt budget ended.