@captain_z/zsk 1.8.2 → 1.8.4

package/templates/module/frontend-module/design.md

@@ -15,6 +15,22 @@ Do not approve this design until project-level path boundaries, evidence routing
 | --- | --- | --- | --- | --- |
 | FR-001 / AC-001 |  |  |  |  |
 
+## Accepted Upstream Inputs
+
+| Source | Reviewed Revision / Evidence | Design Use |
+| --- | --- | --- |
+| `.zsk/modules/{module}/spec.md` |  | Required behavior and acceptance contract |
+| `.zsk/raws/prepare/ux/{topic}/interaction-handoff.md` | N/A or reviewed revision | Accepted UI/interaction facts only; missing behavior routes back to `preproposal` or `spec`. |
+| `.zsk/raws/prepare/design/{topic}/design-source-map.md` | N/A or reviewed revision | Visual/source evidence and gaps only; not a substitute for code design. |
+
+## Control Traceability Matrix When Triggered
+
+Use this table when the module touches auth, permissions, roles, tenancy, data access, compliance, audit, privacy, or security. If none apply, write an evidence-backed N/A rationale.
+
+| Source Rule / Spec | Subject / Actor | Action / Capability | Resource / Data | Scope | UI / API / State Behavior | Enforcement Point | AC / Scenario | Test / Evidence |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| N/A or source id |  |  |  |  |  |  |  |  |
+
 ## Design Views
 
 Use Mermaid or linked configured design-source evidence to make boundaries, flows, states, and dependencies reviewable. Keep a view N/A only with rationale.
@@ -70,9 +86,11 @@ N/A rationale or diagram:
 
 ## Decisions
 
-| Decision | Alternatives Rejected | Rationale / Evidence | Rollback / Migration Note |
-| --- | --- | --- | --- |
-|  |  |  |  |
+| ADR | Context / Requirement | Options Considered | Decision | Consequences / Risks | Rollback / Migration | Verification |
+| --- | --- | --- | --- | --- | --- | --- |
+| ADR-001 |  |  |  |  |  |  |
+
+Use `N/A` only when no architecture, interface, data-flow, storage, migration, dependency, rollback, integration, cross-team ownership, security, or permission-enforcement decision is made.
 
 ## States And Failure Modes
 
@@ -96,11 +114,15 @@ Guidelines:
 - Define auth/storage reuse before demo so Playwright can run repeatably.
 - Keep generated docs, issues, evidence, and Playwright assets inside the `.zsk` paths required by `PROJECT-CONFIG.md` and `SYSTEM-SPEC.md`.
 - Route unclear behavior back to spec instead of redesigning requirements here.
+- Do not author or repair `interaction-handoff.md` in design; update the
+  preproposal raw artifact first when interaction source facts change.
 
 ## Best-Practice Checklist
 
 - [ ] Behavior maps to files/modules/interfaces/state/data flow without changing approved requirements.
 - [ ] Design includes useful diagrams/charts for context, flow, state, data, dependency, or UX where complexity requires them; otherwise N/A rationale is explicit.
+- [ ] ADR/decision-record entries capture context, options, decision, consequences, rollback/migration, and verification for design-significant decisions.
+- [ ] Auth/permission/privacy/security/data-access scope has a control traceability matrix, or N/A cites source evidence.
 - [ ] Security/auth/privacy, migration/rollback, performance, and rollout risks are recorded when touched.
 - [ ] UI work includes accessible locator/state strategy and Playwright evidence needs.
 - [ ] Project military rules from `PROJECT-CONFIG.md` and `SYSTEM-SPEC.md` are enforced or blocked.

package/templates/module/frontend-module/proposal.md

@@ -24,6 +24,14 @@ Do not draft or pass this proposal until project-level path, source-priority, ev
 - Assumptions:
 - Open questions / blockers:
 
+## Upstream Raw Sources
+
+| Source | Reviewed Revision / Evidence | Proposal Use |
+| --- | --- | --- |
+| `.zsk/raws/prepare/product/{topic}/product-brief.md` |  | product direction / scope input |
+| `.zsk/raws/prepare/product/{topic}/roadmap.md` |  | MVP / phase / module boundary input |
+| `.zsk/raws/prepare/ux/{topic}/interaction-handoff.md` | N/A or reviewed revision | interaction source reference only; do not copy full handoff here |
+
 ## Success Criteria
 
 | Criterion | Evidence Source | Owner / Next Stage |

package/templates/module/frontend-module/spec.md

@@ -14,6 +14,13 @@ Do not freeze this spec until source-priority, conflict-routing, evidence, and s
 | ID | Requirement | Type | Source / Decision | Priority | Observable Outcome |
 | --- | --- | --- | --- | --- | --- |
 | FR-001 |  | FR |  | P0 |  |
+| NFR-001 |  | NFR |  | P0/P1/P2 |  |
+
+## Upstream Interaction Source
+
+| Source | Reviewed Revision / Evidence | Spec Impact |
+| --- | --- | --- |
+| `.zsk/raws/prepare/ux/{topic}/interaction-handoff.md` | N/A or reviewed revision | Convert accepted interaction facts into FR/NFR/AC/scenarios; route missing behavior back to preproposal/spec clarification. |
 
 ## Acceptance Criteria
 
@@ -21,6 +28,14 @@ Do not freeze this spec until source-priority, conflict-routing, evidence, and s
 | --- | --- | --- | --- |
 | AC-001 | FR-001 | Given  / When  / Then  |  |
 
+## Control Matrix When Triggered
+
+Use this table when the module touches auth, permissions, roles, tenancy, data access, compliance, audit, privacy, or security. If none apply, write an evidence-backed N/A rationale.
+
+| Source Rule | Subject / Actor | Action / Capability | Resource / Data | Scope | Expected Outcome | FR/AC / Scenario |
+| --- | --- | --- | --- | --- | --- | --- |
+| N/A or source id |  |  |  |  |  |  |
+
 ## Scenario Contracts
 
 | Scenario | User Goal | Entry | Preconditions | Observable Result | PRD/SRS / FR/AC | Automate |
@@ -32,6 +47,7 @@ Rules:
 - Define behavior and observable outcomes here.
 - Link every P0/P1 scenario back to the original PRD/SRS or accepted FR/AC.
 - Link every project-wide rule that changes behavior back to `PROJECT-CONFIG.md` or `SYSTEM-SPEC.md`.
+- Include a control matrix when auth/permission/privacy/security/data-access behavior is touched; N/A needs evidence.
 - Mark unclear or conflicting facts as blockers instead of choosing behavior silently.
 - Do not write brittle selectors in spec.
 - Mark which P0/P1 scenarios must become Playwright cases.

package/templates/module/frontend-module/tasks.md

@@ -11,18 +11,18 @@ Do not start coding until path boundaries, evidence routing, issue routing, vali
 
 ## Task Todo List
 
-- [ ] T-001:
+- [ ] 1. <task group: deliverable outcome>
   - Owner:
   - Depends on:
   - Scope / files:
   - Linked FR/AC:
   - Evidence hook:
   - Stop condition:
-  - [ ] T-001.1:
+  - [ ] 1.1 <subtask: executable step>
     - Owner:
     - Output:
     - Evidence:
-  - [ ] T-001.2:
+  - [ ] 1.2 <subtask: executable step>
     - Owner:
     - Output:
     - Evidence:
@@ -31,13 +31,27 @@ Do not start coding until path boundaries, evidence routing, issue routing, vali
 
 | Order | Task / Subtask | Depends On | Can Run In Parallel With | Blocker / Decision Needed |
 | --- | --- | --- | --- | --- |
-| 1 | T-001.1 |  |  |  |
+| 1 | 1.1 |  |  |  |
 
-## Coverage Matrix
+## Proposal / Spec / Design / ADR Alignment Matrix
+
+| Goal / FR / AC / NFR | Design Decision / ADR | Task Group | Subtask | Evidence |
+| --- | --- | --- | --- | --- |
+| FR-001 / AC-001 | ADR-001 | 1 | 1.1 |  |
+
+## FR / AC Coverage Matrix
 
 | FR/AC | Implementation Task/Subtask | Test / Scenario Task/Subtask | Docs / Issue / Evidence Task/Subtask |
 | --- | --- | --- | --- |
-| FR-001 / AC-001 | T-001.1 | T-001.2 |  |
+| FR-001 / AC-001 | 1.1 | 1.2 |  |
+
+## Control Row Task Coverage When Triggered
+
+Use this table when spec/design include auth, permission, privacy, security, tenancy, compliance, audit, or data-access control rows. If none apply, write an evidence-backed N/A rationale.
+
+| Control Row | Implementation Task | Test / Scenario Task | Docs / Issue Task | Evidence |
+| --- | --- | --- | --- | --- |
+| N/A or CTRL-001 |  |  |  |  |
 
 ## Playwright Case Tasks
 
@@ -47,8 +61,10 @@ Do not start coding until path boundaries, evidence routing, issue routing, vali
 
 Rules:
 
-- Use a Kiro-style checkbox hierarchy: task IDs for deliverables, subtask IDs for executable steps.
+- Use a Kiro-style checkbox hierarchy: `- [ ] 1. <task group>` with indented `- [ ] 1.1 <subtask>` children.
 - Every task and subtask must have owner, dependency, output, evidence hook, and stop condition.
+- Every design decision/ADR must map to task groups, subtasks, and evidence or an explicit blocker.
+- Every triggered control row must map to implementation, test/scenario, docs/issue, and evidence tasks.
 - Create Playwright skeletons under `__PLAYWRIGHT_SPECS__` before demo.
 - Create or update source-aligned tests/scenarios before implementation for testable behavior changes.
 - Tag cases as smoke/demo/verify/regression.

package/templates/project-init/.zsk/config.yaml

@@ -12,7 +12,40 @@ template:
 mode: standard
 scale: auto
 
+# Prepare source capture strategy:
+# - Register source origins under sources.prepare.<lane>.<source-id>.
+# - Prefer stable local exports or provider API/export URLs over bare browser
+#   pages when fidelity matters.
+# - Keep credentials out of config; reference env names under origin.auth or use
+#   .zsk/playwright/.auth storageState created by `zsk prepare auth`.
+# - Run `zsk prepare plan` before acquisition, `zsk prepare auth-check` for
+#   remote/private URLs, then `zsk prepare sync --source=<id> --allow-network`
+#   when acquisition is intentionally allowed.
+# - Design/Figma sources are evidence only. Pair them with
+#   .zsk/raws/prepare/ux/{topic}/interaction-handoff.md for page/module
+#   interaction details before proposal/spec/design consume them. In
+#   module-targeted preproposal runs, {topic} defaults to the module id.
 sources: {}
 
+# Example source shape:
+# sources:
+#   prepare:
+#     product:
+#       prd:
+#         type: prd
+#         origin:
+#           kind: local
+#           path: docs/PRD.md
+#         snapshot: .zsk/raws/prepare/product/prd.md
+#     design:
+#       figma-product:
+#         type: design-source
+#         origin:
+#           kind: url
+#           provider: figma
+#           url: https://www.figma.com/file/<file-id>/<name>
+#           exportPath: exports/figma-product.json
+#         snapshot: .zsk/raws/prepare/design/figma-product/source.md
+
 customize:
   roles: .zsk/roles.yaml

package/templates/project-init/.zsk/docs/PROJECT-CONFIG.md

@@ -53,6 +53,49 @@ Every module stage document is a handoff contract:
 
 If a document cannot answer its stage questions, stop and record the missing source, decision, blocker, or issue instead of filling the template.
 
+## Preproposal Raw Artifacts
+
+`preproposal` may create living raw artifacts under `.zsk/raws/prepare/**` when a
+brief request lacks reviewed product, roadmap, UX, design-source, or source
+readiness material.
+
+- Product direction and roadmap seeds live under `.zsk/raws/prepare/product/**`.
+- UX readiness and interaction handoff live under `.zsk/raws/prepare/ux/**`.
+- Design-source needs and provider source maps live under `.zsk/raws/prepare/design/**`.
+- Checkpoint review evidence lives under `.zsk/evidence/preproposal/{run}/`.
+
+Module `proposal.md`, `spec.md`, `design.md`, and `tasks.md` should reference
+reviewed revisions from these raw artifacts instead of copying their full
+contents. A later interaction change updates the raw artifact first, then routes
+impact to the affected module stage.
+
+## Prepare Capture Strategy
+
+`prepare` records where facts come from and whether they can be acquired. It is
+not a requirement author, interaction designer, code designer, or task planner.
+
+Use this order for source capture:
+
+1. Register stable origins in `.zsk/config.yaml#sources`.
+2. Run `zsk prepare plan` to classify ready, stale, blocked, and ambiguous
+   sources before writing snapshots.
+3. Run `zsk prepare auth-check` for private URLs so credentials are verified
+   without writing source content.
+4. Run `zsk prepare sync` for local/provider/export sources, adding
+   `--allow-network`, `--browser`, and `--auth-state` only when that acquisition
+   is intentional.
+5. Review `.zsk/evidence/prepare/{run}/adapter-results/` and
+   `downstream-impact.md` before downstream stages consume the snapshot.
+
+For Figma or similar design tools, prefer provider API/export payloads, raw node
+exports, screenshots/assets, and local design-source maps over a bare page URL.
+Browser-rendered capture is useful evidence, but it is not complete interaction
+truth. Pair design snapshots with a reviewed
+`.zsk/raws/prepare/ux/{topic}/interaction-handoff.md` when page/module behavior,
+states, empty/error/loading flows, or accessibility rules are needed. For
+module-targeted preproposal work, `{topic}` defaults to the module id unless a
+narrower page/frame split is justified in the raw artifact.
+
 ## Maintenance Checklist
 
 - Update `.zsk/config.yaml` when paths, tools, or source origins change.

package/templates/project-init/.zsk/docs/SYSTEM-SPEC.md

@@ -20,6 +20,7 @@ Agents must use the smallest sufficient lane: read local sources first, run dete
 - `paths.docs` stores project-level docs only.
 - `paths.modules` stores module source-of-truth docs.
 - `paths.raws` stores immutable shared source snapshots and manually provided fact sources.
+- `preproposal` may add candidate/generated product, roadmap, UX, and design-source readiness resources under `paths.raws` only when provenance, assumptions, review checkpoint status, and blockers are explicit. When a target module is specified, raw topics default to the module id and must name any narrower page/frame split rationale.
 - Module `_issues` stores module-specific actionable issue records; `paths.issues` is created on demand only for shared/global indexes or cross-module issues.
 - Module `_evidence` stores module-specific runtime evidence and verification artifacts; `paths.evidence` is created on demand only for shared/global evidence.
 - Module `_playwright` stores module-specific Playwright specs, plans, auth state, results, reports, and execution records; `paths.playwright` is created on demand only for shared Playwright assets.
@@ -46,6 +47,7 @@ ZSK stage documents are decision artifacts. They are complete only when the next
 | Stage | Document Mode | Must Prove |
 | --- | --- | --- |
 | `prepare` | Evidence report | Source origins, freshness, conflicts, and raw snapshot paths are known before planning. |
+| `preproposal` | Decision brief | Product direction, MVP/phase split, UX/design readiness, assumptions, risks, and readiness review are complete before proposal when no reviewed source pack exists. |
 | `proposal` | Decision brief | Problem, user/business outcome, scope, non-goals, risks, and success criteria are explicit. |
 | `spec` | Behavior contract | FR/NFR, scenarios, edge cases, and acceptance criteria are observable and source-linked. |
 | `design` | Implementation contract | Behavior maps to files/modules/interfaces/state/data flow, with risks and verification strategy. |
@@ -56,4 +58,24 @@ ZSK stage documents are decision artifacts. They are complete only when the next
 | `ready` | Verification handoff | Fixed issues, AC, evidence, replay steps, version, and residual risks are mapped. |
 | `verify` | Independent evidence | The ready claim is replayed with fresh evidence and pass/fail issue status updates. |
 
-Each stage document must separate facts, decisions, assumptions, open questions, evidence, and next action. Do not leave template filler, untraceable "best practice" claims, vague tasks, or unresolved contradictions in a stage artifact.
+Each stage document must separate facts, decisions, assumptions, open questions,
+evidence, and next action. Do not leave template filler, untraceable "best
+practice" claims, vague tasks, or unresolved contradictions in a stage artifact.
+Each stage challenge must also align terminology against project context,
+configured raw sources, existing artifact IDs, and implementation names when
+implementation-facing work is touched. Conflicting, overloaded, stale, or
+translated terms must be recorded as a blocker or repaired by the owning stage.
+
+## Lifecycle Ownership
+
+| Artifact / Decision | Owning Stage | Notes |
+| --- | --- | --- |
+| Source origins, acquisition plan, auth readiness, raw snapshots, manifest/index, adapter results, downstream impact evidence | `prepare` | Capture-only stage. It may classify sources as ready/stale/blocked/gap, but it does not invent requirements, interactions, architecture, or tasks. |
+| Product direction, roadmap, UX readiness, interaction handoff, design-source map | `preproposal` | Living raw artifacts. They may change after initial review, but each revision records source, status, impact, and affected downstream stages. |
+| Scope, non-goals, success criteria, high-level risks | `proposal` | Freezes the smallest useful problem/scope boundary before behavior is specified. |
+| FR, NFR, acceptance criteria, scenarios, edge cases | `spec` | Creates observable behavior contracts from proposal/source evidence. Missing quality targets remain `未指定` instead of invented. |
+| ADR / decision records for architecture, interfaces, state/data flow, storage, migration, dependency, rollback, integration, security, permission, privacy, or public API decisions | `design` | Required only for design-significant decisions. N/A must cite why no such decision exists. |
+| Proposal/spec/design/ADR alignment and executable work | `task` | Preserves FR/AC/NFR/ADR traceability into task groups, subtasks, evidence, and stop conditions. |
+
+Downstream stages consume reviewed upstream revisions. They may report gaps, but
+must not silently rewrite another stage's source of truth.

package/templates/project-init/.zsk/raws/index.md

@@ -5,11 +5,30 @@ Immutable fact sources for this project. Generated and refreshed by `zsk prep`.
 Active source snapshots should be organized by prepare responsibility lane:
 
 - `prepare/product/` for SRS, PRD, business process, acceptance semantics, and work items.
+- `prepare/product/{topic}/product-brief.md` and `roadmap.md` for preproposal-generated product direction and MVP/phase decomposition after checkpoint review.
 - `prepare/backend/` for backend repositories, API contracts, data model, and service-boundary evidence.
 - `prepare/design/` for design/prototype sources, screen maps, and visual assets.
+- `prepare/design/{topic}/design-source-needs.md` for preproposal design-source readiness gaps after checkpoint review.
+- `prepare/design/{topic}/design-source-map.md` for provider-backed design source coverage and missing Figma/prototype metadata.
 - `prepare/ux/` for user flows, interaction notes, IA, and usability evidence.
+- `prepare/ux/{topic}/ux-readiness.md` for preproposal journey/flow/IA/readiness seeds after checkpoint review.
+- `prepare/ux/{topic}/interaction-handoff.md` for sourced interaction matrices, state coverage, accessibility contract, and unresolved interaction gaps. For module-targeted preproposal work, `{topic}` defaults to the module id.
 - `prepare/qa/` for test cases, acceptance scenarios, regression matrices, and QA evidence.
 
+Interaction handoff files are living raw artifacts owned by `preproposal`, not
+inline sections of module `proposal.md` or `design.md`. Downstream module stages
+should reference a reviewed revision, for example:
+
+```md
+Interaction source:
+- `.zsk/raws/prepare/ux/{topic}/interaction-handoff.md`
+- Accepted revision: <review evidence or commit/date>
+```
+
+If later UX changes alter scope or behavior, revise the raw artifact first,
+record source/status/impact, then route affected module stages back through
+`proposal`, `spec`, `design`, or `task` as needed.
+
 | Provider | Type | Status | Snapshot / Origin |
 | --- | --- | --- | --- |
 |  |  |  |  |

package/templates/project-init/.zsk/raws/prepare/design/index.md

@@ -1,3 +1,21 @@
 # Design Sources
 
 Design handoff files, wireframes, prototype exports, visual assets, design tokens, and platform snapshots.
+
+Use `prepare/design/{topic}/design-source-map.md` for provider-backed design
+sources such as Figma, MasterGo, exports, screenshots, and assets.
+
+Rules:
+
+- Preserve provider URL, file/page/frame/node ids, capture method, raw payload,
+  screenshots/assets, capture time, and tool/auth limits.
+- Record prototype links, annotations, variables/tokens, components, variants,
+  and missing source data when available.
+- Treat design files as source evidence, not complete interaction truth.
+- Pair source maps with `prepare/ux/{topic}/interaction-handoff.md` when visual
+  sources need page/module interaction detail.
+- For module-targeted preproposal work, `{topic}` defaults to the module id so
+  the design-source map and interaction handoff can be consumed by the same
+  module proposal/spec/design chain.
+- Code design remains owned by module `design.md`; this lane provides source
+  evidence and gaps only.

package/templates/project-init/.zsk/raws/prepare/index.md

@@ -2,3 +2,36 @@
 
 Reusable source snapshots for prepare. Iterations and releases should reference these snapshots instead of copying source content.
 
+## Responsibility
+
+`prepare` is the source acquisition and evidence stage. It owns:
+
+- source origin registration from `.zsk/config.yaml#sources`;
+- repository inventory and draft source discovery;
+- acquisition planning, blocked-source questions, and correspondence prompts;
+- auth preflight and reusable Playwright storageState helpers;
+- raw snapshot materialization through local, provider, URL, browser, or
+  metadata-only strategies;
+- `.zsk/raws/manifest.json`, raw indexes, adapter results, and downstream impact
+  evidence.
+
+`prepare` does not own product decisions, formal FR/NFR, interaction decisions,
+code design, or task planning. If a source is missing or private, preserve the
+previous snapshot when present, write a blocked/gap artifact, and route the
+missing decision to the owning stage.
+
+## Capture Strategy
+
+Use the least lossy acquisition method that is explicit and repeatable:
+
+| Source Kind | Preferred Strategy | Notes |
+| --- | --- | --- |
+| Local docs/contracts/exports | `origin.kind: local` + `zsk prepare sync` | Best default for PRD, API, QA, Figma JSON exports, screenshots, and manually reviewed handoffs. |
+| Provider APIs | `origin.provider` + API/export URL + `--allow-network` | Use Confluence/Jira/GitLab/design-source adapters when provider payloads are available. |
+| Private web pages | `zsk prepare auth-check`, then `zsk prepare sync --browser --auth-state ... --allow-network` | Browser capture is fallback evidence, not a replacement for provider exports. |
+| Repository roots | metadata-only snapshot | Do not crawl broad repositories; configure concrete contracts/files instead. |
+| Figma/design URLs | provider export or local raw payload first; browser URL only as fallback | Pair with `prepare/ux/{topic}/interaction-handoff.md` for interaction details. |
+
+Record incomplete provider coverage as a source gap. A successful prepare run is
+allowed to say "blocked" or "needs confirmation"; that is expected behavior, not
+a silent failure.

package/templates/project-init/.zsk/raws/prepare/ux/index.md

@@ -1,3 +1,22 @@
 # UX Sources
 
 User flows, interaction maps, screen behavior notes, usability findings, and experience research artifacts.
+
+Use `prepare/ux/{topic}/interaction-handoff.md` when UI, UX, or design-source
+interaction needs clarification before formal proposal/spec/design work. When
+the brief targets a module, `{topic}` defaults to the module id.
+
+Rules:
+
+- `preproposal` owns this file as a living source artifact.
+- Generate an AI brief from available Figma/design/source/code evidence before
+  asking humans to fill gaps.
+- Separate sourced facts, accepted decisions, inferred assumptions, missing
+  details, recommended answers, and human confirmation status.
+- Record revisions and impact. Downstream module docs consume only reviewed or
+  accepted revisions.
+- For module-targeted work, name the target module, module path, reviewed module
+  artifacts, scope boundary, terminology alignment, and any page/frame split
+  rationale in the interaction handoff.
+- Do not use this lane for final code design, formal FR/NFR, or task execution
+  planning.

package/templates/project-init/.zsk/roles.yaml

@@ -13,21 +13,21 @@ roles:
 
   product-owner:
     subagentType: analyst
-    stages: [prepare, proposal, spec, review, verify, acceptance]
+    stages: [prepare, preproposal, proposal, spec, review, verify, acceptance]
     lanes: [product, pm, requirement, requirements, srs, prd]
     activation: when product or requirement evidence is configured or in scope
     reason: Interpret product scope, requirement semantics, priorities, and acceptance gaps.
 
   business-analyst:
     subagentType: analyst
-    stages: [proposal, spec]
+    stages: [preproposal, proposal, spec]
     lanes: [business, domain, process, rules]
     activation: when domain process or business-rule evidence is configured or in scope
     reason: Map domain process, terminology, business rules, and edge cases.
 
   architect:
     subagentType: architect
-    stages: [proposal, spec, design, review]
+    stages: [preproposal, proposal, spec, design, review]
     activation: when architecture, API, system-boundary, or dependency decisions are in scope
     reason: Review system boundaries, module relationships, contracts, and technical risks.
 
@@ -40,28 +40,28 @@ roles:
 
   frontend-engineer:
     subagentType: executor
-    stages: [design]
+    stages: [preproposal, design]
     lanes: [frontend, web, client, mobile]
     activation: when frontend implementation, routing, state, or UI integration is in scope
-    reason: Map UI implementation, routing, state, and component integration risk.
+    reason: Map existing UI implementation surfaces, routing, state, candidate page/module-to-code mapping, and component integration risk.
 
   design-specialist:
     subagentType: designer
-    stages: [prepare, design]
+    stages: [prepare, preproposal]
     lanes: [design, ui, visual]
     activation: when design, UI, visual, prototype, or asset sources are configured
     reason: Inspect design assets, screens, visual states, and design-source gaps.
 
   ux-specialist:
     subagentType: designer
-    stages: [prepare]
+    stages: [prepare, preproposal]
     lanes: [ux, ue, user-experience, research]
     activation: when UX, UE, user-flow, or research sources are configured
     reason: Inspect user flows, interaction constraints, and usability ambiguity.
 
   qa-engineer:
     subagentType: test-engineer
-    stages: [prepare, spec, task, coding, review, verify]
+    stages: [prepare, preproposal, spec, task, coding, fix, review, verify]
     lanes: [qa, test, testing, quality]
     activation: when QA, test, acceptance, or quality evidence is configured or in scope
     reason: Connect requirements to acceptance scenarios, test coverage, and verification evidence.
@@ -88,19 +88,19 @@ roles:
 
   researcher:
     subagentType: researcher
-    stages: [prepare]
+    stages: [prepare, preproposal]
     activation: optional when current official or external evidence is required
     reason: Collect official/current external references only when configured local sources are insufficient.
 
   planner:
     subagentType: planner
-    stages: [task]
+    stages: [preproposal, task]
     activation: when task sequencing, dependencies, and risk flags are in scope
     reason: Sequence implementation tasks, dependencies, ownership, and evidence hooks.
 
   executor:
     subagentType: executor
-    stages: [task, coding]
+    stages: [task, coding, fix]
     activation: when implementation ownership, write scope, or scoped code changes are in scope
     reason: Implement or estimate scoped code ownership and write boundaries.