opencode-skills-collection 3.1.0 → 3.1.2

package/bundled-skills/yao-meta-skill/references/skill-engineering-method.md

@@ -0,0 +1,210 @@
+# Skill Engineering Method
+
+This doctrine defines the default method for turning messy workflow material into a reusable skill without bloating the entrypoint.
+
+## Core Loop
+
+1. Decide whether the request should become a skill at all.
+2. Run a short intent dialogue to capture the real job, outputs, exclusions, and constraints.
+3. Choose the smallest viable archetype.
+4. Set one clear capability boundary.
+5. Write and test the trigger description before expanding the body.
+6. Apply authoring discipline: name unresolved assumptions, keep scope small, and tie meaningful changes to checks.
+7. Add an output risk profile for user-facing artifacts.
+8. Add an artifact design profile for reports, tutorials, viewers, dashboards, screenshots, and visual pages.
+9. Add only the gates that match the risk.
+10. Ship the first routeable package, then pick the three highest-value next iteration directions.
+11. Package and govern the skill only as far as real reuse demands.
+
+## Phase 1: Qualification
+
+Promote a request into a skill only when at least one of these is true:
+
+- the workflow will be reused
+- the workflow is easy to route incorrectly
+- deterministic scripts reduce repeated effort
+- governance or portability matters
+
+Reject skill creation when the request is only:
+
+- explanation
+- summary
+- translation
+- brainstorming
+- documentation without agent execution
+- a one-off answer with no reuse value
+
+See [Non-Skill Decision Tree](non-skill-decision-tree.md).
+
+## Phase 1.5: Authoring Discipline
+
+Before expanding the package, apply the execution discipline that keeps the work grounded.
+
+- clarify only the assumptions that change the package design
+- do not add speculative features, generic configurability, or decorative structure
+- when editing an existing skill, touch only files that directly serve the requested change
+- connect each meaningful change to a check: route evidence, sample run, resource-boundary check, governance check, or reviewer note
+
+See [Authoring Discipline](authoring-discipline.md).
+
+## Phase 1.6: Problem Diagnosis
+
+When the user gives a fuzzy pain point instead of a clear skill request, diagnose the likely package shape before asking for structure.
+
+- infer whether the need is best served by a scaffold, production workflow, library capability, governed asset, or no skill
+- recommend at most three candidate directions
+- explain why each candidate fits, where it is limited, and what the first light version should prove
+- prefer a concrete recommendation over a menu when the intent is clear enough
+
+This keeps discovery useful for users who can describe the problem but not the skill architecture.
+
+## Phase 2: Intent Dialogue
+
+Before deep authoring, ask only the questions that change the package design.
+
+- open with a human, teacher-like framing rather than a cold field list
+- let the user answer naturally first; offer a tiny template only as an optional shortcut
+- what recurring job should the skill own
+- what real inputs will users hand to it
+- what outputs must it produce
+- what near-neighbor requests should stay out of scope
+- whether the user has reference systems, repos, or products worth learning from
+- what constraints matter: privacy, naming, portability, governance, or local fit
+
+See [Intent Dialogue](intent-dialogue.md).
+
+## Phase 3: Archetype Selection
+
+Choose the lightest archetype that fits the job.
+
+- `Scaffold`: exploratory, personal, or short-lived
+- `Production`: team-reused, quality-sensitive, but still compact
+- `Library`: broad reuse, visible evidence, portability, and maintenance expectations
+- `Governed`: organizationally sensitive or operationally critical; lifecycle and review are explicit
+
+See [Skill Archetypes](skill-archetypes.md).
+
+## Phase 4: Boundary Design
+
+Every skill should answer four questions clearly:
+
+- what recurring job does it own
+- what outputs does it produce
+- what near-neighbor requests should not route here
+- what detail belongs outside `SKILL.md`
+
+Boundary work comes before polishing prose.
+
+## Phase 5: Reference Scan
+
+Run a short benchmark pass before deep authoring.
+
+- scan `3-5` reference objects at most
+- prioritize high-star external GitHub and official benchmark sources first
+- ask for user-supplied references second, but extract only patterns and standards
+- use local files third, only for fit, privacy, and compatibility calibration
+- choose from method, structure, execution, portability, and domain patterns
+- extract only what passes the pattern test: recurrence, generativity, distinctiveness, and boundary clarity
+- record what not to borrow so the new skill stays light
+
+See [Reference Scan Strategy](reference-scan.md) and [Pattern Extraction Doctrine](pattern-extraction-doctrine.md).
+
+## Phase 5.5: Output Risk Profiling
+
+Before treating the package as usable, predict the likely mistakes in its final user-facing output.
+
+- tutorial skills should guard against generic headings, vague examples, and missing success checks
+- report and Markdown skills should guard against weak tables, dense lists, and poor hierarchy
+- screenshot or visual skills should guard against wrong captures, missing assets, and invented visual evidence
+- research or citation-heavy skills should guard against footnote clutter and unsupported claims
+- code or command skills should guard against hidden cwd, input, output, and side-effect assumptions
+
+Generate `reports/output-risk-profile.md` and expose it to the reviewer before adding more structure.
+
+See [Output Quality Risk](output-quality-risk.md).
+
+## Phase 5.6: Artifact Design Profiling
+
+Before approving generated reports or visual outputs, define how the artifact should read and scan.
+
+- choose the artifact family: tutorial, report, review viewer, dashboard, visual evidence, slide-like narrative, or code/CLI guide
+- let the content choose the visual system instead of copying a fixed house style
+- borrow document discipline from Kami: route by document type, distill content, verify layout-critical assumptions
+- borrow slide discipline from presentation skills: plan hierarchy, density, rhythm, and quality gates before writing HTML
+- reject generic headings, noisy citations, weak tables, wrong screenshots, repeated card grids, and decorative visual defaults
+
+Generate `reports/artifact-design-profile.md` and expose it in the overview and review viewer.
+
+See [Artifact Design Doctrine](artifact-design-doctrine.md) and [Output Visual Quality](output-visual-quality.md).
+
+## Phase 5.7: Prompt Quality Profiling
+
+When a skill depends on prompt behavior, role design, dialogue quality, or output contracts, turn prompt methodology into an evidence profile.
+
+- identify the explicit need, implicit need, scenario, user level, and success standard
+- map Role, Task, and Format into skill behavior instead of copying a full meta-prompt into `SKILL.md`
+- classify the task family and complexity before adding structure
+- score completeness, clarity, consistency, practicality, and specificity
+- expose the full reasoning to reviewers while keeping the user-facing flow recommendation-led
+
+Generate `reports/prompt-quality-profile.md` and expose it in the overview and review viewer.
+
+See [Prompt Engineering Doctrine](prompt-engineering-doctrine.md).
+
+## Phase 6: Trigger-First Authoring
+
+Author the frontmatter `description` before expanding the body.
+
+- start with the recurring job
+- include the trigger actions that should route here
+- include exclusions when confusion is plausible
+- test the route before growing the file tree
+
+Trigger quality is improved through:
+
+- `trigger_eval.py`
+- `optimize_description.py`
+- blind holdout
+- judge-backed blind holdout
+- adversarial holdout
+- route confusion
+
+## Phase 7: Gate Selection
+
+Add gates by risk, not by habit.
+
+- low-risk scaffolds: validate structure and context size
+- production skills: trigger eval plus resource-boundary checks
+- library skills: description optimization, route confusion, packaging checks
+- governed skills: governance scoring, lifecycle metadata, regression history
+
+See [Gate Selection](gate-selection.md).
+
+## Phase 8: First Iteration Philosophy
+
+The first package is a routeable baseline, not the final answer.
+
+- improve trigger and exclusions before growing prose
+- add one execution asset before adding many documents
+- surface the three highest-value next moves so authors do not expand in every direction at once
+- prefer the smallest step that increases reliability more than context cost
+- move unverifiable ideas into next-step candidates instead of shipping them as baseline structure
+
+See [Iteration Philosophy](iteration-philosophy.md) and [Authoring Discipline](authoring-discipline.md).
+
+## Phase 9: Promotion
+
+A candidate route or package is promotable only when:
+
+- visible holdout does not regress
+- blind holdout does not regress
+- judge-backed blind holdout does not regress
+- adversarial holdout does not regress
+- route confusion stays clean
+- context and governance gates still pass
+
+See [Promotion Policy](../evals/promotion_policy.md).
+
+## Design Principle
+
+The method is only correct if rigor grows faster than context cost. If a new check or document makes the skill heavier without making it more reliable, remove or relocate it.

package/bundled-skills/yao-meta-skill/references/skill-ir-method.md

@@ -0,0 +1,41 @@
+# Skill IR Method
+
+Skill IR is the 2.0 layer that separates durable skill meaning from platform packaging.
+
+## Purpose
+
+Use Skill IR before platform-specific packaging for production, library, governed, or team-distributed skills. The IR should preserve the capability contract even when OpenAI, Claude, Agent Skills, VS Code, or generic adapters differ in folder layout, metadata names, or activation behavior.
+
+## What Belongs In IR
+
+- the recurring job the skill owns
+- the frontmatter trigger description
+- should-trigger, should-not-trigger, and near-neighbor edge cases
+- workflow steps, decision points, and failure modes
+- references, scripts, assets, and reports used by the package
+- trigger and output eval plans
+- output risk, execution risk, and trust boundary
+- owner, maturity, review cadence, and target platforms
+
+## What Does Not Belong In IR
+
+- platform-specific file paths that only exist after packaging
+- copied prose from external benchmarks
+- client-specific UI labels
+- local private paths that are not part of the skill package
+- speculative adapters that are not requested or tested
+
+## Authoring Rule
+
+Export or update Skill IR before adding new adapters, compilers, registries, or conformance checks. If a field cannot be derived from local package evidence, leave it empty or use an explicit low-confidence default instead of inventing detail.
+
+## Reviewer Gate
+
+A reviewer should be able to answer:
+
+1. What does this skill own?
+2. When should it trigger?
+3. When should it not trigger?
+4. Which resources and scripts carry the real behavior?
+5. Which evals prove the contract?
+6. Which targets can consume the skill without semantic loss?

package/bundled-skills/yao-meta-skill/references/skillops-decision-policy.md

@@ -0,0 +1,53 @@
+# SkillOps Decision Policy
+
+Use this policy when turning explicit-source conversation evidence into SkillOps opportunities, proposals, or release work. The goal is to make repeated user signals actionable without letting automation write durable instructions, skills, scripts, or evals without review.
+
+## Decision Order
+
+1. Classify the signal as no action, report only, Memory, AGENTS.md, existing Skill patch, candidate Skill, script, eval, report, merge, split, or archive.
+2. Prefer the smallest durable surface that fixes the repeated friction.
+3. Require evidence for every write action.
+4. Require a proposal or approval ledger entry before any source-file write.
+5. Map every proposed change to at least one verification command.
+
+## Score Bands
+
+SkillOps opportunities use a `0-100` score. Scores are advisory and never bypass approval.
+
+| Score | Decision |
+| ---: | --- |
+| `85-100` | Ready for approval review |
+| `70-84` | Proposal review |
+| `50-69` | Observe more evidence |
+| `0-49` | Report only or no action |
+
+High-risk items stay proposal-only even when their score is high.
+
+## Action Mapping
+
+| Pattern | Default Action | Durable Surface |
+| --- | --- | --- |
+| `language_default` | Patch existing skill | Report template or artifact doctrine |
+| `report_ui` | Patch existing skill | Report renderer, artifact doctrine, visual test |
+| `approval_safety` | AGENTS update | Governance guidance or approval policy |
+| `delivery_format` | Patch existing skill | CLI output, README, generated summary copy |
+| `evidence_testing` | Add eval | Focused regression, report-quality, or release gate |
+| Unknown pattern | Report only | Manual review queue |
+
+## Safety Rules
+
+- Do not scan private logs implicitly; only use explicit user-supplied sources.
+- Do not store raw conversation content in reports; use redacted excerpts and aggregate counts.
+- Do not write source files from a daily report run.
+- Do not count SkillOps reports as public world-class evidence.
+- Do not treat planned work, draft submissions, or generated proposals as accepted evidence.
+
+## Verification
+
+Every implementation that changes this policy should run:
+
+```bash
+python3 tests/verify_skillops_opportunity.py
+python3 tests/verify_daily_skillops.py
+python3 tests/verify_yao_cli.py
+```

package/bundled-skills/yao-meta-skill/references/systems-thinking-doctrine.md

@@ -0,0 +1,75 @@
+# Systems Thinking Doctrine
+
+Use this doctrine when a skill needs to keep producing good behavior after repeated real use.
+
+## Core Principle
+
+Structure drives behavior. Improve the system boundary, feedback loops, drift watch, and leverage points before adding more prose, templates, or tools.
+
+This is inspired by general systems-thinking practice: recurring failures usually come from structure, incentives, feedback, delays, or boundary mistakes rather than from one isolated bad output.
+
+## Apply Silently By Default
+
+Use the systems model as author and reviewer evidence. Do not ask the user to choose between system concepts unless there is real uncertainty or a design conflict.
+
+The user should usually see a recommendation, not a menu of theory.
+
+## Four Questions
+
+1. What does this skill own?
+2. What feedback tells us it is improving or drifting?
+3. Which failure will appear only after repeated use?
+4. Where is the smallest change with the largest quality gain?
+
+## Boundary Map
+
+Define these before expanding the package:
+
+- Owned job: the recurring behavior this skill is responsible for.
+- Input boundary: the real material users will provide.
+- Output boundary: the concrete hand-back users need.
+- Non-goals: adjacent requests this skill should refuse or hand off.
+- Human judgment boundary: places where the model should ask, escalate, or disclose uncertainty.
+
+## Feedback Loops
+
+Every serious skill should have at least one loop:
+
+- Intent loop: user clarification changes the boundary.
+- Reference loop: benchmark patterns become borrow or avoid guidance.
+- Output loop: common output failures become self-repair checks.
+- Reviewer loop: human feedback becomes a gate, reference, or regression case.
+- Lifecycle loop: reuse level changes maturity tier and governance.
+
+## Delay And Drift
+
+Watch for problems that appear after initial success:
+
+- Trigger drift: the skill starts activating on adjacent work.
+- Output drift: outputs become generic, cluttered, or misaligned.
+- Reference drift: borrowed patterns add ceremony without payoff.
+- Governance drift: team-critical use grows faster than review discipline.
+
+## Leverage Points
+
+Prefer changes in this order:
+
+1. Clarify the real job boundary.
+2. Tune the frontmatter description.
+3. Add one output self-repair check.
+4. Borrow one external pattern as structure, not surface style.
+5. Close one lifecycle or reviewer feedback loop.
+
+Do not add more files if a description, boundary, or feedback-loop change would solve the root cause.
+
+## Reviewer Standard
+
+A reviewer should ask: will this skill's structure keep producing the desired behavior after repeated use?
+
+If the answer is unclear, request one of these before approving:
+
+- a sharper boundary
+- a named feedback loop
+- a drift watch
+- a failure pattern
+- a highest-leverage next move

package/bundled-skills/yao-meta-skill/references/telemetry-drift-method.md

@@ -0,0 +1,182 @@
+# Telemetry And Drift Method
+
+Telemetry turns real use into the next iteration queue. It must stay local-first and metadata-only by default.
+
+## When To Use
+
+Use the telemetry drift loop when a skill is production, library, governed, team-distributed, or repeatedly invoked by more than one workflow.
+
+Do not collect raw prompts, model outputs, transcripts, notes, messages, or private files. If a reviewer needs examples, store anonymized fixtures separately and cite them as eval evidence, not telemetry.
+
+## Event Contract
+
+The local event stream is `reports/telemetry_events.jsonl`. It is intentionally narrow:
+
+```json
+{
+  "event": "skill_activation",
+  "skill": "example-skill",
+  "version": "2.0.0",
+  "source": "yao_cli",
+  "command": "quickstart",
+  "activation_type": "implicit",
+  "outcome": "accepted",
+  "failure_type": "none",
+  "timestamp": "2026-06-13T10:00:00Z"
+}
+```
+
+Allowed events: `skill_activation`, `skill_output`, `script_run`, `review_event`.
+
+Allowed sources: `manual`, `yao_cli`, `external`, `unknown`.
+
+Allowed outcomes: `accepted`, `edited`, `rejected`, `missed`, `failed`, `reviewed`, `unknown`.
+
+Allowed failure types: `wrong_trigger`, `under_trigger`, `bad_output`, `missing_resource`, `script_error`, `review_overdue`, `none`.
+
+`source` and `command` are metadata fields. They may identify that `yao.py` ran `quickstart`, `validate`, `output-exec`, or another subcommand, but they must not include arguments, prompt text, file content, model output, transcripts, or reviewer notes.
+
+## CLI Capture
+
+`scripts/yao.py` can record metadata-only `script_run` events automatically. It is opt-in to keep release evidence reproducible and avoid surprising local writes:
+
+```bash
+YAO_CLI_TELEMETRY=1 python3 scripts/yao.py validate .
+```
+
+Optional destination override:
+
+```bash
+YAO_CLI_TELEMETRY=1 \
+YAO_CLI_TELEMETRY_EVENTS=/tmp/yao-telemetry.jsonl \
+python3 scripts/yao.py output-exec
+```
+
+Equivalent global flags are available before the subcommand:
+
+```bash
+python3 scripts/yao.py --record-cli-telemetry validate .
+python3 scripts/yao.py --no-cli-telemetry validate .
+```
+
+Successful CLI runs record `event=script_run`, `source=yao_cli`, `outcome=accepted`, and `failure_type=none`. Failed CLI runs record `outcome=failed` and `failure_type=script_error`. The command name is normalized to the subcommand only; command arguments are never recorded.
+
+## External Client Emit
+
+External clients, browser extensions, editor adapters, or wrapper scripts can emit one sanitized event at a time into a local spool before importing it into the aggregate drift report:
+
+```bash
+python3 scripts/yao.py telemetry-emit . \
+  --event skill_activation \
+  --activation-type explicit \
+  --outcome accepted \
+  --command browser-extension
+```
+
+By default this writes to `.yao/telemetry_spool/external_events.jsonl`. Use `--output-jsonl` when a client needs a different local handoff path:
+
+```bash
+python3 scripts/yao.py telemetry-emit . \
+  --output-jsonl /tmp/external-client-events.jsonl \
+  --event skill_output \
+  --activation-type manual \
+  --outcome edited \
+  --command browser-plugin
+```
+
+Use `--dry-run` to validate a proposed event without writing to the spool. The emitter uses the same metadata-only contract as import: no prompt, input, output, transcript, message, note, raw text, arguments, or unknown fields are accepted.
+
+After a client finishes a batch, import the spool:
+
+```bash
+python3 scripts/yao.py telemetry-import . --input-jsonl .yao/telemetry_spool/external_events.jsonl
+```
+
+## Client Hook Recipes
+
+Use `telemetry-hooks` to generate auditable Browser, Chrome, VS Code, CLI wrapper, and provider-adapter hook recipes:
+
+```bash
+python3 scripts/yao.py telemetry-hooks .
+```
+
+The report is written to:
+
+- `reports/telemetry_hook_recipes.json`
+- `reports/telemetry_hook_recipes.md`
+
+Each recipe includes a dry-run command, an emit command, the target local spool, trigger points, and the privacy contract. The report intentionally sets `native_auto_capture=false`; it proves the local hook contract and metadata-only command shape, not that a host client is already natively integrated.
+
+## Browser Native Host
+
+`scripts/telemetry_native_host.py` implements the local side of Browser/Chrome Native Messaging. It accepts length-prefixed JSON messages on stdio, validates them with the same metadata-only telemetry contract, appends accepted events to the local spool, and rejects raw prompt/output/transcript/message/note fields.
+
+Smoke-test one message without Browser installation:
+
+```bash
+python3 scripts/telemetry_native_host.py . \
+  --message-json '{"event":"skill_activation","activation_type":"explicit","outcome":"accepted","failure_type":"none","command":"chrome-native-host"}'
+```
+
+Generate a local launcher and Chrome native messaging manifest for an operator-installed extension:
+
+```bash
+python3 scripts/telemetry_native_host.py . \
+  --write-launcher /tmp/yao-telemetry-host.sh \
+  --write-manifest /tmp/yao-telemetry-host.json \
+  --allowed-origin chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/
+```
+
+This is an executable native host bridge and manifest generator. It still does not prove that a specific Browser/Chrome extension is installed or sending events in the user's environment.
+
+## External Client Import
+
+External clients, browser extensions, editor adapters, or wrapper scripts may hand off already-sanitized JSONL through `telemetry-import`:
+
+```bash
+python3 scripts/yao.py telemetry-import . \
+  --input-jsonl /tmp/external-client-events.jsonl \
+  --command browser-extension
+```
+
+The importer defaults missing `source` to `external` and missing `command` to `external-client`. It validates the entire JSONL file before writing anything. If any line includes a raw content field, unsupported source, unsupported outcome, unsupported failure type, unknown field, malformed JSON, or an unsafe command name, the whole import is rejected and the existing local event stream is left untouched.
+
+Use `--dry-run` to validate an external batch without writing `reports/telemetry_events.jsonl` or refreshing aggregate reports:
+
+```bash
+python3 scripts/yao.py telemetry-import . --input-jsonl /tmp/external-client-events.jsonl --dry-run
+```
+
+## Privacy Rule
+
+The raw JSONL event log is local evidence and should not be distributed in skill packages. The distributable artifact is the aggregate report:
+
+- `reports/adoption_drift_report.json`
+- `reports/adoption_drift_report.md`
+
+Package builders should exclude `reports/telemetry_events.jsonl`. The root repository also ignores this raw event stream so local usage evidence does not become ordinary source history by accident.
+
+## Release Interpretation
+
+- `no-data`: acceptable for a first scaffold, but a warning for governed release review.
+- `low`: events exist and no drift failure signal is present.
+- `medium`: at least one missed trigger, wrong trigger, bad output, script error, or overdue review signal exists.
+- `high`: several drift signals are present; convert them into eval cases or governance actions before calling the skill release-ready.
+
+## Iteration Loop
+
+1. Capture metadata-only events locally, either manually with `adoption-drift --record-event`, automatically with opt-in `yao.py` CLI capture, through `telemetry-emit` client hooks, through generated `telemetry-hooks` client recipes, or through validated external JSONL import.
+2. Render `reports/adoption_drift_report.md`.
+3. Convert missed triggers into trigger eval cases.
+4. Convert bad outputs into Output Eval assertions and failure taxonomy entries.
+5. Convert script errors into non-interactive smoke tests.
+6. Feed review-overdue signals back into Skill Atlas and owner review.
+7. Let Skill Atlas read only `reports/adoption_drift_report.json` and publish portfolio-level `skill_atlas/drift_signals.json`.
+
+## Review Studio Role
+
+Review Studio should show the aggregate telemetry gate as an operating loop, not as raw logs. A blocker means the telemetry contract was violated. A warning means the evidence is absent or the drift signal needs a follow-up case.
+
+## Skill Atlas Role
+
+Skill Atlas uses aggregate adoption drift reports to rank portfolio work. It should surface no-data warnings for actionable production/library/governed skills, and drift warnings for missed triggers, wrong triggers, bad outputs, missing resources, script errors, and review-overdue counts. It must not inspect raw JSONL telemetry or use non-actionable example/fixture signals as release blockers.

package/bundled-skills/yao-meta-skill/references/trust-security-method.md

@@ -0,0 +1,79 @@
+# Trust Security Method
+
+Trust checks make skills safer to install and review, especially when they include scripts or are distributed to a team.
+
+## When To Run
+
+Run the trust report when:
+
+- the skill contains scripts
+- the skill will be shared with a team
+- the package may be installed from a registry or plugin
+- the skill reads external files, uses network access, or shells out
+- the maturity tier is library or governed
+
+## V0 Checks
+
+- obvious secret patterns
+- script help surface and interactive prompts
+- execution-level `--help` smoke checks
+- dependency pinning
+- runtime trust metadata
+- network-capable scripts
+- bounded host policy for network-capable scripts
+- reviewer-approved permission policy for high-permission capabilities
+- packaged-target runtime permission probes for adapter contracts and metadata fallback limits
+- source-contract integrity digest
+
+## Script Interface Rule
+
+Every Python file under `scripts/` is reviewed as part of the package trust surface.
+
+- CLI scripts should use `argparse` so reviewers and installers can run `python3 scripts/name.py --help` before execution.
+- The trust report executes `python3 scripts/name.py --help` for CLI scripts with `argparse`, with a short timeout, and records pass/fail evidence.
+- Import-only modules should declare `SCRIPT_INTERFACE = "internal-module"` near the top of the file.
+- Internal modules should also declare `SCRIPT_INTERFACE_REASON` with a short explanation of which CLI or renderer imports them.
+- The trust report keeps internal modules in the script inventory, but excludes them from CLI help-surface warnings.
+- A Python file without an explicit internal-module declaration is treated as a CLI script by default.
+- CLI scripts without `argparse` are not smoke-executed; they remain visible as help-surface warnings.
+
+## Network Policy Rule
+
+Network-capable scripts must be bounded by a machine-readable policy before team distribution.
+
+- Put the policy in `security/network_policy.json`.
+- Add one entry per network-capable script under `scripts`.
+- Declare `allowed_hosts`, `allowed_path_prefixes`, purpose, timeout, auth mode, and custom-host behavior.
+- Default to HTTPS-only and deny custom hosts unless a CLI flag or environment variable makes the override explicit.
+- The trust report compares HTTPS URL literals in each script with `allowed_hosts`; missing or mismatched entries remain reviewer-visible warnings.
+
+## Permission Approval Rule
+
+High-permission capabilities must be approved before governed release.
+
+- Put approvals in `security/permission_policy.json`.
+- Cover each required capability detected by the trust report: `network`, `file_write`, `subprocess`, and `interactive` when present.
+- Each approval must include `decision: approved`, `reviewer`, `scope`, `reason`, `expires_at`, `evidence`, and `target_enforcement`.
+- Review Studio surfaces these checks as the `permission-gates` gate.
+- Missing, invalid, or expired approvals block governed mode. They remain visible warnings in lighter modes.
+
+## Runtime Permission Probe Rule
+
+Permission approval validates reviewer intent. Runtime permission probes validate the generated target adapters after packaging.
+
+- Run `python3 scripts/probe_runtime_permissions.py . --package-dir dist` after `cross_packager.py`.
+- The probe writes `reports/runtime_permission_probes.json` and `reports/runtime_permission_probes.md`.
+- A passing probe requires every target adapter to carry `permission_contract`, `target_permission_contract`, declared capabilities, a native-enforcement boolean, representation notes, and operator notes.
+- When `reports/install_simulation.json` matches the same package directory, the probe also reports installer enforcement counts from the install simulation. This proves the local package installer gate is wired, but it does not count as target-client native enforcement.
+- If a target has no native enforcement, the probe must mark an explicit metadata fallback and keep residual risk reviewer-visible.
+- Review Studio surfaces this as the `permission-runtime` gate.
+
+## Release Rule
+
+High-risk secrets or unrestricted remote inline execution block governed release. Warnings are reviewer-visible but do not block v0 unless the release owner decides the target environment requires stricter policy.
+
+## Hash Scope
+
+`package_sha256` is a stable source-contract digest, not a generated archive digest. It covers the skill entrypoint, metadata, scripts, references, evals, runtime, templates, security notes, Skill IR, and root control files. It deliberately excludes generated `reports/`, packaged `dist/` archives, and raw local telemetry so a report render or local adoption log cannot mutate the trust fingerprint.
+
+Use the package verification or registry audit report for the distributable archive checksum.

package/bundled-skills/yao-meta-skill/references/user-memory-policy.md

@@ -0,0 +1,35 @@
+# User Memory Policy
+
+This skill treats user preference memory as local, explicit, and reviewable.
+
+## Principles
+
+- **Explicit source only**: adaptive scans require a user-provided file path.
+- **Local first**: no network access is needed for preference extraction.
+- **No implicit private logs**: shell history, browser history, mail, and hidden chat logs are blocked by default.
+- **Repeated signals only**: one-off statements are recorded as discarded signals unless they meet the configured support threshold.
+- **Redacted evidence**: stored excerpts must remove secrets, tokens, email addresses, and local absolute paths.
+- **Proposal before patch**: preference memory can generate proposals, not automatic source edits.
+
+## Allowed Inputs
+
+Recommended inputs are curated JSONL, Markdown, or text files prepared for review. JSONL records should use a field such as `text`, `message`, `content`, `excerpt`, `prompt`, `note`, or `body`.
+
+## Blocked By Default
+
+The scanner refuses common shell history files such as `.zsh_history`, `.bash_history`, and `.fish_history` unless an explicit override is added for a controlled test. Even with an override, the output remains redacted and proposal-only.
+
+## Retention
+
+Generated reports store only summarized patterns and short redacted excerpts. They should not be treated as a full transcript, chat archive, or durable personal memory store.
+
+## Upgrade Path
+
+A future patch-application stage must add:
+
+- human approval ledger;
+- allowlisted target files;
+- dry-run diffs;
+- regression command execution;
+- rollback artifacts;
+- reviewer-visible audit trail.