@tea-agent/loop-agent 0.42.0-next.1 → 0.42.0-next.3

package/docs/templates/frontend-implementation-dag.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "./agent-dag.schema.json",
+  "version": 2,
+  "title": "Frontend implementation independent DAG template",
+  "objective": "Replace with the concrete, bounded frontend implementation objective for this DAG run.",
+  "successCriteria": [
+    "The contract covers every required user-visible behavior, state, and interaction.",
+    "The implementation is admitted only after a concrete, narrow writeSet is reviewed.",
+    "Static and behavior verification are recorded before final review.",
+    "The final closeout distinguishes passed, not-run, and residual-risk evidence."
+  ],
+  "globalConstraints": [
+    "This is a self-contained static template: do not generate, import, or merge a DAG from a runtime builder before execution.",
+    "Replace every REPLACE/WITH/... placeholder with concrete repository paths or deterministic commands before execution.",
+    "Do not commit runtime traces under .harness/dag-runs/.",
+    "Every node must explicitly declare its executor; defaults.executor is schema-only and not a runtime fallback.",
+    "Only frontend-implement-pi may write project files, and only inside its concrete writeSet.",
+    "Read-only nodes must not write root artifacts/**; root artifacts/ is not a per-node scratchpad.",
+    "Do not infer missing behavior, states, interactions, design decisions, or verification commands. Stop for an explicit task-contract revision instead.",
+    "Do not add dependencies unless they are already declared by the project contract."
+  ],
+  "defaults": {"executor":"pi","contextProfile":"slim","skills":["ai-engineering-context"],"writePolicy":"read-only"},
+  "skillsByRole": {
+    "planner":["loop-agent"], "scout":["ai-engineering-context"], "implementer":["verification-before-completion"], "reviewer":["requesting-code-review"], "verifier":["verification-before-completion","systematic-debugging"], "closeout":["loop-agent","verification-before-completion"]
+  },
+  "executorModels": {"pi":{"LOW":"gpt-5.3-codex-spark","MED":"gpt-5.5","HIGH":"gpt-5.5"}},
+  "tasks": [
+    {
+      "id":"frontend-contract-pi", "depends_on":[], "complexity":"MED", "executor":"pi", "role":"planner", "writePolicy":"read-only", "allowedPaths":["**"], "forbiddenPaths":[".harness/**","artifacts/**"],
+      "outputContract":"Plain Markdown frontend contract: required behavior, states, interactions, non-goals, concrete verification expectations, and unresolved gaps; no file writes.",
+      "subtask_prompt":"Read the task inputs. Produce a concise frontend contract that maps each required behavior, UI state, and interaction to observable outcomes. Identify missing or conflicting requirements as blockers; do not infer them and do not edit files."
+    },
+    {
+      "id":"frontend-scout-pi", "depends_on":["frontend-contract-pi"], "complexity":"LOW", "executor":"pi", "role":"scout", "writePolicy":"read-only", "allowedPaths":["REPLACE/WITH/FRONTEND/SOURCE/PATH/**","REPLACE/WITH/FRONTEND/TEST/PATH/**"], "forbiddenPaths":[".harness/**","artifacts/**"],
+      "outputContract":"Plain Markdown source and verification reconnaissance: relevant routes, components, styles, state patterns, focused tests, and risks; no file writes.",
+      "subtask_prompt":"Inspect only the declared frontend source and test paths. Report reusable component, styling, accessibility, state-management, and verification patterns that satisfy the contract. Do not edit files or broaden the allowed paths."
+    },
+    {
+      "id":"frontend-plan-pi", "depends_on":["frontend-scout-pi"], "complexity":"MED", "executor":"pi", "role":"planner", "writePolicy":"read-only", "allowedPaths":["REPLACE/WITH/FRONTEND/SOURCE/PATH/**","REPLACE/WITH/FRONTEND/TEST/PATH/**"], "forbiddenPaths":[".harness/**","artifacts/**"],
+      "outputContract":"Plain Markdown implementation plan: ordered changes, concrete target files, behavior/state/interaction coverage, and focused verification mapping; no file writes.",
+      "subtask_prompt":"Turn the contract and reconnaissance into a minimal implementation plan. Every target file and verification step must be concrete. Preserve existing design and accessibility conventions. If any behavior lacks a verifiable target, report it as blocked instead of guessing."
+    },
+    {
+      "id":"frontend-design-policy-shell", "depends_on":["frontend-plan-pi"], "complexity":"LOW", "executor":"shell", "role":"verifier", "writePolicy":"read-only", "allowedPaths":["REPLACE/WITH/FRONTEND/SOURCE/PATH/**","REPLACE/WITH/FRONTEND/TEST/PATH/**"], "forbiddenPaths":[".harness/**","artifacts/**"],
+      "outputContract":"Archived deterministic design-policy result proving the plan uses declared dependencies, concrete requirements, and approved design evidence; no worktree writes.",
+      "subtask_prompt":"Run the project-specific deterministic design-policy check selected for this task. It must reject missing requirement coverage, unauthorized dependencies, and unresolved design conflicts.",
+      "shell":{"commands":["REPLACE/WITH/DESIGN-POLICY/COMMAND"],"cwd":".","timeoutMs":300000}
+    },
+    {
+      "id":"frontend-design-review-pi", "depends_on":["frontend-design-policy-shell"], "complexity":"MED", "executor":"pi", "role":"reviewer", "writePolicy":"read-only", "allowedPaths":["REPLACE/WITH/FRONTEND/SOURCE/PATH/**","REPLACE/WITH/FRONTEND/TEST/PATH/**"], "forbiddenPaths":[".harness/**","artifacts/**"],
+      "outputContract":"Plain Markdown design review: approved plan or explicit blocking findings for behavior, state, interaction, design-system, and accessibility coverage; no file writes.",
+      "subtask_prompt":"Review the approved plan against the frontend contract and design-policy result. Reject missing visible states, interaction behavior, accessibility obligations, or unsupported design claims. Do not edit files."
+    },
+    {
+      "id":"frontend-writer-admission-shell", "depends_on":["frontend-design-review-pi"], "complexity":"LOW", "executor":"shell", "role":"verifier", "writePolicy":"read-only", "allowedPaths":["REPLACE/WITH/FRONTEND/TARGET/PATH/**"], "forbiddenPaths":[".harness/**","artifacts/**"],
+      "outputContract":"Archived deterministic writer-admission result with a concrete, narrow writeSet and pre-write baseline; no worktree writes.",
+      "subtask_prompt":"Run the project-specific writer-admission check. It must derive and record a concrete writeSet from the approved plan, reject broad paths and scope drift, and capture the pre-write baseline before authorizing the writer.",
+      "shell":{"commands":["REPLACE/WITH/WRITER-ADMISSION/COMMAND"],"cwd":".","timeoutMs":300000}
+    },
+    {
+      "id":"frontend-implement-pi", "depends_on":["frontend-writer-admission-shell"], "complexity":"HIGH", "executor":"pi", "role":"implementer", "toolProfile":"write", "writePolicy":"exclusive", "writeSet":["REPLACE/WITH/FRONTEND/TARGET/PATH/**"], "allowedPaths":["REPLACE/WITH/FRONTEND/TARGET/PATH/**"], "forbiddenPaths":[".harness/**","artifacts/**"],
+      "outputContract":"Implementation summary with changed files, contract coverage, focused checks run, and residual risks.",
+      "subtask_prompt":"Implement only the admitted frontend changes. Preserve established component, styling, accessibility, and state-management conventions. Cover every approved behavior, state, and interaction, then report changed files and focused verification. Do not broaden writeSet or add undeclared dependencies."
+    },
+    {
+      "id":"frontend-verify-shell", "depends_on":["frontend-implement-pi"], "complexity":"LOW", "executor":"shell", "role":"verifier", "writePolicy":"read-only", "allowedPaths":["REPLACE/WITH/FRONTEND/TARGET/PATH/**"], "forbiddenPaths":[".harness/**","artifacts/**"],
+      "outputContract":"Archived static and behavior verification output with command exit codes; no worktree writes.",
+      "subtask_prompt":"Run the contract-selected deterministic static and behavior verification commands. Record all exit codes. A failed required command is terminal for this DAG run; do not silently substitute a different command.",
+      "shell":{"preset":"loop-agent-standard-verify","cwd":".","timeoutMs":300000}
+    },
+    {
+      "id":"frontend-review-context-shell", "depends_on":["frontend-verify-shell"], "complexity":"LOW", "executor":"shell", "role":"verifier", "writePolicy":"read-only", "allowedPaths":["REPLACE/WITH/FRONTEND/TARGET/PATH/**"], "forbiddenPaths":[".harness/**","artifacts/**"],
+      "outputContract":"Archived deterministic final-review context: admitted writeSet, cumulative diff, and required verification evidence; no worktree writes.",
+      "subtask_prompt":"Run the project-specific review-context collector. It must bind the admitted writeSet, actual cumulative diff, and required verification results so final review cannot rely on summaries alone.",
+      "shell":{"commands":["REPLACE/WITH/REVIEW-CONTEXT/COMMAND"],"cwd":".","timeoutMs":300000}
+    },
+    {
+      "id":"frontend-review-pi", "depends_on":["frontend-review-context-shell"], "complexity":"MED", "executor":"pi", "role":"reviewer", "writePolicy":"read-only", "allowedPaths":["REPLACE/WITH/FRONTEND/TARGET/PATH/**"], "forbiddenPaths":[".harness/**","artifacts/**"],
+      "outputContract":"Plain Markdown final review: approved result or explicit findings for contract coverage, regression risk, accessibility, and verification gaps; no file writes.",
+      "subtask_prompt":"Review the actual diff and archived verification evidence against the frontend contract. Do not treat missing, weak, mock-only, or not-run evidence as passed. Report explicit residual risks; do not edit files."
+    },
+    {
+      "id":"frontend-closeout-shell", "depends_on":["frontend-review-pi"], "complexity":"LOW", "executor":"shell", "role":"closeout", "writePolicy":"read-only", "allowedPaths":["REPLACE/WITH/FRONTEND/TARGET/PATH/**"], "forbiddenPaths":[".harness/**","artifacts/**"],
+      "outputContract":"Archived deterministic closeout summarizing contract coverage, verification status, review findings, evidence gaps, and residual risks; no worktree writes.",
+      "subtask_prompt":"Run the project-specific deterministic closeout renderer. Preserve evidence status exactly: passed, failed, not-run, mock-backed, and baseline debt must never be promoted to a stronger result.",
+      "shell":{"commands":["REPLACE/WITH/CLOSEOUT/COMMAND"],"cwd":".","timeoutMs":300000}
+    }
+  ]
+}

package/docs/templates/spec-registry.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://loop-agent.local/schemas/spec-registry.schema.json",
+  "title": "Frontend specification registry",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "roots"],
+  "properties": {
+    "version": { "const": 1 },
+    "roots": {
+      "type": "array",
+      "maxItems": 32,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path"],
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^(?!/)(?!.*//)(?!.*\\\\)(?!.*(?:^|/)\\.{1,2}(?:/|$)).+$"
+          },
+          "scope": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 },
+            "uniqueItems": true
+          },
+          "mode": { "enum": ["normative", "advisory"] },
+          "description": { "type": "string" }
+        }
+      }
+    },
+    "discovery": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": { "type": "boolean", "default": true },
+        "maxDepth": { "type": "integer", "minimum": 0, "maximum": 8, "default": 3 },
+        "maxFiles": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 },
+        "maxBytes": { "type": "integer", "minimum": 1, "maximum": 10485760, "default": 1048576 },
+        "timeoutMs": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 2000 }
+      }
+    }
+  }
+}

package/harness.json

@@ -87,4 +87,4 @@
       "HIGH": "wizard-local/gpt-5.6-sol"
     }
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.42.0-next.1",
+  "version": "0.42.0-next.3",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",

package/skills/frontend-bounded-implement/SKILL.md

@@ -1,17 +1,23 @@
 ---
 name: frontend-bounded-implement
 description: >-
-  Use only for frontend implementation and repair writers after the canonical
+  Use only for frontend implementation writers after the canonical
   contract gate has authorized a bounded write set.
+references:
+  - path: references/code-standards.md
+    required: true
+    maxChars: 2600
 ---
 
 # Frontend Bounded Implement
 
+Read the bounded code standards before editing. They apply only inside the
+canonical targets and do not authorize additional discovery.
+
 ## Authoritative Inputs
 
 - For implementation, use the run-owned
   `contracts/frontend-implementation-contract.json`.
-- For repair, also use `contracts/frontend-repair-assessment.json`.
 - Treat requirement `expectedOutcome`, interaction `trigger` /
   `expectedBehavior`, target files, UI states, Mock/API strategy, and verification
   targets as closed decisions. Do not rediscover or reinterpret them.
@@ -25,7 +31,7 @@ description: >-
 - Start the bounded edit after confirming the contract and targets. Optional
   context is not a reason to postpone implementation.
 - If behavior is still ambiguous or a required target is outside `writeSet`, stop
-  with `IMPLEMENTATION_OUTCOME: blocked`; do not compensate with broader scouting.
+  without writing and explain the blocker; do not compensate with broader scouting.
 
 ## Implementation Discipline
 
@@ -39,15 +45,10 @@ description: >-
 - Run only the focused checks already frozen by the task. Leave full verification
   to downstream deterministic nodes.
 
-## Required Outcome
-
-The first non-empty response line must be exactly one of:
-
-- `IMPLEMENTATION_OUTCOME: changed` — a non-empty bounded diff was produced.
-- `IMPLEMENTATION_OUTCOME: already-satisfied` — the contract was already met and
-  no file changed.
-- `IMPLEMENTATION_OUTCOME: blocked` — implementation cannot proceed without
-  guessing or exceeding the write boundary.
+## Completion Summary
 
-Then report changed files, requirements/interactions implemented, tests or focused
-checks attempted, and residual risks. Never report `changed` for an empty diff.
+Briefly report changed files, implemented requirements/interactions, focused checks
+attempted, blockers, and residual risks. This summary is human-readable only: the
+runtime derives implementation state from persisted write events, run delta, write
+guard, requirement coverage, and focused checks. Do not use a mandatory
+`IMPLEMENTATION_OUTCOME:` response-text protocol.

package/skills/frontend-bounded-implement/references/code-standards.md

@@ -0,0 +1,19 @@
+# Bounded Frontend Code Standards
+
+Apply the canonical contract and the conventions visible in target files and their
+direct local dependencies. Do not reopen task sources, OpenSpec, `ai_workspace`, or
+unrelated repository areas to discover new rules or redesign approved decisions.
+
+- Work test-first when behavior changes and preserve unrelated behavior.
+- Reuse existing public helpers, APIs, components, tokens, schemas, and test
+  patterns that are directly available from the bounded target surface.
+- Keep rendering, transitions, validation, request lifecycle, errors, and side
+  effects testable; cover relevant races and boundaries.
+- Keep real API behavior enabled by default. Mock activation must follow the
+  approved strategy, remain explicit and dev/test-only, and never import test mocks
+  into production code.
+- Trace fixtures to the approved API/schema evidence and never store secrets.
+- Do not add unapproved dependencies, relax lint/type/test/build configuration,
+  add `.skip`/`.only`, comment out real requests, or write outside `writeSet`.
+- Run only frozen focused checks and report their real status. Downstream shell
+  verification remains authoritative.

package/skills/frontend-contract/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: frontend-contract
+description: Use only for the read-only frontend requirement contract node.
+references:
+  - path: references/contract-protocol.md
+    required: true
+    maxChars: 4200
+---
+
+# Frontend Contract
+
+Use task sources, explicit references, constraints, and the frozen source-fidelity
+ledger. Preserve canonical requirement IDs, source fragments, commands, paths, and
+language. Do not inspect implementation files or choose components, routes, Mock
+mechanisms, dependencies, or target code as requirement facts.
+
+Submit confirmed facts incrementally with the contract `record_*` tools and finish
+with exactly one `finalize_contract`. Start recording as soon as a requirement or
+constraint is confirmed; do not accumulate the whole contract in one response.
+
+Missing product semantics may be explicit assumptions only when they do not change
+observable behavior. Otherwise record a blocking question or a split proposal.
+This node is read-only.

package/skills/frontend-contract/references/contract-protocol.md

@@ -0,0 +1,34 @@
+# Frontend Contract Protocol
+
+## Requirement fidelity
+
+- Use the frozen canonical requirement ID for every requirement. Never invent a
+  replacement REQ/BR/AC ID.
+- Bind every requirement to exactly the source fragment IDs supplied by the
+  source-fidelity ledger. Do not infer fragment IDs from prose.
+- Record observable outcomes, applicable UI states, runtime/environment constraints,
+  non-goals, risks, and verification expectations without choosing implementation.
+- Classify each requirement as `explicit`, `repository-resolvable`, `assumption`, or
+  `blocking`. Blocking facts name their owner and evidence.
+
+## Evidence and handoff
+
+- Register static, behavior, Mock, and real-integration evidence expectations as
+  required, optional, or not-applicable. The classification follows the source and
+  risk; it is not selected for model convenience.
+- Register a non-blocking frontend-test handoff for UI-visible or interactive work.
+- Preserve exact command labels and referenced paths. Do not invent evidence,
+  connector results, APIs, or verification commands.
+
+## OpenSpec selection
+
+When the frozen task exposes OpenSpec candidates, record only candidates actually
+used by the contract as `required` or `relevant`. Explicit required paths and task
+source citations remain required. Unmentioned candidates are irrelevant; do not
+enumerate or downgrade them.
+
+## Terminal
+
+Commit facts in small batches and call `finalize_contract` exactly once with
+`ready`, `ready-with-assumptions`, or `blocked`. If the task is too large for one
+bounded writer, record a split proposal instead of broadening the contract.

package/skills/frontend-design-review/SKILL.md

@@ -9,31 +9,26 @@ references:
 
 # Frontend Design Review
 
-For frontend design review nodes. Read the checklist; audit contract, scout, Mock
-strategy, effective plan, task bounds, and traceable design evidence.
-Knowledge base, OpenSpec, and `ai_workspace/` are parallel sources. Query the
-knowledge-base connector when available; always search/read `openspec/schemas/**`,
-`openspec/project-specs/**`, and `ai_workspace/**` before accepting conventions.
-Connector format is TODO: never invent results.
+For frontend design review nodes. Read the checklist and the non-blocking contract
+capacity diagnostic first. Audit either the canonical contract or, when the
+diagnostic recommends indexed reading, its hash-bound field sections. Check the
+bound Mock strategy, task bounds, and traceable design evidence supplied by the
+upstream context. Do not rediscover task sources, search specification roots, or
+replace frozen evidence with nearby-code conventions. Use only exact, bound evidence
+paths when additional reading is necessary; never invent connector results.
 
-## Verdict Contract
+## Authoritative Terminal
 
-First non-empty line: exactly `VERDICT: pass` or `VERDICT: request-revision`.
-Any blocker requires request-revision. An initial pass is the effective verdict;
-there is no intermediate first-design shell gate.
+Complete the review with exactly one committed typed tool call:
 
-In standard/full topology, revision and final review run only after initial
-`VERDICT: request-revision`. Verify every Required Plan Correction against the
-complete revision; reject remaining, incomplete, or new gaps. An initial pass uses
-the original plan and skips both conditional nodes.
+- `approve_design` when no blocking design defect remains;
+- `request_design_changes` when a blocker exists. It must include a typed
+  `issueCategory`, at least one `evidenceRef`, and non-empty findings.
 
-Small-risk topology instead removes initial review and revision, then runs
-`frontend-final-design-review-pi` as the sole review of the original plan. Do not
-expect initial findings or a revision there.
-
-The deterministic gate prefers final-review output and falls back to initial review
-only when no current-run final output exists. Existing malformed/non-pass primary
-output fails closed.
+The typed terminal is the only authoritative outcome. Do not require or emit a
+`VERDICT:` line, JSON verdict, revision patch, or a second final-design-review
+verdict. A requested design change ends this run; the recovery controller creates
+any bounded follow-up run from the appropriate phase.
 
 ## Blocking Conditions
 
@@ -51,29 +46,15 @@ Knowledge-base absence is advisory if relevant rules from either openspec
 specification directory were read and applied. Block skipped fallback, unresolved
 conflict, or unresolved UI decisions.
 
-## Method And Output
+## Method And Human-readable Output
 
 Map criteria to steps/files/states/checks, audit paths/evidence, classify Blocking
 or Advisory, and never edit files.
 
 ### Spec Evidence Rules
 
-Run `grep`/`find`, then explicit `read` calls for applicable specs/checklist. Only
-successful paired reads count as “已读取规范文件”; summaries do not. List each path/
-section in `Checked Items`; search/read both openspec specification directories
-before accepting conventions.
-
-```markdown
-VERDICT: pass
-
-## Findings
-- None blocking.
-
-## Required Plan Corrections
-- None.
-
-## Checked Items
-- ...
-```
-
-Each correction names its criterion/section, gap, and exact plan change.
+Read only the canonical contract (or its indexed, hash-bound sections) and any exact
+evidence paths bound in its upstream context. Successful paired reads are the only proof that a specification was read;
+summaries do not substitute for them. A concise human-readable summary may list
+checked items and findings, but it is never a control protocol. Each requested
+change names its criterion/section, gap, and required plan change.

package/skills/frontend-plan/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: frontend-plan
+description: Use only for the tool-only frontend decision planning node.
+references:
+  - path: references/decision-contract.md
+    required: true
+    maxChars: 5200
+  - path: references/design-decisions.md
+    required: true
+    maxChars: 3400
+---
+
+# Frontend Plan
+
+Plan only the delta between frozen Contract facts and the Scout target surface.
+Do not reread task sources, Contract/Scout prose, or target files, and do not repeat
+requirements or repository discovery.
+
+Commit the smallest necessary typed decisions through the plan `record_*` tools:
+requirement coverage, component/styling choices, applicable states and interactions,
+data/Mock strategy, deviations, and dependency policy. Process a bounded requirement
+slice and record facts immediately rather than reasoning over the whole task first.
+
+The runtime owns protected skeleton fields, path/command validation, materialization,
+and final schema checks. Finish with exactly one `finalize_plan`; return no Markdown
+narrative. Record a genuine evidence gap when frozen facts are insufficient.

package/skills/frontend-plan/references/decision-contract.md

@@ -0,0 +1,37 @@
+# Frontend Plan Decision Contract
+
+## Requirement-local decisions
+
+- Cover each frozen requirement exactly once and map it to Scout-confirmed
+  implementation paths and verification target IDs.
+- Record observable state and interaction behavior, including trigger and expected
+  behavior. IDs and paths alone are not behavioral coverage.
+- One behavior target may cover multiple related requirements when one observable
+  test behavior proves them together.
+- Every non-static verification target `id` is the stable machine trace token and
+  must later appear in a real `describe` / `it` / `test` title. There is no free-form
+  `symbol` field.
+- Static targets are for project-wide commands and are traced by file and command
+  only.
+
+## Global decisions
+
+Keep route/component placement, Mock/data strategy, and dependency/deviation policy
+as explicit global decisions rather than duplicating them across each requirement.
+Use only frozen command labels and Scout-confirmed paths.
+
+For Mock/API, keep the real request path enabled by default. Select only a strategy
+allowed by the frozen task capability. Active Mock requires deterministic Mock-backed
+verification and production-default-off activation. `not-needed` requires positive
+real/no-remote evidence or records a real-integration gap.
+
+Add dependencies only when authorized. Record unsupported dependency, path, API,
+design, or verification needs as blocking evidence gaps; never invent a command or
+widen the write set.
+
+## Runtime-owned fields and terminal
+
+The runtime owns `schemaVersion`, `sourceBinding`, risk, canonical target files,
+aliases, command allowlisting, path containment, and final validation. Submit only
+editable decision facts, then call `finalize_plan` exactly once. The deterministic
+design policy materializes the canonical implementation contract.

package/skills/frontend-plan/references/design-decisions.md

@@ -0,0 +1,17 @@
+# Frontend Design Decisions
+
+Use only design evidence already committed by Scout and frozen selections from
+Contract. Do not search specification roots or nearby code from Plan.
+
+- Reuse confirmed components, variants, tokens, helpers, and state patterns unless
+  the task authorizes a new pattern.
+- Record `uiComponentChoices` per UI purpose. `purpose` is the stable coverage key
+  matching an interaction or UI state; behavior remains in the corresponding
+  expected behavior and rationale.
+- `specified` requires an exact bound OpenSpec reference. `reuse-existing` identifies
+  the proven existing component/path. Task-mandated `new` choices bind the frozen
+  source requirement/fragment so the runtime can derive the PRD citation.
+- Define applicable success, loading, empty, error, permission, disabled, boundary,
+  responsive, and accessibility behavior; use not-applicable only with a reason.
+- Record styling strategy, deviations, conflicts, and unresolved gaps explicitly.
+  Never silently replace a spec-defined component or claim unread evidence.

package/skills/frontend-review/SKILL.md

@@ -9,17 +9,25 @@ references:
 
 # Frontend Review
 
-Use for `frontend-review-pi`; read the findings guide first. Required inputs are
-original task/reference material, effective plan/design branch, implementation summary,
-and `contracts/frontend-review-context.json`. That canonical context binds the validated
-implementation contract, effective verification trace, repair assessment, optional
-`frontend-lint-assessment-v1`, and run-owned diff. The diff is authoritative.
+Use for `frontend-review-pi`; read the findings guide and capacity diagnostic first.
+Inputs are `contracts/frontend-review-context.json`, its hash-bound contract
+reference/index and diff fragments, and only source files named by that diff. Use
+indexed contract sections when recommended. Do not reopen task sources, plans,
+design-review prose, OpenSpec, or `ai_workspace/`; the bound context is authoritative.
 
-## Verdict Contract
+## Authoritative Terminal
 
-The first non-empty line must be exactly `VERDICT: pass` or
-`VERDICT: request-revision`. Any Critical/Important finding, failed or missing
-required check, forbidden write, or unmet acceptance criterion forces revision.
+Complete the review with exactly one committed typed tool call:
+
+- `approve_review` when no Critical/Important finding remains;
+- `request_review_changes` for a defect, missing required evidence, forbidden
+  write, or unmet acceptance criterion. It must include a typed `issueCategory`,
+  at least one `evidenceRef`, and non-empty findings.
+
+The typed terminal is the only authoritative outcome. Do not require or emit a
+`VERDICT:` line or response-text JSON verdict. A request for review changes ends
+this run and is handled by the recovery controller rather than a same-run repair
+branch.
 
 ## Review Scope
 
@@ -27,7 +35,7 @@ required check, forbidden write, or unmet acceptance criterion forces revision.
 - Inspect every changed file against allowed, forbidden, and approved write scope.
 - Map criteria to behavior, applicable UI states, tests, and shell evidence.
 - Review state/data flow, validation, async/error behavior, design, responsive/a11y,
-  dependencies, maintenance, and regression risk when applicable.
+  dependencies, and regression risk when applicable.
 - Inspect static, behavior, and available Mock-specific artifacts directly. For Mock
   strategies, compare the endpoint matrix, handler/fixture/adapter and consumer diff;
   require the real request as default, contract-aligned fixtures, production isolation,
@@ -38,11 +46,8 @@ required check, forbidden write, or unmet acceptance criterion forces revision.
   baseline-matched diagnostics on unchanged files, and none on writer-changed files.
   Report debt, never `lint passed`; `failed`/`unavailable` blocks. Typecheck, build,
   and test still require successful final exits.
-- Component/design claims need both knowledge-base and local openspec evidence. Query
-  the connector when available and always read task-relevant files under
-  `<repoRoot>/openspec/schemas/`, `<repoRoot>/openspec/project-specs/`, and `<repoRoot>/ai_workspace/`.
-  Connector format is TODO; never invent evidence. Only successful `read` calls are
-  observable as "已读取规范文件".
+- Evaluate component/design claims against bound evidence; do not replace it with a
+  repository-wide search or connector query.
 - Treat shell exit status as authoritative. Do not edit files.
 
 ## Evidence And Output

package/skills/frontend-review/references/review-findings.md

@@ -14,24 +14,23 @@
   `baseline-debt` only with a valid `frontend-lint-assessment-v1`; this is not a
   passed lint result. A changed-file lint diagnostic, new unmatched diagnostic,
   command drift, missing baseline, timeout, or unparseable output is Important.
-- Treat knowledge base, `openspec/schemas/`, `openspec/project-specs/`, and `ai_workspace/` as
-  parallel sources. Record connector/query/source/time plus openspec search terms and
-  matched paths/headings; label fallback or unavailable accurately.
+- Treat the design evidence already bound in the canonical review context as the
+  source of truth. Do not launch a connector query or repository-wide OpenSpec/
+  `ai_workspace` search to replace frozen evidence; label a missing bound evidence
+  reference accurately instead.
 
 ## Review Sequence
 
 1. Establish changed-file inventory and write boundaries.
-2. Compare original requirement with derived contract/constraints.
+2. Compare the bound contract with the approved constraints and cumulative diff.
 3. Map each criterion to code, states, tests, and evidence.
 4. Inspect interactions, state/data/API behavior, failure paths, and regressions.
 5. Check mock selection, contract-to-fixture mapping, activation/default path,
    handler/fixture/adapter and consumer diff, verification, production imports, and
    the real-integration gap.
-6. Check design evidence, responsive/a11y behavior, dependencies, and maintenance.
+6. Check bound design evidence, responsive/a11y behavior, dependencies, and maintenance.
 7. Classify findings and derive the verdict mechanically.
 
-Skipping either directory is Important when design compliance affects acceptance.
-
 ```text
 - [Critical|Important|Minor] path:line — Problem; impact; required correction; evidence.
 ```

package/skills/frontend-scout/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: frontend-scout
+description: Use only for read-only frontend target-surface and design-evidence scouting.
+references:
+  - path: references/scout-evidence.md
+    required: true
+    maxChars: 4200
+  - path: references/design-evidence.md
+    required: true
+    maxChars: 3600
+---
+
+# Frontend Scout
+
+Inspect only enough repository evidence to prove the target surface and applicable
+design rules. Separate facts, inferences, and unresolved gaps. Reuse the frozen
+capability context and contract selections before running bounded task-term searches.
+
+Submit findings incrementally through `record_target_surface` and
+`record_design_evidence`. A complete surface names proven entrypoints, routes or
+mounts, implementation paths, test paths, data sources, and any allowed-path
+conflicts. If ownership remains unresolved, commit `completeness=blocked` with the
+specific gaps rather than guessing.
+
+This node is read-only and does not make plan decisions.

package/skills/frontend-scout/references/design-evidence.md

@@ -0,0 +1,16 @@
+# Frontend Design Evidence
+
+Use the generation-frozen component/design capability context and cited candidate
+set. When a connector is available, query the configured knowledge base; regardless
+of its result, inspect relevant frozen OpenSpec or `ai_workspace` candidates. Search
+local specification roots only for unresolved task terms and never recursively read
+all supported files.
+
+Record evidence as `knowledge-base`, `openspec fallback`, `repository fallback`, or
+`unavailable`. Include query/search terms, paths, headings or tight line ranges,
+applied rules, and conflicts. Filename-only and unread search matches are not rules.
+
+Look for components, variants, composition, tokens, layout, responsive behavior,
+accessibility, state patterns, data/Mock conventions, deprecations, exceptions, and
+forbidden patterns. Explicit task requirements remain authoritative; report source
+conflicts instead of merging them silently.

package/skills/frontend-scout/references/scout-evidence.md

@@ -0,0 +1,23 @@
+# Frontend Scout Evidence
+
+## Target surface
+
+Prove the current frontend stack and the files that own the requested behavior:
+
+- entrypoint, route or mount;
+- page/component/style implementation paths;
+- state and data/API/Mock flow;
+- supported scripts and test entrypoints;
+- reusable components, tokens, helpers, fixtures, and assets;
+- paths discovered outside task `allowedPaths`;
+- unresolved ownership or missing evidence.
+
+Use repository-relative POSIX paths. A search hit, lockfile, fixture, or filename is
+not proof by itself. Read the relevant surrounding code or configuration and report
+the exact evidence. Do not recursively inspect unrelated directories.
+
+## Completeness
+
+Commit `complete` only when the target surface is sufficiently proven for Plan to
+reuse without repository discovery. Otherwise commit `blocked` and list every
+unresolved path or ownership question. Do not shift discovery work into Plan.