create-yss-spec 2.1.9 → 2.1.11

package/template/.cursor/skills/yss-product-lifecycle/references/orchestration-contract.yaml

@@ -0,0 +1,521 @@
+schema_version: 1
+supported_state_schema_versions: [1]
+
+implementation_path_policy:
+  harness_layout:
+    backend: apps/backend/<project>/
+    frontend: apps/frontend/<project>/
+  container_roots: [apps/backend/, apps/frontend/]
+  forbidden_roots: [app/backend/, app/frontend/]
+  container_roots_are_projects: false
+  external_repository_uses_native_root: true
+
+review_verification:
+  low_medium_combined_independent_executor: true
+  implementer_must_be_separate: true
+  split_when: [new_module, high_risk, responsibility_conflict, dual_control_required]
+
+checkpoint_policy:
+  strategy: consolidated
+  flush_on: [human_pause, handoff, implementation_entry, merge, release]
+  flush_immediately_on: [blocked, responsibility_changed, asset_approval]
+  preserve_stage_causality: true
+  required_stage_trace_fields: [stage, upstream_refs, artifact_refs, gate_decisions, downstream_impacts]
+
+modes:
+  route: read_only
+  audit: read_only
+  orchestrate: bounded_write
+  resume: rebuild_then_bounded_write
+
+# 有效的 YSS 仓库必须先由生命周期编排器接管入口；Matt flow 只负责选择工作方式。
+entry_routing:
+  manifest: yss-project.yaml
+  valid_modes: [template-source, project-instance]
+  invalid_manifest:
+    action: migration-check
+  direct_matt_entry:
+    skill: ask-matt
+    delegate_to: yss-product-lifecycle
+    requires_valid_manifest: true
+    action: navigate-only
+    lifecycle_state_mutation: forbidden
+    lifecycle_artifact_write: forbidden
+    return_to_orchestrator: required
+  formal_user_entry:
+    skills: [setup-matt-pocock-skills, grill-with-docs, to-spec, to-tickets, implement]
+    action: lifecycle-validate-and-accept
+    lifecycle_artifact_write: conditional-explicit-user-entry
+    return_to_orchestrator: required
+  template_source:
+    route: template-maintenance
+    forbidden_artifacts: [product-spec, prototype, openapi, vertical-slice-tickets]
+    forbidden_flows: [to-spec, to-tickets, implement, release, retrospective]
+    on_forbidden_flow: blocked
+    block_reason: template-source-product-artifact-forbidden
+
+# 旧 Matt Skill Result 只用于兼容读取；所有生命周期新输出使用 Workflow Execution Result。
+matt_skill_result:
+  status: compatibility-read-only
+  may_influence_routing: false
+  normalize_to: workflow-execution-result-v1
+  schema_version: 1
+  result_values: [completed, blocked, needs-human, failed]
+  required: [result, skill, evidence_refs, changed_artifacts, new_impacts, stale_candidates, next_route, blocking_signals]
+  blocking_signals: [drift, new_impacts, violation, missing_evidence, stale_candidates]
+  completed_requires_empty: [new_impacts, stale_candidates]
+  completed_requires_non_empty: [evidence_refs]
+  completed_requires_readable_evidence_refs: true
+  evidence_ref_validation: readable-or-resolvable
+  completed_requires_no_blocking_signals: true
+  router_status_mapping:
+    draft: completed
+    blocked: blocked
+    ready-for-lifecycle-review: needs-human
+
+workflow_execution_result:
+  canonical_output_schema: workflow-execution-result-v1
+  accepted_input_schemas: [workflow-execution-result-v1]
+  legacy:
+    matt-skill-result-v1:
+      status: compatibility-read-only
+      may_influence_routing: false
+      normalize_to: workflow-execution-result-v1
+      removal_target: schema_version_2
+  result_values: [completed, blocked, needs-human, failed]
+  required: [result_schema, work_unit, workflow_reference, result, evidence_refs, changed_artifacts, new_impacts, stale_candidates, next_route, blocking_signals]
+  blocking_signals: [drift, new_impacts, violation, missing_evidence, stale_candidates]
+  completed_requires_empty: [new_impacts, stale_candidates]
+  completed_requires_non_empty: [evidence_refs]
+  completed_requires_readable_evidence_refs: true
+  evidence_ref_validation: readable-or-resolvable
+  completed_requires_no_blocking_signals: true
+  workflow_reference:
+    required: [source, skill, invocation_mode]
+    allowed_sources: [yss-product-lifecycle, mattpocock/skills]
+
+# Matt user-invoked skills remain explicit user entry points. Lifecycle work units
+# may prepare, validate and accept their results, but cannot invoke them or create
+# their formal artifacts on their behalf.
+matt_invocation_boundary:
+  user_invoked_skills: [ask-matt, grill-me, grill-with-docs, handoff, implement, improve-codebase-architecture, loop-me, setup-matt-pocock-skills, setup-ts-deep-modules, teach, to-questionnaire, to-spec, to-tickets, triage, wait-what, wayfinder, writing-beats, writing-fragments, writing-shape]
+  lifecycle_managed_user_entries: [setup-matt-pocock-skills, grill-with-docs, to-spec, to-tickets, implement]
+  model_invoked_skills: [code-review, codebase-design, diagnosing-bugs, domain-modeling, grilling, migrate-to-shoehorn, prototype, research, resolving-merge-conflicts, scaffold-exercises, setup-pre-commit, tdd, writing-for-agents]
+  lifecycle_allowed_model_invoked_skills: [code-review, codebase-design, diagnosing-bugs, domain-modeling, grilling, prototype, research, tdd]
+  lifecycle_may_invoke_user_invoked: false
+  formal_artifact_owner: explicit-user-entry
+  continuous_orchestration: compatibility-prepare-and-validate-only
+  direct_user_entry: lifecycle-validate-and-accept
+
+skill_source_contract:
+  lock_version: 3
+  source_revisions_required: [mattpocock/skills]
+  adaptation_ref_required_when_effective_diff: true
+  retired_shared_skills: [batch-grill-me, product-design-prototype, yss-dictionary, yss-jdbc, yss-log, yss-taskflow, yss-backend-scaffold-application, yss-backend-scaffold-domain, yss-backend-scaffold-infrastructure, yss-backend-scaffold-web]
+
+# 生命周期默认走原生工作单元；Matt user-invoked skill 仅保留为兼容入口。
+lifecycle_native_entries:
+  default_entry: yss-product-lifecycle
+  formal_artifact_owner: yss-product-lifecycle
+  user_confirmation_required_at: [spec-baseline, prototype-confirmation, openapi-freeze, merge-or-release]
+  compatibility_entries:
+    to-spec: lifecycle-validate-and-accept
+    to-tickets: lifecycle-validate-and-accept
+    implement: lifecycle-validate-and-accept
+
+work_unit_routes:
+  work-unit.discovery-opportunity:
+    native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    skills: [competitive-intelligence, research]
+    route_by: {market_or_competitor_fact: competitive-intelligence, technical_or_standard_fact: research, no_external_fact: yss-product-lifecycle}
+  work-unit.discovery-requirements:
+    native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    skills: [grilling, domain-modeling]
+  work-unit.spec-synthesis:
+    native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    compatibility: {source: mattpocock/skills, skill: to-spec, invocation_mode: reference, formal_artifact_owner: explicit-user-entry}
+    skills: [domain-modeling]
+    human_gate: spec-baseline
+  work-unit.prototype-design:
+    native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    skills: [yss-design-system, yss-prototype-stage, product-design:index]
+    human_gate: prototype-confirmation
+  work-unit.technical-analysis:
+    native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    skills: [yss-openapi-governance, yss-openapi-draft-review, codebase-design, implementation-repo-onboarding, yss-router]
+    human_gate: openapi-freeze_if_api_impact
+  work-unit.ticket-decomposition:
+    native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    compatibility: {source: mattpocock/skills, skill: to-tickets, invocation_mode: reference, formal_artifact_owner: explicit-user-entry}
+    skills: [yss-router]
+  work-unit.slice-implementation:
+    native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    compatibility: {source: mattpocock/skills, skill: implement, invocation_mode: reference, formal_artifact_owner: explicit-user-entry}
+    skills: [tdd, yss-router, yss-ui, yss-page-module-development]
+  work-unit.frontend-implementation-verification:
+    native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    skills: [yss-ui, yss-design-system, code-review]
+    applies_when: ui_impact
+  work-unit.code-review:
+    native: {source: yss-product-lifecycle, skill: code-review, invocation_mode: model-invoked}
+    skills: [code-review]
+  work-unit.release-and-retrospective:
+    native: {source: yss-product-lifecycle, skill: yss-product-lifecycle, invocation_mode: model-invoked}
+    skills: [yss-product-lifecycle]
+    human_gate: merge_or_release
+
+compatibility_flow_preconditions:
+  to-spec:
+    required: [grill_exit, no_unresolved_runnable_blocker]
+    evidence: [user_problem, mvp_and_non_goals, success_criteria, test_seam, terminology_review]
+    output_role: ready-for-human
+  to-tickets:
+    required: [openapi_freeze_or_no_api_impact, required_gates_satisfied, vertical_slice_scope, blocking_edges]
+    output: vertical-slice-tickets
+    output_role: ready-for-human
+  implement:
+    required: [ready_for_agent, slice_contract_approved, slice_contract_persisted, slice_contract_current_version, build_architecture_checklist, implementation_repo, implementation_branch, ci, verification_commands, rollback_point, backend_slice_contract_if_applicable, backend_scaffold_policy_satisfied, frontend_implementation_plan_if_ui_impact]
+    applies_to_single_session: true
+
+grill_exit:
+  required: [frontier_empty, facts_resolved_or_routed, decisions_confirmed, shared_understanding_confirmed, no_unresolved_runnable_blocker]
+  facts_resolved_or_routed:
+    technical_fact: research
+    runnable_question: handoff-prototype-handoff
+    external_decision: external-input-required
+  user_confirmation_required: true
+  output: discovery-evidence
+
+ticket_role_transition:
+  yss_active:
+    to_tickets_initial_role: ready-for-human
+    promotion_owner: yss-product-lifecycle
+    promoted_role: ready-for-agent
+    promotion_requires: ready_for_agent
+
+review_input:
+  schema_version: 1
+  required: [review_mode, review_base_ref, implementation_candidate_ref, candidate_snapshot_ref, candidate_digest, spec_ref, ticket_ref, slice_contract_ref, build_architecture_checklist_ref, yss_execution_result_refs]
+  nullable: [spec_ref]
+  axes: [standards, spec, ui_fidelity_if_ui_impact]
+  repair_invalidates_candidate: true
+  repair_action: recapture_candidate_and_rerun_all_axes
+  modes: [committed, worktree]
+  committed:
+    candidate_ref: HEAD
+    diff_scope: merge-base-to-head
+  worktree:
+    candidate_ref: working-tree
+    diff_scope: merge-base-to-working-tree
+    required_coverage: [committed, staged, unstaged, untracked]
+    tracked_diff_command: git diff --no-ext-diff --binary --full-index <merge-base>
+    untracked_inventory_command: git ls-files -z --others --exclude-standard
+    untracked_files_encoding: nul-delimited-raw-path-bytes
+    untracked_diff_command: git diff --no-index --no-ext-diff --binary --full-index -- /dev/null <path>
+    capture_once: true
+    verify_unchanged_after_review: true
+  manifest_required_by_mode:
+    committed: [merge_base, tracked_diff_command, commit_list_command]
+    worktree: [merge_base, tracked_diff_command, untracked_inventory_command, untracked_diff_command, untracked_files, commit_list_command]
+  snapshot:
+    immutable: true
+    protocol: yss-worktree-candidate-v1
+    digest_algorithm: sha256
+    digest_framing: length-prefixed-path-and-bytes
+    path_order: bytewise
+    path_encoding: raw-bytes
+    length_encoding: uint64-big-endian
+    header_ascii: YSS-WORKTREE-CANDIDATE-V1
+    terminator_byte: "0x00"
+    tracked_record:
+      type_byte: "0x54"
+      fields: [type_byte, uint64be_content_length, binary_diff_bytes]
+      source: tracked_diff_command_stdout
+    untracked_record:
+      type_byte: "0x55"
+      fields: [type_byte, uint64be_path_length, raw_path_bytes, uint32be_file_mode, entry_kind_byte, uint64be_content_length, content_bytes]
+      order: bytewise-raw-path
+      entry_kinds: {regular: "0x52", symlink: "0x4c"}
+      regular_content_source: file_bytes
+      symlink_content_source: link_target_bytes
+    unsupported_entry_action: blocked
+    snapshot_artifact:
+      identity: candidate_digest
+      required: [candidate-manifest.yaml, tracked.diff, untracked/]
+      access: immutable-read-only
+    on_digest_change: blocked
+    completion_requires_current_digest: true
+
+git_authorization:
+  natural_language_intent_is_authorization: false
+  commit:
+    requires_explicit_user_authorization: true
+    required: [commit_authorized, commit_scope, commit_authorization_ref]
+    authorized_value: true
+    non_empty: [commit_scope, commit_authorization_ref]
+    unauthorized_action: checkpoint-only
+  push:
+    requires_explicit_user_authorization: true
+    required: [push_authorized, push_scope, push_authorization_ref]
+    authorized_value: true
+    non_empty: [push_scope, push_authorization_ref]
+    unauthorized_action: checkpoint-only
+
+seam_deferred_required: [risk, owner, follow_up_ticket, verification_plan, target_version_or_release_date]
+
+backend_scaffold:
+  applies_when: [backend_impact]
+  scaffold_statuses: [existing, required, initialized]
+  required_status: required
+  sequence:
+    after: [prototype_review, prototype_verification, antd_cli_verification, browser_verification, prototype_confirmation, engineering_baseline]
+    before_generator: [yss-router-scaffold-contract, lifecycle-approve-scaffold-contract]
+    before: [business_code_generation, implement]
+  generator_skill: yss-ddd-scaffold-generator
+  baseline_skill: yss-backend-scaffold-parent
+  tdd_mode: controlled-generation
+  contract_schema:
+    schema_version: 1
+    required: [contract_id, contract_version, slice_id, status, router_draft_ref, lifecycle_approval_ref, persisted_ref, current_version, implementation_repository, backend_repository, scaffold_status, target_git_url_or_output_dir, allowed_write_paths, expected_evidence_files, verification_commands, approval, work_unit, overwrite_policy]
+    status_by_owner:
+      router: [draft, ready-for-lifecycle-review, blocked]
+      lifecycle: [approved, stale, blocked]
+    approval:
+      required: [approval_ref, approver, persisted_ref, current_version]
+    overwrite_policy:
+      required: [force_allowed, overwrite_scope, rollback_ref]
+  required_inputs: [implementation_repository, backend_repository, scaffold_status, scaffold_target_confirmed, target_git_url_or_output_dir, project_name, base_package, database, scaffold_contract_file, scaffold_contract_draft, scaffold_contract_id, scaffold_contract_version, scaffold_contract_status, scaffold_contract_approved, scaffold_contract_router_draft_ref, scaffold_contract_lifecycle_approval_ref, scaffold_contract_persisted, scaffold_contract_persisted_ref, scaffold_contract_current_version]
+  required_evidence: [generator_inputs, expected_files, scaffold_generation_manifest, generated_project_structure, generation_execution_result, verification_execution_result, ./mvnw_validate, ./mvnw_test, ./mvnw_package, yss_skill_execution_result]
+  generation_options:
+    with_example: false
+    force: forbidden-by-default
+    force_requires: [contract_file, contract_id, contract_version, approval_ref, router_draft_ref, persisted_ref, overwrite_scope, rollback_ref]
+  forbidden_generation: [business_rules, state_machine, permission, transaction, complex_query, error_mapping, user_visible_behavior, business_example_crud, unapproved_force_overwrite]
+  after_generation: [yss-backend-scaffold-parent, yss-router]
+  existing_or_initialized: [baseline_evidence, wrapper_verification, yss_router_contract_recompile]
+  verification:
+    commands: ["./mvnw validate", "./mvnw test", "./mvnw package"]
+    requires_execution: true
+    printed_commands_are_not_evidence: true
+    evidence: [command, exit_code, duration_ms, stdout_ref, stderr_ref, executed_at]
+    failure_action: blocked
+  failure_action: blocked
+
+scaffold_work_unit_policy:
+  applies_to: [scaffold_generator_output]
+  scope: pre_business_code_generation
+  required: [approved_scaffold_contract, primary_yss_skill, allowed_write_paths, expected_evidence_files, verification_commands]
+  controlled_generation:
+    allowed_for: [project_scaffold, pom, mechanical_config, wrapper]
+    forbidden_when: [business_behavior, business_fields, business_state, permission, transaction, complex_query, error_mapping, business_example_crud]
+  on_violation: blocked
+
+post_scaffold_generated_code_policy:
+  applies_to: [post_scaffold_backend_code]
+  scope: post_scaffold_generated_code
+  required: [approved_persisted_current_slice_contract, primary_yss_skill, dependency_closure, allowed_write_paths, expected_evidence_files, yss_skill_execution_result]
+  business_behavior:
+    tdd_mode: behavior-tdd
+    impacts: [domain-rule, state-machine, transaction, permission, complex-query, error-mapping, user-visible-behavior]
+  controlled_generation:
+    allowed_for: [dto_boilerplate, po_boilerplate, mapstruct_generated, frozen_openapi_client, mechanical_config]
+    forbidden_when: [business_behavior, business_fields, business_state, permission, transaction, complex_query, error_mapping, business_example_crud]
+  on_violation: blocked
+
+tracker:
+  allowed_platforms: [local-markdown, github, gitlab]
+  default_platform: local-markdown
+  selection_precedence: [persisted_project_configuration, explicit_user_choice, template_default]
+  remote_origin_role: code_host_only
+  no_automatic_cross_platform_switch: true
+  local_markdown:
+    root: docs/.scratch
+    legacy_roots: [.scratch, docs/requirements/tickets]
+    feature_layout: [map.md, discovery, spec.md, spec-delta, parent-ticket.md, design, api, architecture, gates, verification, issues]
+    primary_sync: local
+    remote_ticket_required: false
+    remote_mirror: optional
+    default_remote_mirror: false
+  remote_platforms:
+    primary_sync: remote
+    remote_ticket_required: true
+    unavailable_fallback_root: docs/.scratch
+    unavailable_fallback_marker: pending-publication
+    unavailable_fallback_record: parent-ticket.md
+    unavailable_fallback_fields: [tracker, publication, pending_publication_to]
+
+setup_readiness:
+  evaluation: once_per_task
+  recheck_when: [tracker_changed, remote_changed, labels_changed, configuration_changed]
+  missing_action: needs-human
+  requested_skill: setup-matt-pocock-skills
+  resume_route: setup-readiness
+  preserves: [lifecycle.status, gate.status, ticket.role]
+  lifecycle_may_invoke_setup: false
+  legacy_artifacts_detected:
+    action: migration-check
+    setup: forbidden
+    write: paused
+  states: [ready, missing, conflict, degraded, not-applicable]
+  evidence: [platform, label_check, domain_layout, artifact_root, migration_ref]
+  semantics:
+    ready: [tracker_compatible, labels_verified, domain_layout_verified, artifact_root_verified]
+    missing: [required_configuration_absent, legacy_artifacts_detected_requires_migration]
+    conflict: [persistent_configuration_or_tracker_conflict, canonical_and_legacy_artifacts]
+    degraded: [target_platform_unavailable]
+    not-applicable: [template_source_validate_only]
+  template_source:
+    action: validate-only
+
+lifecycle_owned_work_units: [release, retrospective]
+lifecycle_work_unit_requirements:
+  release: [fresh_verification, release_or_rollback_evidence, independent_review, all_triggered_gates_approved_or_not_applicable]
+  retrospective: [fresh_verification, retrospective_record, governance_reflow_decision]
+
+release_readiness:
+  required: [fresh_verification, release_or_rollback_evidence, independent_review, all_triggered_gates_approved_or_not_applicable]
+  conditional:
+    ui_impact: [gate.frontend-implementation-verified, evidence.frontend-implementation-verification]
+  blocked_when: [triggered_gate_blocked, triggered_gate_stale, triggered_gate_not_evaluated, missing_evidence]
+
+wayfinder_completion:
+  required: [no_open_children, no_open_blocked_or_claimed_children, no_fog, destination_clear]
+
+ready_for_agent:
+  required: [gates_satisfied, no_stale_artifacts, blockers_closed, implementation_context_ready, implementation_repo, implementation_branch, ci, verification_commands, rollback_point, slice_contract_approved, slice_contract_persisted, slice_contract_current_version, build_architecture_checklist, backend_slice_contract_if_applicable, backend_scaffold_policy_satisfied, frontend_implementation_plan_if_ui_impact]
+
+frontend_implementation_plan:
+  applies_when: [ui_impact]
+  required_before: [ready_for_agent]
+  required: [prototype_ref, spec_ref, route_and_page_inventory, visual_acceptance_cases, desktop_viewport, narrow_viewport, state_cases, pnpm_commands]
+  schema: docs/process/schemas/frontend-implementation-evidence.schema.json
+  validator: scripts/verify-frontend-implementation-evidence
+  acceptance: [kind_plan, template_false, status_approved, no_template_placeholders, readable_baseline_refs, non_empty_acceptance_cases]
+
+frontend_implementation_verification:
+  applies_when: [ui_impact]
+  required_before: [release]
+  required: [prototype_ref, spec_ref, route_and_page_inventory, desktop_visual_evidence, narrow_view_visual_evidence, loading_empty_error_permission_interaction_results, console_warning_check, pnpm_commands, uncovered_differences, difference_owner]
+  verification: [actual_command, exit_code, executed_at, evidence_ref]
+  schema: docs/process/schemas/frontend-implementation-evidence.schema.json
+  validator: scripts/verify-frontend-implementation-evidence
+  acceptance: [kind_verification, template_false, status_approved, no_template_placeholders, console_warning_pass, independent_review_approved]
+  blocked_when: [unexplained_visual_difference, missing_visual_evidence, typecheck_only, claimed_alignment_without_evidence]
+  on_new_impact: [new_impacts, drift, reroute]
+
+unknown_impact:
+  action: pause
+  reason_code: impact-classification-required
+
+# 每个 target 必须声明 kind、传播层级和适用条件。条件不满足时保持原状态，尤其不得把 not-applicable 改成 stale。
+impact_propagation:
+  wording:
+    targets:
+      - {kind: artifact, name: spec, level: direct, when: always}
+  ui-state:
+    targets:
+      - {kind: artifact, name: product-design, level: direct, when: ui_impact}
+      - {kind: artifact, name: prototype, level: direct, when: ui_impact}
+      - {kind: gate, name: requirement-freeze, level: direct, when: ui_impact}
+      - {kind: artifact, name: openapi-draft, level: transitive, when: api_impact}
+      - {kind: gate, name: openapi-freeze, level: transitive, when: api_impact}
+      - {kind: artifact, name: vertical-slice-tickets, level: transitive, when: always}
+  api-schema:
+    targets:
+      - {kind: artifact, name: spec, level: direct, when: always}
+      - {kind: artifact, name: spec-delta, level: direct, when: existing_frozen_baseline}
+      - {kind: artifact, name: openapi-draft, level: direct, when: api_impact}
+      - {kind: gate, name: draft-review, level: transitive, when: api_impact}
+      - {kind: gate, name: design-review, level: transitive, when: api_impact}
+      - {kind: gate, name: openapi-freeze, level: transitive, when: api_impact}
+      - {kind: artifact, name: vertical-slice-tickets, level: transitive, when: api_impact}
+      - {kind: artifact, name: contract-tests, level: transitive, when: api_impact}
+  state-machine:
+    targets:
+      - {kind: artifact, name: spec, level: direct, when: always}
+      - {kind: artifact, name: spec-delta, level: direct, when: existing_frozen_baseline}
+      - {kind: artifact, name: product-design, level: direct, when: ui_impact}
+      - {kind: artifact, name: system-architecture, level: direct, when: always}
+      - {kind: artifact, name: data-architecture, level: direct, when: data_impact}
+      - {kind: gate, name: requirement-freeze, level: direct, when: always}
+      - {kind: artifact, name: openapi-draft, level: transitive, when: api_impact}
+      - {kind: gate, name: design-review, level: transitive, when: always}
+      - {kind: gate, name: openapi-freeze, level: transitive, when: api_impact}
+      - {kind: artifact, name: vertical-slice-tickets, level: transitive, when: always}
+      - {kind: artifact, name: test-mapping, level: transitive, when: always}
+  data-model:
+    targets:
+      - {kind: artifact, name: spec, level: direct, when: always}
+      - {kind: artifact, name: spec-delta, level: direct, when: existing_frozen_baseline}
+      - {kind: artifact, name: data-architecture, level: direct, when: data_impact}
+      - {kind: gate, name: architecture-review, level: direct, when: data_impact}
+      - {kind: artifact, name: openapi-draft, level: transitive, when: api_impact}
+      - {kind: gate, name: openapi-freeze, level: transitive, when: api_impact}
+      - {kind: artifact, name: vertical-slice-tickets, level: transitive, when: always}
+      - {kind: artifact, name: data-migration, level: transitive, when: data_impact}
+  service-boundary:
+    targets:
+      - {kind: artifact, name: system-architecture, level: direct, when: always}
+      - {kind: artifact, name: engineering-baseline, level: direct, when: backend_impact}
+      - {kind: gate, name: architecture-review, level: direct, when: always}
+      - {kind: artifact, name: openapi-draft, level: transitive, when: api_impact}
+      - {kind: gate, name: openapi-freeze, level: transitive, when: api_impact}
+      - {kind: artifact, name: vertical-slice-tickets, level: transitive, when: always}
+  nfr:
+    targets:
+      - {kind: artifact, name: spec, level: direct, when: always}
+      - {kind: artifact, name: system-architecture, level: direct, when: always}
+      - {kind: gate, name: design-review, level: direct, when: always}
+      - {kind: artifact, name: vertical-slice-tickets, level: transitive, when: always}
+      - {kind: artifact, name: verification-strategy, level: transitive, when: always}
+  deployment:
+    targets:
+      - {kind: artifact, name: system-architecture, level: direct, when: always}
+      - {kind: artifact, name: rollout-plan, level: direct, when: always}
+      - {kind: artifact, name: rollback-plan, level: direct, when: always}
+      - {kind: gate, name: design-review, level: transitive, when: always}
+      - {kind: artifact, name: release-plan, level: transitive, when: always}
+prototype_return_evidence:
+  required: [prototype_mode, source_handoff, prototype_asset_or_run, conclusion, updated_authoritative_asset, remaining_questions, return_handoff]
+  allowed_modes: [matt_logic, yss_high_fidelity]
+
+# Matt phase boundaries are context decisions only. They never add a lifecycle state,
+# alter a gate, or mutate a Ticket role.
+phase_boundary:
+  choices: [continue, clear, handoff, subagent, compact]
+  precedence: [continue, clear, handoff, subagent, compact]
+  invariants: [does-not-force-clear, preserves-lifecycle-state]
+  evidence:
+    required: [decision, reason]
+    conditional:
+      handoff: [source_ref, destination_ref]
+      subagent: [task_package_ref, convergence_ref]
+      compact: [next_phase]
+  preserves: [lifecycle.status, gate.status, ticket.role]
+
+external_input_pause:
+  transition: pause
+  reason_code: external-input-required
+  reason: required decision-maker input is not available to the Agent
+  required: [questionnaire_ref, recipient_role, requested_outputs, resume_route]
+  response_required: [response_ref, reclassified_impact, updated_authoritative_asset]
+  resume_requires: [response_ref, reclassified_impact, updated_authoritative_asset]
+
+prototype_modes:
+  matt_logic:
+    asset: single_file_shareable_html
+    branch_pattern: prototype/<name>
+    required: [prototype_mode, prototype_branch, source_handoff, prototype_asset_or_run, conclusion, updated_authoritative_asset, remaining_questions, return_handoff]
+    purpose: exploratory_primary_source
+    production_delivery: false
+    replaces_yss_high_fidelity: false
+  yss_high_fidelity:
+    asset: ant_design_v6_html
+    required: [prototype_mode, prototype_review, antd_cli_verification, browser_verification, prototype_evidence, user_confirmation]
+    purpose: product_design_review
+    replaces_matt_logic: false
+
+behavioral_invariants:
+  wait_what_preserves_state: true
+  human_checkpoint_required_for_manual_steps: true
+  diagnostics_redact_secrets: true

package/template/.cursor/skills/yss-product-lifecycle/references/orchestration.md

@@ -0,0 +1,103 @@
+# 编排执行协议
+
+## 有界推进循环
+
+1. 识别模式、仓库身份、任务规模和影响面。
+2. `setup readiness`：每个任务只执行一次，核对 tracker、五态标签和领域文档布局，并在本轮缓存结果；仅在 tracker、主远端、真实标签或配置变化时重查。
+3. 加载父 Ticket/checkpoint 与真实资产，计算最近可信阶段。
+4. 评估资产、门禁和 `stale`，选择第一个未阻塞工作单元。
+5. 执行最小生命周期工作单元：只实际调用允许的 model-invoked skill；原生工作单元可直接持有正式资产，Matt 兼容 user-invoked skill 仅作为 workflow reference，仍由用户显式启动。将结果归一化为 `Workflow Execution Result`，验收输出并回写状态与证据。
+6. 若仍在授权和自动推进边界内，回到第 3 步；否则暂停。
+
+不要仅输出下一个提示词后结束 `orchestrate`/`resume`。不要因进入业务代码阶段而退出主控；应把实现交给专项 skill，并在返回后继续核验。
+
+连续阶段自动推进时累积 Ticket 同步和 Git 判断证据，在人工暂停、handoff、进入实现、合并或发布边界集中 checkpoint。发生阻塞、责任人变化或资产需要单独批准时立即落 checkpoint，不因合并记录而丢失阶段因果关系。
+
+## 阶段边界
+
+Matt phase boundary 是工作阶段之间的上下文决策，不是新的生命周期状态。按以下顺序判断，第一项适用即停止判断：
+
+1. **Continue**：下一阶段需要当前会话作为 primary source，或当前上下文仍在 smart zone 内。
+2. **`/clear`**：当前探索、死路和决策对下一阶段完全无关。
+3. **`/handoff`**：内容必须跨新 harness、新目录、同事或中途分叉的 side task 携带。
+4. **Subagent**：工作单元边界清晰，可以在无人值守时完成并返回报告。
+5. **`/compact`**：同一 harness、同一目录且上下文仍相关，但需要压缩后继续；它是最后选项。
+
+在 checkpoint 记录 `phase_boundary.decision`；使用 `handoff`、subagent 或 `compact` 时同时记录契约要求的引用。phase boundary 不得改变生命周期阶段、门禁或 Ticket 五态。
+
+## 原型到后端脚手架的接力
+
+`prototype_confirmation` 通过后，先判断实现仓库登记中的 backend `scaffold_status`。当状态为 `required` 时，先完成工程基线，由 `yss-router` 编译脚手架 `controlled-generation` 工作单元合同，生命周期编排器批准并持久化后才能运行生成器；顺序为：工程基线 → Router 脚手架合同 draft → 生命周期批准/持久化 → 脚手架生成 → `yss-backend-scaffold-parent` 基线校验 → Router 合同重编译。`existing` / `initialized` 不重复全量生成，但不能跳过基线校验和 Router 重编译。
+
+脚手架工作单元必须使用结构化合同 JSON 文件，至少记录 `contract_id`、`contract_version`、`slice_id`、Router draft 引用、生命周期批准引用、持久化引用、当前版本、允许写路径、预期证据文件和验证命令；批准记录至少含 `approval_ref`、`approver`、`persisted_ref`、`current_version`。生成器必须读取该合同文件并校验状态、版本、skill、工作模式和固定命令，不能只接受任意字符串参数。它还必须记录生成器输入、预期文件、目标目录、实际 `./mvnw validate` / `./mvnw test` / `./mvnw package` 结果和 YSS Skill Execution Result。三条命令必须由受控工作单元真实执行，逐条留存 `exit_code`、`duration_ms`、stdout/stderr 引用和执行时间；生成器打印的下一步命令不构成证据。生命周期生成关闭 `--with-example`；非空目标目录使用 `--force` 默认阻断，除非覆盖范围、备份、回滚点和批准引用已进入合同。脚手架不得把业务规则、状态机、权限、事务、复杂查询、错误映射或用户可见行为放进生成物；`validate` 通过、输出目录存在或生成器成功都不是生命周期批准、架构放行或 `ready-for-agent`。
+
+脚手架完成后，所有后续生成的后端代码仍必须重新消费当前版本的批准 Slice Implementation Contract、YSS skill 依赖闭包、允许写路径、预期证据和 Execution Result。业务行为使用 `behavior-tdd`；只有机械结构、样板、配置和冻结客户端使用 `controlled-generation`。缺少合同、skill、证据或实际验证时立即阻断；生成范围从机械内容变成业务行为时触发完整重路由。
+
+## Setup readiness
+
+Readiness 结果在同一任务内复用。只有 tracker、主远端、真实标签或配置发生变化，才重新执行检查；不得把 `setup-matt-pocock-skills` 当作每阶段或每工作单元的固定动作。
+
+| 状态 | 判定 | 动作 |
+|---|---|---|
+| `ready` | tracker、Local `Status:` 或远程标签和领域布局兼容 | 继续 |
+| `missing` | 必要配置缺失 | `needs-human`；说明缺失项并请用户显式运行 `setup-matt-pocock-skills`，随后回到 readiness |
+| `conflict` | 多个持久配置或真实标签/Local 状态互相矛盾 | 暂停并提出迁移方案，不覆盖 |
+| `degraded` | 已选择的 GitHub/GitLab 不可用 | 建 `docs/.scratch/<feature>/` 待发布草案，不改投平台 |
+| `not-applicable` | `template-source` | 只验证模板契约 |
+
+远程 tracker 必须检查真实标签；Local Markdown 必须检查功能包目录和 Ticket 顶部的 `Status:`。仅有 `docs/agents/triage-labels.md` 不代表远程标签存在，也不能替代 Local 文件状态检查。
+
+tracker 选择和冲突按 `docs/agents/issue-tracker.md` 裁决：已持久化 tracker 配置优先，本模板默认 `local-markdown`，Local root 为 `docs/.scratch/`；用户在初始化/迁移时明确选择 GitHub/GitLab 后才切换，Git remote 只代表代码托管。Local 主 tracker 不要求远程 Ticket；只有已选择远程平台但凭据不可用时，才降级为 `docs/.scratch/<feature>/` 待发布草案，不自动改投其他平台。发现根 `.scratch/` 或 `docs/requirements/tickets/` 旧资产时，保留 `migration_ref` 并暂停写入；新旧路径同时存在时返回 `conflict`。恢复前记录最终平台、真实五态标签或 Local `Status:` 检查结果和草案位置。
+
+## Matt flow 进入条件
+
+- `work-unit.discovery-requirements` 实际调用 `grilling` 和 `domain-modeling`；`work-unit.discovery-opportunity` 按事实类型路由 `competitive-intelligence` 或 `research`。生命周期原生工作单元默认负责 Spec、Ticket 和实现资产；`to-spec`、`to-tickets`、`implement` 仅保留为显式兼容入口，结果必须回交生命周期验收。
+- 原生 `work-unit.ticket-decomposition` 只能在 OpenAPI Freeze 或无 API 影响记录后创建垂直切片，初始角色统一为 `ready-for-human`；生命周期复算完整公式后才能提升 `ready-for-agent`。
+- 原生 `work-unit.slice-implementation` 必须在生命周期批准并持久化 Slice Implementation Contract 和 Build Architecture Checklist 后执行；用户显式 `implement` 仍走兼容入口，不得绕过生命周期。
+- `implement` 遇到 backend `scaffold_status=required` 时，还必须满足原型确认后的脚手架策略：脚手架 Execution Result、`yss-backend-scaffold-parent` 基线、Wrapper 验证和 Router 合同重编译均已回写；否则停在工程基线，不得写业务代码。
+- `Workflow Execution Result` 出现 `drift`、`new_impacts`、`stale_candidates`、`violation`、`missing_evidence`、空 `evidence_refs` 或缺少必需字段时暂停当前工作单元；旧结果只能先经只读兼容 adapter 归一化。
+
+## 审查与验证
+
+- 调用 `code-review` 前先固定 review input：`review_mode`、`review_base_ref`、`implementation_candidate_ref`、`candidate_snapshot_ref`、`candidate_digest`、Spec/Ticket、Slice Implementation Contract、Build Architecture Checklist 和 YSS Skill Execution Result 引用。`committed` 模式审查不可变 `HEAD`；`worktree` 模式一次捕获 committed、staged、unstaged 和 untracked 内容。必须按 `orchestration-contract.yaml.review_input` 的 manifest 按模式必填字段及 `yss-worktree-candidate-v1` 字节流（raw path、uint64 big-endian 长度、tracked/untracked record）计算 SHA-256，两个 Reviewer 必须消费同一不可变快照。返回后或完成 checkpoint 摘要变化时返回 `blocked`，由编排器决定重新审查。候选为空、漏项或 fixed point 不可解析时阻断。
+- 小改动和中等变更可由同一独立执行者完成 `code-review` 与 fresh verification，并在同一报告中分别记录 findings、命令、结果和残余风险。
+- 该执行者必须独立于实现者；新模块、高风险变更、职责冲突或需双人控制时，Reviewer 与 Verifier 分开。
+- `code-review` 是唯一默认代码审查 skill。GitLab、CI、Sonar、Alibaba Java 等治理事实作为仓库规则或专项检查输入，不再叠加第二个通用审查 skill。
+- UI 影响切片将 `UI fidelity` 作为 `code-review` 的条件第三轴；任何修复都会使候选摘要失效，必须重新捕获候选并重跑 Standards、Spec、UI fidelity 和 fresh verification。
+
+## Git 授权
+
+实现授权、`orchestrate`/`resume` 的有界写入、当前分支和 Git checkpoint 都不蕴含 commit 或 push 授权。执行 commit 前必须同时取得 `commit_authorized=true`、非空 `commit_scope` 和 `commit_authorization_ref`；执行 push 前必须同时取得 `push_authorized=true`、非空 `push_scope` 和 `push_authorization_ref`。任一缺失时只记录 checkpoint 判断并保持 Git 状态不变；负责人要求、时间压力、测试通过或“本地 commit 可逆”都不能补足用户授权。
+
+## 必须暂停
+
+- Spec baseline、需求冻结、原型确认、OpenAPI Freeze 或 Architecture Review 等普通门禁等待人工裁决。
+- 需要目标仓库、外部凭据、发布窗口或其他新授权。
+- 状态与证据冲突且无法可靠重建。
+- 专项 skill 失败或返回不可验收结果。
+- 即将作出可合并、可发布或完成结论。
+
+暂停输出：门禁、证据、责任人、推荐答案、一个问题、恢复动作。
+
+## Wayfinder 完成判定
+
+“无 frontier”不等于完成。只有以下条件同时成立，才能 `wayfinder → handoff → to-spec`：
+
+- open child tickets 为 0；
+- 不存在 open blocked 或 open claimed child ticket；
+- `Not yet specified` 无剩余 fog；
+- destination 已清晰。
+
+Decision ticket 产生决策，不是实现切片，不得标记 `ready-for-agent`。
+
+## `grill-with-docs` 退出判定
+
+进入 `to-spec` 前必须区分已确认项与未决项，并确认用户、问题、MVP、非目标、成功标准、术语/ADR 候选和测试 seam。事实问题走 `research`；需 runnable 反馈的问题走 `handoff → prototype → handoff`。存在未回流 blocker 时不得进入 Spec baseline。
+
+Prototype 回流必须有可核验证据：来源 handoff、prototype 资产或运行记录、结论、被更新的 Spec/设计/ADR/Ticket 引用、剩余未决项和返回 handoff。仅在对话中声称“已验证”不算回流完成。
+
+Matt `prototype` 的回流还必须注明 `prototype_branch`，并保留单文件 HTML 主来源；YSS 高保真 HTML 原型另走阶段 4 的评审、AntD CLI 校验和用户确认，不得用 throwaway prototype 替代。
+
+`to-questionnaire` 未收到答案时使用 `external-input-required` 暂停，记录问卷、接收人、所需输出和恢复路由；收到答案后记录 response、重新分类影响面和更新后的权威资产，再回到 `grill-with-docs` 或 `to-spec`。
+
+Release 与 Retrospective 属于生命周期编排器拥有的工作单元。发布和复盘前都必须重新取得 fresh verification；发布还需要发布/回滚证据和独立审查，复盘还需要复盘记录和治理回流判断，再回流权威资产。