yugoo-design 0.1.2 → 0.2.2

package/payload/desktop-preparation/studio-authoring-template/authoring/studio-creators/source/packages/skills-web-app/bundles/research/validation.yaml

@@ -0,0 +1,74 @@
+# research validation contract.
+# Mechanical publication validation uses the installed schema and the rules
+# declared below. Citation provenance and report quality are reviewed by the
+# executing Agent against SKILL.md, not by a separate citation/report driver
+# declared in this Bundle. A successful validation is not proof of grounding.
+# Explicit per-direction source/scope bounds in research_points are also
+# Agent-reviewed against the actual report; these rules do not infer numeric
+# source limits from free text. Passing them does not waive the user's bounds.
+#
+# Contract summary:
+# - Every accepted direction has a direct `findings_file` and non-empty file.
+# - Attempt failure stays in Host execution events, never in canonical JSON.
+# - A completed/partial round has a direct, non-empty `conclusion_file`.
+skill: research
+
+rules:
+  - id: referenced_files_present
+    scope: [state]
+    code: research.referenced_artifact_invalid
+    check:
+      referenced_files: ["rounds.*.directions.*.findings_file", "rounds.*.conclusion_file"]
+
+  # ---- validate_state ----
+  - id: empty_plan
+    scope: [state]
+    code: research.empty_plan
+    message: "The research plan has no rounds."
+    repair_hint: "Create one round with a concrete topic and directions."
+    check: { non_empty_map: rounds }
+
+  - id: empty_round_order
+    scope: [state]
+    code: research.empty_round_order
+    message: "round_order is empty."
+    repair_hint: "List every active research round in chronological order."
+    check: { non_empty_list: round_order }
+
+  - id: invalid_current_round
+    scope: [state]
+    code: research.invalid_current_round
+    message: "current_round_id does not identify a planned round."
+    repair_hint: "Set current_round_id to the round being executed."
+    check: { member_of_map: { value: current_round_id, map: rounds } }
+
+  - id: empty_topic
+    scope: [state]
+    code: research.empty_topic
+    message: "Round {round_id} has no topic."
+    repair_hint: "State the concrete research goal for this round."
+    check:
+      for_each_in_map: rounds
+      non_empty_string: topic
+
+  - id: empty_directions
+    scope: [state]
+    code: research.empty_directions
+    message: "Round {round_id} has no research directions."
+    repair_hint: "Add at least one evidence-oriented direction."
+    check:
+      for_each_in_map: rounds
+      non_empty_map: directions
+
+  - id: empty_direction_order
+    scope: [state]
+    code: research.empty_direction_order
+    message: "Round {round_id} has an empty direction_order."
+    repair_hint: "List every planned direction id."
+    check:
+      for_each_in_map: rounds
+      non_empty_list: direction_order
+
+  # Candidate prose quality and citation grounding are Agent-reviewed against
+  # SKILL.md. Schema plus these rules remain the single publication validator;
+  # no second state-transform script participates in the workflow.

package/payload/desktop-preparation/studio-authoring-template/authoring/studio-creators/source/packages/skills-web-app/bundles/role_access/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: role_access
+description: |-
+  - **Capability**: define product roles, how each role is obtained, the concrete operations each role is allowed or explicitly forbidden to perform, and optional single-parent permission inheritance.
+  - **Resolves**: S/T gaps where actors are known but authorization boundaries, target ranges, runtime conditions, or extra verification remain unclear.
+  - **Candidate when**: different users or service identities use the product differently, a flow/page contains protected actions, or the user explicitly asks for roles, permissions, RBAC, or access control.
+  - **Do not infer**: a job title, flow lane, persona, or page visitor is not automatically a product role; do not invent organization levels or enterprise separation-of-duties rules.
+  - **Output**: `role_access` panel — editable roles with assignment rules, local permissions, and an optional same-source inheritance graph with read-only ancestor permission sources.
+---
+
+# Roles and Permissions
+
+For canvas generation or revision, read [the canvas guide](reference/canvas-guide.md).
+It supplements the existing methods and output contract; it applies to both
+new design and reconstruction without replacing domain-specific rules.
+
+## Ownership and tools
+
+`role_access/role_access.json` is the only canonical state. The foreground
+Producer uses project-scoped `list` and `read` to inspect that state, GROUND,
+and the smallest relevant Design evidence. It uses `write` or `edit` to maintain
+the complete authorization design in its owned WorkingCopy. This lightweight
+skill is completed directly by the Producer.
+
+For a proposal that requires explicit review, the Producer calls
+`design_validate`, repairs every schema or declarative validation diagnostic in
+the same WorkingCopy, and repeats
+until valid. It then calls `design_publish({action:"handoff"})` to publish the
+canonical state before the review gate. A panel save already persists the
+user's edits; later runs read and preserve them.
+
+## Maintaining existing design
+
+The saved `role_access` state is the authority for the current authorization design. A later request changes the affected role or permission; it does not create a parallel permission matrix.
+
+- Read the current state before a material revision when the relevant role, assignment rule, permission, condition, or extra requirement is not already visible in the current design context.
+- Preserve unaffected role and policy IDs, order, wording, conditions, and requirements. A policy belongs to one role only, so editing one role must never alter another role's policy record.
+- For the first material role design and for any later add, rename, delete, reassignment, permission change, or condition refinement, maintain the complete updated state in the Producer's WorkingCopy, preserving unaffected records and including the complete changed order list. A deletion drops the role or policy from the state and from its order list. Panel saves already persist edits and must not be repeated merely to continue the conversation.
+- Preserve existing inheritance edge IDs, direction and explanation. Removing a role
+  removes its own policies and incident inheritance edges in the same state; it
+  never deletes another role or copies a removed parent's permissions to its children.
+  A parent-policy edit can affect descendants' inherited view: name that impact
+  and keep those policy records at their original owner. Changing an assignment
+  rule does not change descendants' assignment rules.
+
+## Prerequisite evidence
+
+This Bundle deepens established capabilities and protected journey actions from `function_modules` and `flow_design`. Treat their persisted records as references and never copy them into a parallel function or flow model. When either source is absent, keep only roles and permissions grounded by the current request and visible design evidence; do not invent actors or protected actions to complete the panel. The user may explicitly authorize reasonable assumptions, but unsupported decisions remain assumptions rather than facts attributed to another Bundle. This evidence relationship is not a fixed execution order.
+
+## Post-write Design projection self-check
+
+After every successful canonical write and before ending this skill, inspect the refreshed revision-pinned Design projection once. Compare the persisted roles and permission decisions with the available `function_modules` and `flow_design` evidence. Repair one deterministic issue owned by `role_access` with at most one focused follow-up write, then inspect the refreshed projection once more. Ask the user when a real authorization decision is required. If an upstream Bundle or record is missing, malformed, or unresolved, report that non-blocking evidence gap without undoing the valid write, editing another Bundle, or retrying indefinitely. After the write enters the Design Project Git history, G/R/A owns ongoing cross-Bundle drift checks.
+
+## When to use
+
+Use this skill when the product needs an explicit answer to two questions: how an identity receives a named role, and what that role may do. It is appropriate after actors or protected product actions are known, or whenever the user directly asks to design or revise access control.
+
+Do not use it to repeat personas, job descriptions, responsibilities, organization charts, workflow participation, or page navigation. Those facts may provide evidence for a role, but a role exists only when a distinct permission set is needed. Public access is a permission decision outside this granted-role panel. A function or page being visible does not by itself prove that every visitor may operate it.
+
+The general Web App model assumes one current role per user or service identity within the product context. An optional single-parent chain can reuse an evidenced permission set; it does not grant the identity multiple roles. Products that intentionally compose multiple roles, require multiple parents, calculate permissions from organization hierarchy, or require separation-of-duties matrices belong in a custom enterprise skill.
+
+## Close-out evidence
+
+Close only after the visible roles, assignment rules, and material permission decisions are persisted and reviewed through the native panel, with every completion issue repaired. A reviewed role design primarily adds S and T evidence because authorization boundaries and observable allowed behavior become inspectable. It may improve U only when resolving roles clarifies who the product actually serves. Report the persisted evidence behind those changes; role or permission count alone adds no clarity.
+
+### Typical evidence guidance
+
+- Reviewed roles, assignment conditions and material permission decisions provide evidence about authorization structure and observable allowed behavior under the shared rubric; no fixed S/T increment follows from producing a role design.
+- Resolving an unclear actor or product boundary can also provide U evidence; any score change follows the saved facts and current agreed scope, not a fixed range.
+- Empty roles, permissions copied from job descriptions, uncovered protected actions, or broad access without a grounded condition may leave scores unchanged or lower them.
+
+## Output contract
+
+Read [the shared output contract](reference/artifact-contract.md) for these field meanings, examples and checks; it is used by both ordinary design and reconstruction.
+
+## Inputs and authority
+
+Before proposing roles, inspect GROUND and the smallest relevant set of persisted design evidence:
+
+| Prior evidence | Extract | Use in this skill |
+|---|---|---|
+| `smart_questions` / GROUND | established users, account mode, membership or invitation facts | identify grounded identities and assignment rules |
+| `function_modules` | active user-facing capabilities | find product areas that may contain protected operations; do not turn every function into a permission |
+| `flow_design` | actors, approvals, handoffs, exceptional actions | inventory who performs material actions; a lane is evidence, not automatic permission |
+| `business_data` / `business_rules` | business things, visible states, eligibility and prohibitions | write a natural `applies_when` or explicit deny only when required |
+| `page_design` | visible actions on lists, details, forms, and workspaces | check that every protected user action has a role decision |
+
+If those artifacts do not exist, use the user's current requirement conservatively. Prefer `用户` and `管理员` over fabricated department titles. Never invent identity-provider groups, organization levels, API scopes, endpoint names, or database identifiers.
+
+### Usage
+
+Maintain the complete role design state for the first material design and for every later chat-requested change. Run integration validation and publish the paused WorkingCopy before presenting the native panel. The native panel persists its own edits; do not repeat a panel save.
+
+The host appends the exact generated schema to this body. Follow that schema literally: `roles` and `policies` are ID-keyed mappings, `role_order` and `policy_order` are ordered ID lists, and every policy uses the singular `role_ref`.
+
+## Workflow
+
+### 1. Build an action inventory from evidence
+
+List the material product operations implied by established flows and pages before creating roles. Focus on operations that change data, reveal non-public information, approve or reject work, manage other users, export information, or alter configuration. Ordinary navigation and viewing public content do not need role records.
+
+For each protected operation, identify:
+
+- the actor that needs it;
+- the user-visible capability, written as a verb plus its target, such as `审批订单` or `查看项目成员`;
+- whether it applies everywhere or only to a target range/state;
+- whether the operation needs an extra confirmation step.
+
+Do not persist this inventory as another collection. It is a reasoning checklist used to form `roles` and `policies`.
+
+### 2. Derive permission sets, not job titles
+
+Start with established actors, then group them by required access:
+
+- Merge actors into one role when they obtain access the same way and need materially the same permission set, even if their business titles differ.
+- Split roles when their allowed operations materially differ. A reviewer who can approve an order and an applicant who can only submit it need different roles.
+- Keep one role and use `applies_when` when the operations are the same but apply only to owned records, one workspace, or a lifecycle state.
+- Do not create a second role merely to express temporary confirmation, record ownership, or one conditional operation.
+- Treat a service identity as a role only when it authenticates to the product and performs protected product operations.
+
+A role title must be durable and understandable to the user. Prefer `项目成员`, `审批人`, and `系统管理员`; avoid person names, temporary team names, and internal group codes.
+
+### 3. State how each role is obtained
+
+Read [the shared output contract](reference/artifact-contract.md) for these field meanings, examples and checks; it is used by both ordinary design and reconstruction.
+
+For a new design, grant only operations needed by established tasks and add
+extra verification only when an allowed high-impact operation needs it.
+Restoration preserves the evidenced grants and verification even when a better
+policy could be proposed; policy improvements are separate design work.
+
+### Optional permission inheritance
+
+Start with flat roles. Add `inheritances` only when the request or observed access
+behavior establishes that one role receives another role's permission set. A job
+title, seniority, flow lane, larger scope, or similar capability names do not prove
+inheritance. An administrator needing a wider target range does not inherit a
+member's narrower grant merely because the administrator looks more senior.
+
+Use one edge from child `source` to parent `target`, with `kind="inherits"`.
+Each child has at most one parent; a parent may have multiple children, and
+chains may span multiple levels. Reject self-links, cycles, missing endpoints
+and duplicate parent edges. Never add `roles.parent_ref` as a second authority.
+
+Local policies remain attached through their original singular `role_ref`.
+Show inherited policies read-only with the originating role, preserving the
+original `effect`, target range and `applies_when`, `requirements`, and
+`custom_requirement` at every level. Do not copy those policies to the child,
+remove verification, rewrite “own records” as “all records”, or inherit the
+parent's `assignment_rule`. Edit a sourced policy at its owning role only when
+that change and its descendant impact are authorized.
+
+Walk a concrete protected action for the child through the entire parent chain.
+If local and ancestor decisions might overlap or contradict, explain the source
+roles, conditions and unresolved decision in the handoff and ask when needed.
+Do not infer that a local rule overrides a parent, that deny always wins, or that
+identical natural-language capability text establishes the same authorization
+scope. This Bundle designs inspectable access facts, not an enterprise ACL
+evaluator. Do not claim the inheritance design is resolved while a consequential
+allow/deny conflict remains unclear. Reconstruction preserves supported source
+semantics and reports unsupported composition rather than inventing precedence.
+
+### 7. Reconcile coverage and least privilege
+
+Before writing or closing, check the design in both directions:
+
+1. Every protected action established in a flow or page has one grounded allow decision for the role expected to perform it.
+2. Every allow decision traces to an established user task; remove speculative or convenience access.
+3. Every `role_ref` resolves to one existing role, and each role has at least one material local or explicitly inherited permission.
+4. Similar role titles do not hide identical permission sets that should be merged.
+5. Conditions do not contradict business rules or lifecycle states.
+6. A role cannot approve, administer, export, or view sensitive information merely because it participates in the same flow.
+7. Every inheritance edge is evidenced, single-parent, acyclic and endpoint-valid;
+   inherited permissions retain their original conditions and verification, with
+   any consequential conflict resolved explicitly rather than guessed.
+
+If a required identity fact is missing, preserve the smallest safe design and report the gap in close-out. Do not silently broaden access to make a workflow appear complete.
+
+## State contract
+
+Read [the shared output contract](reference/artifact-contract.md) for these field meanings, examples and checks; it is used by both ordinary design and reconstruction.
+
+## Interaction gate
+
+This skill uses `must_edit` because authorization decisions require explicit review. After the current role/access facts are validated and published with `design_publish({action:"handoff"})`, pause for the native role-centric panel. A successful panel save persists any user edits and releases the review gate; it does not create or change an evidence-review status.
+
+The form and canvas edit the same role and inheritance records. Use the shared
+canvas/details overlay switch to inspect the chain, then return to the selected
+role's details; do not create another matrix or a sidebar viewing-mode selector.
+The local permission editor and read-only ancestor sources have different edit
+ownership even when both are visible. Default flat data remains useful without
+an inheritance edge or an invented parent.
+
+## Close-out
+
+Summarize the reviewed result by role: how it is obtained, its principal permission decisions, optional parent chain and original permission sources, and material conditions or extra verification. Report only actionable uncovered operations, contradictory decisions, excessive access, or missing identity facts. Do not repeat the full permission list in chat when it is already readable in the panel.

package/payload/desktop-preparation/studio-authoring-template/authoring/studio-creators/source/packages/skills-web-app/bundles/role_access/reference/artifact-contract.md

@@ -0,0 +1,186 @@
+# role_access output contract
+
+For canvas generation or revision, read [the canvas guide](canvas-guide.md).
+It supplements the existing methods and output contract; it applies to both
+new design and reconstruction without replacing domain-specific rules.
+
+Shared by ordinary design and reconstruction. Canonical state is
+`role_access/role_access.json`; the installed schema and validation remain
+authoritative. This reference describes representation and semantic checks,
+not permission to invent facts, choose new policy or trigger user review.
+Examples and design recommendations below are not source evidence. In
+reconstruction, preserve observed behavior and supported uncertainty; report
+required facts that cannot be represented rather than fabricating a value.
+
+Roles represent permission sets, not job descriptions or flow participants. Preserve actual access behavior rather than improving its least-privilege policy during restoration. The model uses one current role per identity in context; report multi-role composition or other unrepresentable semantics instead of silently flattening them. A missing permission in inspected evidence does not prove source denial; the panel’s unlisted-operation convention must not become a claim about unexamined source behavior.
+
+## Output contract
+
+Persist the role and policy evidence, with optional explicit inheritance edges:
+
+1. `RoleDefinition`: a durable named permission set and one plain-language rule explaining who receives it and when.
+2. `AccessPolicy`: one allow/deny decision owned by exactly one role, expressed as a user-understandable capability with an optional applicability sentence and optional pre-operation verification.
+3. Optional `RoleInheritance`: one child-to-parent permission-set edge. It does
+   not express organizational rank or a second assignment rule.
+
+Do not create persona, responsibility, role-conflict, shared-policy, access-scope, condition-rule, design-reference, safeguard, assumption, or open-question collections. Keep detailed source content in its owner skill and refer to it while reasoning; do not duplicate it into role state.
+
+### 3. State how each role is obtained
+
+Write one self-contained `assignment_rule`:
+
+- `注册后自动拥有` for the ordinary registered-user role;
+- `由管理员授予` when an authorized administrator explicitly assigns it;
+- otherwise write one natural rule, such as `受邀加入项目后拥有，离开项目时失去`.
+
+Do not store the option label `其他`; store the actual rule. Do not describe what the role does in `assignment_rule`.
+
+### Permission decisions
+
+Record the evidenced local operations for each role. Each policy belongs to exactly one role through `role_ref`; never share its ownership between roles. For independent roles with similar operations, use separate local records so their target range and later edits remain independent. When explicit inheritance is evidenced, retain the policy at its original owner and refer through the parent edge instead of copying it.
+
+Write `capability` as one natural user-facing phrase. Do not split it into technical resource/action fields and never expose strings such as `approve:business_data:order`, endpoint names, or code symbols. Set `title` to a readable summary of the decision, normally `允许{capability}` or `禁止{capability}`; it is record metadata, not a second permission concept shown for user input.
+
+The panel models explicit permission decisions, with unlisted operations implicitly denied in that model. This convention does not establish source behavior when evidence coverage is incomplete.
+
+- Use `effect="allow"` for an evidenced grant, even if it appears broader than necessary.
+- Use `effect="deny"` only when an explicit prohibition must remain visible because a broader-looking permission could otherwise be misunderstood, a business rule expressly forbids the operation, or the user asks to record it.
+- Do not generate exhaustive deny lists for everything the role cannot do.
+
+### 5. Add one applicability sentence only when needed
+
+Leave `applies_when` empty when the decision applies to every instance and state relevant to the role. Otherwise combine target range and runtime condition into one plain-language sentence, for example `仅限自己负责的客户，且客户仍在跟进中`.
+
+Use this field for ownership, workspace boundary, record relationship, lifecycle state, amount threshold, or another established condition. Do not create separate scope and condition records. Do not hide a second permission inside the condition.
+
+### 6. Add extra verification only when the operation itself needs it
+
+`requirements` may contain:
+
+- `confirm`: ask the user to confirm immediately before the operation;
+- `reauthenticate`: verify the user's identity again;
+- `custom`: perform the plain-language step in `custom_requirement`.
+
+Record these when the allowed operation has that verification, regardless of its perceived risk. When `custom` is absent, leave `custom_requirement` empty. These steps do not grant permission; they are additional checks after the role is already allowed to act.
+
+### Optional single-parent inheritance
+
+Old `schema_version: 5` state without `inheritances`, or with an empty map,
+remains flat. Do not insert edges merely to populate the canvas. The optional
+map uses stable edge keys equal to `id`; each edge has `id`, readable `title`,
+`kind: "inherits"`, child role ID `source`, parent role ID `target`, and optional
+`description` explaining the evidenced relationship. There is no second
+`parent_ref`, ancestor list, inherited-policy copy, derived effective-policy map,
+or inheritance order list. The existing role and policy order lists are unchanged.
+
+For example, synthetic `reviewer -> member` and `lead-reviewer -> reviewer`
+edges express a two-level chain. The reviewer still has its own assignment rule,
+and its ancestor's “edit own requests while open” grant does not become “edit
+all requests”. Its ancestor's confirmation, reauthentication or custom step also
+remains required. The example is a representation illustration, not source facts.
+
+Mechanical checks reject self-inheritance, cycles, dangling endpoints, more than
+one parent edge for a child (including duplicate edges to the same parent), and
+edge ID/key mismatch. The `kind` enum admits only `inherits`. Parent and child
+must already exist in `roles`; do not create a speculative role to repair a link.
+Removing a role removes its own local policies and every incident edge while
+preserving other roles, their local policies and remaining edges. Removing an
+edge does not remove either role or materialize its ancestor permissions locally.
+
+Inherited policies stay read-only at the child and identify their originating
+role. Preserve their effect, natural-language applicability, confirmation,
+reauthentication and custom verification without expansion. Role assignment is
+always local. Changes to a parent policy can affect descendants and need explicit
+impact discussion; changing a child's local policy never mutates an ancestor.
+
+No precedence evaluator is defined here. If an inherited/local allow or deny
+may conflict, identify both owners and original conditions and ask for the
+material missing decision. Do not infer local-over-parent or deny-over-allow from
+wording or string equality. Reconstruction reports multi-parent/multi-role or
+unknown precedence as unsupported/uncertain rather than silently flattening it.
+Both form and canvas operate on the same edges and original policies.
+
+Read [the synthetic inheritance example](example.json) only for representation;
+it is not user authorization evidence. The flat example below remains valid.
+
+## State contract
+
+Write `RoleAccessState` in this shape; the generated schema remains authoritative for exact types:
+
+```json
+{
+  "schema_version": 5,
+  "title": "项目协作角色权限",
+  "summary": "成员维护自己的任务，管理员负责成员与空间设置。",
+  "roles": {
+    "project-member": {
+      "id": "project-member",
+      "title": "项目成员",
+      "assignment_rule": "受邀加入项目后拥有，离开项目时失去"
+    },
+    "workspace-admin": {
+      "id": "workspace-admin",
+      "title": "空间管理员",
+      "assignment_rule": "由管理员授予"
+    }
+  },
+  "role_order": ["project-member", "workspace-admin"],
+  "policies": {
+    "member-edit-own-task": {
+      "id": "member-edit-own-task",
+      "title": "允许编辑自己负责的任务",
+      "role_ref": "project-member",
+      "capability": "编辑自己负责的任务",
+      "effect": "allow",
+      "applies_when": "仅限任务未完成时",
+      "requirements": [],
+      "custom_requirement": ""
+    },
+    "admin-remove-member": {
+      "id": "admin-remove-member",
+      "title": "允许移除项目成员",
+      "role_ref": "workspace-admin",
+      "capability": "移除项目成员",
+      "effect": "allow",
+      "applies_when": "仅限自己管理的空间",
+      "requirements": ["confirm"],
+      "custom_requirement": ""
+    }
+  },
+  "policy_order": ["member-edit-own-task", "admin-remove-member"]
+}
+```
+
+Use stable IDs and keep map keys equal to each record's `id`. Keep every live ID exactly once in its order list. Order lists replace wholesale, so the canonical state carries the complete changed order list when adding, removing, or reordering records; a removal also drops the record from its map.
+
+## Quality gates
+
+- Every role is a distinct permission set with one clear local assignment rule and at least one material local or explicitly inherited permission.
+- Every policy names one existing role, one effect, and one user-understandable capability.
+- Every allow is supported by the applicable evidence; missing evidence is not a denial fact.
+- Explicit denies are exceptional and grounded, never an exhaustive negative matrix.
+- `applies_when` is optional and combines target range and runtime condition in one self-contained sentence.
+- Extra requirements describe evidenced verification beyond allow/deny.
+- Flow participation, a job title, or page visibility is never treated as permission proof.
+- Every policy record keeps one owner. Editing a child's local policy cannot
+  change another role's policy record; authorized ancestor edits may change
+  descendant inherited access and must report that impact.
+- Inheritance is optional, grounded, single-parent and acyclic. Original
+  conditions and verification are preserved; unresolved consequential conflicts
+  are not hidden by an invented precedence rule.
+
+### Common mistakes
+
+```text
+Wrong: role = “销售经理”, responsibilities = “管理团队业绩”
+Right: role = “销售经理”, assignment_rule = “由管理员授予”, policies = “查看团队客户”“审批折扣申请”
+
+Wrong: capability = “approve:business_data:order”
+Right: capability = “审批订单”
+
+Wrong: one shared “查看订单” policy points to both salesperson and manager
+Right: salesperson gets “查看自己负责的订单”; manager gets a separate “查看团队订单” policy
+
+Wrong: generate denies for every omitted operation
+Right: omit unavailable operations; add an explicit deny only for a grounded prohibition such as “审批自己提交的申请”
+```

package/payload/desktop-preparation/studio-authoring-template/authoring/studio-creators/source/packages/skills-web-app/bundles/role_access/reference/canvas-guide.md

@@ -0,0 +1,38 @@
+# Role inheritance canvas
+
+Shared representation entry for design/reconstruction. Read [the output
+contract](artifact-contract.md) for role/policy meaning, assignment, verification,
+single-parent inheritance, deletion scope and supported uncertainty. Retain the
+existing SKILL's permission methods; do not replace them with graph aesthetics.
+
+## Facts and relationship semantics
+
+`role_access/role_access.json` is the only role/policy/inheritance authority.
+Nodes are permission sets, not job titles or workflow participants. Optional
+inheritance edges point from child `source` to parent `target`, kind `inherits`.
+Inherited policies retain their originating role, conditions and confirmation
+steps; assignment is local. Neither proximity nor a parent edge grants broader
+access, copies policies, or defines conflict precedence.
+
+## Layout, ports, labels and unknowns
+
+The current declaration uses the shared `relation_graph` and original-record
+inspector. Its renderer owns geometry/ports/label avoidance; Bundle generation
+does not persist another tree, coordinates, ancestor list or effective-policy
+map. Flat saved data may have no edges and remains flat. Do not add an edge to
+populate the canvas or adopt AI model/knowledge bands. Show the meaningful
+inheritance direction and originating permissions. Missing coverage is unknown,
+not proof of denial. Unsupported multiple-parent/multi-role behavior and an
+unresolved local/inherited conflict must be reported, not flattened or guessed.
+
+## Interaction, saving and review
+
+Canvas/form edit the same roles and inheritance records. Removing an edge leaves
+roles/policies intact. Removing a role removes its own local policies and
+incident edges, preserving other records; parent edits can affect descendants.
+Use the existing validated save path; already-saved diffs are not replayed.
+Read [the existing synthetic chain](example.json), not authorization evidence.
+Check stable IDs, one parent, self/cycle/dangling/duplicate edge negatives and
+source-preserving inherited details. Inspect a real chain and flat view for
+readable labels, selected identity, keyboard/resize/narrow-container behavior;
+report rendering and durable save/reopen independently from schema checks.

package/payload/desktop-preparation/studio-authoring-template/authoring/studio-creators/source/packages/skills-web-app/bundles/role_access/reference/example.json

@@ -0,0 +1,90 @@
+{
+  "schema_version": 5,
+  "title": "合成预览示例：请求处理角色",
+  "summary": "合成示例：单父多级继承保留原权限条件与验证；不是用户项目的授权事实。",
+  "roles": {
+    "R-PREVIEW-A": {
+      "id": "R-PREVIEW-A",
+      "title": "申请人",
+      "assignment_rule": "注册后自动拥有"
+    },
+    "R-PREVIEW-B": {
+      "id": "R-PREVIEW-B",
+      "title": "审核人",
+      "assignment_rule": "由管理员授予"
+    },
+    "R-PREVIEW-C": {
+      "id": "R-PREVIEW-C",
+      "title": "主审核人",
+      "assignment_rule": "由管理员明确授予主审角色"
+    }
+  },
+  "role_order": [
+    "R-PREVIEW-A",
+    "R-PREVIEW-B",
+    "R-PREVIEW-C"
+  ],
+  "policies": {
+    "AP-PREVIEW-A": {
+      "id": "AP-PREVIEW-A",
+      "title": "允许修改请求",
+      "role_ref": "R-PREVIEW-A",
+      "capability": "修改请求",
+      "effect": "allow",
+      "applies_when": "仅限本人创建且尚未通过的请求",
+      "requirements": [
+        "confirm",
+        "reauthenticate",
+        "custom"
+      ],
+      "custom_requirement": "核对请求归属后才能修改"
+    },
+    "AP-PREVIEW-B": {
+      "id": "AP-PREVIEW-B",
+      "title": "允许审核请求",
+      "role_ref": "R-PREVIEW-B",
+      "capability": "审核请求",
+      "effect": "allow",
+      "applies_when": "请求处于待审核状态",
+      "requirements": [
+        "confirm"
+      ],
+      "custom_requirement": ""
+    },
+    "AP-PREVIEW-C": {
+      "id": "AP-PREVIEW-C",
+      "title": "允许导出审核记录",
+      "role_ref": "R-PREVIEW-C",
+      "capability": "导出审核记录",
+      "effect": "allow",
+      "applies_when": "仅限本人负责的审核范围",
+      "requirements": [
+        "confirm"
+      ],
+      "custom_requirement": ""
+    }
+  },
+  "policy_order": [
+    "AP-PREVIEW-A",
+    "AP-PREVIEW-B",
+    "AP-PREVIEW-C"
+  ],
+  "inheritances": {
+    "RI-PREVIEW-B-A": {
+      "id": "RI-PREVIEW-B-A",
+      "title": "继承权限",
+      "kind": "inherits",
+      "source": "R-PREVIEW-B",
+      "target": "R-PREVIEW-A",
+      "description": "合成例：审核人保留申请人自有请求的操作条件与验证要求。"
+    },
+    "RI-PREVIEW-C-B": {
+      "id": "RI-PREVIEW-C-B",
+      "title": "继承权限",
+      "kind": "inherits",
+      "source": "R-PREVIEW-C",
+      "target": "R-PREVIEW-B",
+      "description": "合成例：主审核人复用审核权限，不继承审核人的授予规则。"
+    }
+  }
+}

package/payload/desktop-preparation/studio-authoring-template/authoring/studio-creators/source/packages/skills-web-app/bundles/role_access/schema.yaml

@@ -0,0 +1,59 @@
+# Declarative translation of role_access/schema.py. Defaults are documented
+# because schema.yaml validates writes but does not materialize Pydantic defaults.
+type: object
+additional_properties: false
+required: [schema_version]
+properties:
+  schema_version: { knowledge: { role: metadata }, type: enum, values: [5] }
+  title: { type: string }          # default ""
+  summary: { type: string }        # default ""
+  roles:
+    type: map
+    value:
+      type: object
+      additional_properties: false
+      required: [id, title]
+      properties:
+        id: { type: string }
+        title: { type: string }
+        assignment_rule: { type: string } # default ""
+  role_order:
+    knowledge: { role: metadata }
+    type: array
+    items: { type: string }
+  # Optional: absence or an empty map retains the original flat role model.
+  # One canonical child -> parent edge; roles never store a second parent_ref.
+  inheritances:
+    type: map
+    value:
+      type: object
+      additional_properties: false
+      required: [id, title, kind, source, target]
+      properties:
+        id: { type: string }
+        title: { type: string }
+        kind: { type: enum, values: [inherits] }
+        source: { type: string, knowledge: { role: reference, target: '#/roles' } }
+        target: { type: string, knowledge: { role: reference, target: '#/roles' } }
+        description: { type: string }
+  policies:
+    type: map
+    value:
+      type: object
+      additional_properties: false
+      required: [id, title]
+      properties:
+        id: { type: string }
+        title: { type: string }
+        role_ref: { type: string, knowledge: { role: reference, target: '#/roles' } } # default ""
+        capability: { type: string }        # default ""
+        effect: { type: enum, values: [allow, deny] } # default allow
+        applies_when: { type: string }      # default ""
+        requirements:
+          type: array
+          items: { type: enum, values: [confirm, reauthenticate, custom] }
+        custom_requirement: { type: string } # default ""
+  policy_order:
+    knowledge: { role: metadata }
+    type: array
+    items: { type: string }