@rpamis/comet 0.3.9 → 0.4.0-beta.2

package/assets/skills/comet-any/reference/eval-provider.md

@@ -0,0 +1,83 @@
+# Eval Evidence Reference
+
+## Eval choices
+
+Before any verification action, show:
+
+- `quick` estimated runs, covered components, and token workload.
+- `full` estimated runs, covered components, and token workload.
+- the three choices: `skip / quick / full eval`.
+
+If eval is skipped, fails, or records stale-hash evidence, do not enter ready; do not publish or distribute.
+
+For ordinary users, the verification path remains single-purpose: daily evaluation goes through
+`comet eval`. `/comet-any` may internally record eval evidence, but must not present the internal
+recording step as a replacement user-facing command.
+For ordinary users, prefer the word "verify" when explaining; do not surface `Publish readiness:`
+as a first-class concept.
+
+## Result recording
+
+Eval evidence must produce structured JSON with at least:
+
+- the current draft hash.
+- covered entry Skill and internal Node Skills.
+- `workflow-protocol.json` hash.
+- quick or full choice, token workload, and result summary.
+- Bundle compile, safety check, and capability evidence.
+
+Only current draft hash eval evidence can advance state. Stale eval evidence may remain on disk for
+audit, but cannot make the current draft ready.
+
+## Human review
+
+Passing eval still requires human approval. The review summary must include at least:
+
+First run `comet publish review <name> --platform <reference-platform> --json`, then use its
+output to show:
+
+- Bundle name, version, and hash.
+- Multiple entry and internal Skill lists.
+- `planHash`, `preferenceHash`, and `reference/resolved-skills.json` real Skill evidence,
+  including project-level preference mode, required Skills, `sourceSummaries`, and the composed
+  workflow summary.
+- Recommended call order and `preferenceIndex`.
+- Every item that deviates from the preferred order, plus the reason.
+- Whether `.comet/skill-preferences.yaml` drifted after Factory initialization; `advisory` mode
+  warns, while `strict` mode blocks.
+- Whether the stable composed Skill Bundle required capability set
+  `skills/scripts/rules/hooks/references` is complete, and whether `scripts/rules/hooks` remain
+  the required control plane.
+- Whether `comet/skill.yaml`, `comet/guardrails.yaml`, `comet/checks.yaml`, and `comet/eval.yaml`
+  were generated.
+- Whether `hooks/*.yaml` are treated only as portable hook descriptors until
+  `comet publish distribute` compiles them for the target platform.
+- Capability gaps and executable disclosures.
+- eval choice, token workload, and result summary.
+- `Validate this Skill` and the next action so the user knows why the candidate can become ready
+  or is blocked.
+
+Readiness blockers stop publishing. If missing current draft hash eval evidence, missing human
+approval, required capability gaps, or unconfirmed executable disclosures remain, the flow must stop
+in review and cannot continue to publish.
+
+Only after explicit user approval may the agent run `comet publish approve` and publish.
+
+## Install preview
+
+Before real distribution, preview is mandatory:
+
+```bash
+comet publish distribute <name> --platform <id> --scope project --preview --json
+```
+
+Preview is a required check, not an optional extra. It should show:
+
+- `Install preview`
+- planned files
+- unsupported capability
+- executable disclosures
+- `No files were written`
+
+Only after the user confirms the preview result may the Skill remove `--preview` and execute real
+distribution.

package/assets/skills/comet-any/reference/subagents/pause-points-author.md

@@ -0,0 +1,75 @@
+# Pause Point Author Subagent
+
+This file is a portable lane brief, not a platform-native custom agent. If you need a Claude Code custom agent, generate a separate platform agent resource with frontmatter.
+
+## Responsibilities
+
+Design the places where the user must pause and choose, plus cross-device recovery. Pause points must be explicit user choices that cannot be bypassed by default recommendations, historical preferences, or automatic advancement.
+
+Must cover:
+
+- `reference/decision-points.md`
+- `reference/recovery.md`
+
+## Inputs
+
+Read the common input from the main session, especially:
+
+- `confirm-generate`, `revise-proposal`, and `cancel` from the Skill Creator confirmation page.
+- Eval workload choice: `skip / quick / full eval`.
+- Human approval before installation.
+- Blockers such as unresolved candidates, ambiguity, capability gaps, and executable disclosures.
+- Runner recovery state and cross-device recovery entry.
+
+Use file handoff: the main session provides paths instead of pasting large bodies of text. Do not inherit main-session history; use only this brief, common input, workflow protocol, and existing drafts.
+
+## Dispatch Template
+
+Use the current platform's subagent mechanism. The shape should include:
+
+```text
+description: "Design user pause points and recovery for <bundle-name>"
+model: <must explicitly specify model>
+prompt:
+  You are the pause point author subagent.
+  First read this brief, the common input path, workflow protocol path, Skill draft path, and report file path.
+  Start by asking questions: if user choices, blocker recovery, or cross-device state are unclear, return NEEDS_CONTEXT.
+  Do not guess or fill in missing pause points.
+  Only produce decision-points and recovery drafts; do not write Bundle state and do not execute candidate scripts.
+  Write the full pause point draft to the report file path and return only a status summary of 15 lines or fewer.
+```
+
+## Output Requirements
+
+Return a pause point draft that explains:
+
+- The trigger condition for every pause point.
+- The choices available to the user.
+- Which Node each choice enters.
+- Where pause point evidence is written.
+- During recovery, how to show current Node, blocking reason, suggested next step, and options.
+
+Pause points must fit the current workflow protocol, not merely list original Comet pause points.
+
+## Self-Check
+
+Before returning, check:
+
+- Every user pause point has trigger condition, options, next Node, and evidence location.
+- Default recommendations, historical preferences, and automatic advancement cannot bypass required pause points.
+- The recovery summary can show current Node, blocking reason, suggested next step, and options.
+- Cross-device recovery does not rely on current-session memory.
+- Pause points fit the current composed Skill instead of copying original Comet pause points.
+
+## Required Claims
+
+- `pause:decision-points`
+- `pause:recovery`
+
+Missing any claim must block Skill review.
+
+## Status Return
+
+Status must be one of `DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, or `BLOCKED`.
+
+Write the full report to the report file path. The summary returned to the main session must be 15 lines or fewer and include status, report path, claims, unresolved concerns, and recovery risks. If status is `BLOCKED` or `NEEDS_CONTEXT`, state exactly what context is missing, what was tried, and what the main session should do.

package/assets/skills/comet-any/reference/subagents/reference-author.md

@@ -0,0 +1,77 @@
+# Reference Author Subagent
+
+This file is a portable lane brief, not a platform-native custom agent. If you need a Claude Code custom agent, generate a separate platform agent resource with frontmatter.
+
+## Responsibilities
+
+Write and organize the generated Skill's reference layer so audit, recovery, review, and future maintenance have real evidence. The reference layer holds evidence; it does not stuff internal audit content into user-visible `SKILL.md`.
+
+Must cover:
+
+- `reference/workflow-protocol.json`
+- `reference/resolved-skills.json`
+- `reference/composition-report.md`
+- `reference/authoring-lanes.json`
+
+## Inputs
+
+Read the common input from the main session, especially:
+
+- Resolved Skill name, source, description, hash, references, rules, scripts, and hooks.
+- `sourceSummaries`, which must come from real `SKILL.md` bodies and direct references.
+- Project preferences, missing or ambiguous candidate handling, deviation reasons, and executable disclosures.
+- The five-phase Comet semantics preserved when users customize existing Comet Skills.
+
+Use file handoff: the main session provides paths instead of pasting large bodies of text. Do not read main-session history, and do not copy entire source Skills into reference.
+
+## Dispatch Template
+
+Use the current platform's subagent mechanism. The shape should include:
+
+```text
+description: "Organize reference evidence for <bundle-name>"
+model: <must explicitly specify model>
+prompt:
+  You are the reference author subagent.
+  First read this brief, the common input path, resolved skills path, workflow protocol path, and report file path.
+  Start by asking questions: if source evidence, hashes, preference decisions, or executable disclosures are unclear, return NEEDS_CONTEXT.
+  Do not guess or fill in missing sources.
+  Only produce reference drafts and claims; do not write Bundle state and do not execute candidate scripts.
+  Write the full reference draft to the report file path and return only a status summary of 15 lines or fewer.
+```
+
+## Output Requirements
+
+Return a reference draft that explains:
+
+- Each workflow protocol Node's goal, guard, next-Node condition, and recovery point.
+- How resolved Skill evidence supports the composed flow.
+- Where composition matches user preferences, where it deviates, and why.
+- Which content belongs in the user-visible flow and which content stays in the reference audit layer.
+
+Do not turn reference into copied source Skill prose. Distill it into evidence and protocol that the composed Skill can use.
+
+## Self-Check
+
+Before returning, check:
+
+- Every source summary traces back to a real `SKILL.md` or direct reference.
+- The workflow protocol explains Node goals, guards, automatic advancement, and recovery.
+- Preferences, missing candidates, ambiguity, deviations, and executable disclosures are recorded.
+- User-visible flow and internal audit content have a clear boundary.
+- No source Skill body was copied wholesale into reference.
+
+## Required Claims
+
+- `reference:workflow-protocol`
+- `reference:resolved-skills`
+- `reference:composition-report`
+- `reference:authoring-lanes`
+
+Missing any claim must block Skill review.
+
+## Status Return
+
+Status must be one of `DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, or `BLOCKED`.
+
+Write the full report to the report file path. The summary returned to the main session must be 15 lines or fewer and include status, report path, claims, evidence gaps, and concerns. If status is `BLOCKED` or `NEEDS_CONTEXT`, state exactly what source is missing, what was tried, and what the main session should do.

package/assets/skills/comet-any/reference/subagents/script-author.md

@@ -0,0 +1,81 @@
+# Script Author Subagent
+
+This file is a portable lane brief, not a platform-native custom agent. If you need a Claude Code custom agent, generate a separate platform agent resource with frontmatter.
+
+## Responsibilities
+
+Design the generated Skill's script contract instead of copying Comet Classic scripts. Scripts must use the current workflow protocol, user-selected Node labels, and real composed Skill outputs to define automatic advancement, exit checks, recovery, and evidence recording.
+
+Must cover:
+
+- `scripts/workflow-state.mjs`
+- `scripts/workflow-guard.mjs`
+- `scripts/workflow-handoff.mjs`
+
+The factory also deterministically generates `scripts/comet-plan.mjs`, `scripts/comet-check.mjs`, and `scripts/comet-hook-guard.mjs` from the same `workflow-protocol.json`. Do not duplicate or redesign those three; your contract is for the `workflow-*.mjs` scripts that the Skill core author and entry author reference.
+
+## Inputs
+
+Read the common input from the main session, especially:
+
+- `reference/workflow-protocol.json`
+- `workflow.kind`, `workflow.nodes`, `engineMode`, and `runnerMode` from `plan.json`, plus the
+  derived internal `callChain` source inventory from Skill Creator metadata
+- `reference/resolved-skills.json`
+- Protected `.comet.yaml` semantics when users customize existing Comet Skills; `comet-five-phase-overlay` primary state comes only from `openspec/changes/<name>/.comet.yaml` and must not create `.comet/runs/<workflow>/state.json` as the Comet overlay primary state.
+
+Use file handoff: the main session provides paths instead of pasting large bodies of text. Do not read main-session history or ask the user to restate content already written to artifacts.
+
+## Dispatch Template
+
+Use the current platform's subagent mechanism. The shape should include:
+
+```text
+description: "Write the script contract for <bundle-name>"
+model: <must explicitly specify model>
+prompt:
+  You are the script author subagent.
+  First read this brief, the common input path, workflow protocol path, resolved skills path, and report file path.
+  Start by asking questions: if script boundaries, Node completion conditions, state writes, or recovery semantics are unclear, return NEEDS_CONTEXT.
+  Do not guess or fill in missing protocol details.
+  Do not call comet bundle, comet publish, or comet skill, and do not execute candidate Skill scripts.
+  Write the full script contract to the report file path and return only a status summary of 15 lines or fewer.
+```
+
+## Output Requirements
+
+Return a script contract draft that explains, for each script:
+
+- Which state it reads.
+- Which state and evidence it writes.
+- How it decides whether the current Node goal is complete.
+- How it outputs `NEXT:`, `SKILL:`, and blocking reasons.
+- How it stays in the current Node when the Node is incomplete instead of forcing an exit.
+- How it supports cross-device recovery.
+- For `comet-five-phase-overlay`, how it blocks when there is no active change or multiple active changes and asks the user to choose.
+
+Exit checks must come from the current workflow protocol and composed Skill goal, not copied Comet Classic scripts.
+
+## Self-Check
+
+Before returning, check:
+
+- Every script has inputs, outputs, state reads/writes, evidence writes, and failure behavior.
+- Node completion conditions come from the workflow protocol, not fixed Node labels.
+- `NEXT:` and `SKILL:` output conditions can be directly referenced by the Skill core author.
+- Cross-device recovery does not rely on current-session memory.
+- No candidate script was executed and no Bundle state was written.
+
+## Required Claims
+
+- `script:workflow-state`
+- `script:workflow-guard`
+- `script:workflow-handoff`
+
+Missing any claim must block Skill review.
+
+## Status Return
+
+Status must be one of `DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, or `BLOCKED`.
+
+Write the full report to the report file path. The summary returned to the main session must be 15 lines or fewer and include status, report path, claims, test/check notes, and concerns. If status is `BLOCKED` or `NEEDS_CONTEXT`, state exactly what context is missing, what was tried, and what the main session should do.

package/assets/skills/comet-any/reference/subagents/skill-core-author.md

@@ -0,0 +1,129 @@
+# Skill Core Author Subagent
+
+This file is a portable lane brief, not a platform-native custom agent. If you need a Claude Code custom agent, generate a separate platform agent resource with frontmatter.
+
+## Responsibilities
+
+Write the user-visible core content for internal Node Skills. The entry Skill is owned separately by the workflow entry author. The goal is a Comet-like multi-Node workflow, not a simple chain of source Skills or a copied source Skill body.
+
+Must cover:
+
+- Every internal Node Skill
+- Node invocation semantics in `comet/skill.yaml`
+- Every `node-skill:<skill-name>` claim
+
+## Authored Zone (what you write)
+
+The generator composes each Node SKILL.md from a deterministic **Auto zone** (frontmatter, Node Goal, Entry Check, Skill Implementation, Required Skill Calls, Output Schemas, Evidence Record, Guardrails, Exit Check, Recovery) plus an **Authored zone** (`## Guidance`) that YOU write. You do NOT write the whole file — only the Guidance body. The main session records your output via `comet creator authoring-record <name> --lane skill-core --file <out.json>`; the artifact `content` for `../<node-skill>/SKILL.md` is the Guidance body.
+
+Quality bar: a real Comet phase skill (e.g. `comet-build/SKILL.md`); see `reference/authored-zone-example.md` for a full sample at the expected level. Author decision content, not boilerplate. Use `###` subsections within Guidance so they nest under `## Guidance`:
+
+- `### Prerequisites` — what must be true before this Node starts.
+- `### Steps` — the ordered, domain-specific steps; reference the bound Skill by name and say when to call it (do not copy its body).
+- `### Completion reasoning` — when the Node is genuinely done (beyond the mechanical Exit Check), and the judgment calls involved.
+- `### Red flags` — the failure modes that look like progress but are not.
+
+Here is a concrete excerpt showing the expected depth for a "Research" substance node. Notice: it is **decision content** (when to stop, what counts as enough, what to reject), not a restatement of the route table or output schema.
+
+```markdown
+### Prerequisites
+
+- The entry Decision Core has confirmed the research topic and scope.
+- `research-skill` is resolvable in the project Skill pool; if missing, stop and ask the user before improvising.
+
+### Steps
+
+1. Load `research-skill` and follow its discovery method for the confirmed topic. Do not substitute a generic web search when the project Skill defines a specific source order.
+2. Gather sources in priority order; for each source, capture origin, date, and the claim you will reuse. Reject sources that fail the project's credibility bar rather than noting them as "weak".
+3. Distill findings into note files under `notes/*.md` — one note per distinct claim, with a verbatim quote and the source pointer. Synthesis happens in the writer node, not here.
+4. Record the `research.notes.v1` `summary` evidence with a one-paragraph distillation and the count of notes produced.
+
+### Completion reasoning
+
+This node is complete ONLY when both hold: (a) the `summary` evidence is recorded, and (b) at least one artifact matches `notes/*.md`. Do not exit merely because the step list is exhausted — if notes are sparse relative to the topic scope, continue researching rather than declaring done. The Exit Check script enforces the artifact + evidence requirement mechanically; your job is to judge whether the research is genuinely sufficient.
+
+### Red flags
+
+- Exiting after recording `summary` but producing zero `notes/*.md` files (the guardrail will block this — do not attempt to bypass).
+- Copying source text into notes without a quote marker or source pointer.
+- Advancing to the Write node while a source is still "to be verified" — verification belongs in this node.
+- Treating a single source as sufficient for a multi-perspective topic.
+```
+
+Node mode (from the protocol):
+
+- **substance** Node (workflow-kernel default): rich Guidance is mandatory. Without it the Node renders as `AUTHORING PENDING` and the Bundle cannot become ready.
+- **delegates** Node (comet-five-phase-overlay, delegating to an installed rich Skill): a short Guidance note is acceptable — the delegate carries the richness; do not duplicate it.
+
+## Inputs
+
+Read the common input from the main session, especially:
+
+- User-confirmed Node labels and editable name fields.
+- Node goals, `requiredSkillCalls`, and automatic advancement conditions from
+  `reference/workflow-protocol.json`.
+- Real Skill summaries from `reference/resolved-skills.json`.
+- The script author's `NEXT:`, `SKILL:`, guard, and recovery contracts.
+
+Use file handoff: the main session provides paths instead of pasting large bodies of text. Do not inherit main-session history; use only this brief, common input, script contracts, and reference evidence.
+
+## Dispatch Template
+
+Use the current platform's subagent mechanism. The shape should include:
+
+```text
+description: "Write Skill core content for <bundle-name>"
+model: <must explicitly specify model>
+prompt:
+  You are the Skill core author subagent.
+  First read this brief, the common input path, script contract path, reference evidence path, and report file path.
+  Start by asking questions: if Node labels, required Skill calls, automatic advancement, or user pause points are unclear, return NEEDS_CONTEXT.
+  Do not guess or fill in missing flow details.
+  Only write internal Node Skill drafts; do not write entry Skill, Bundle state, or execute candidate scripts.
+  Write the full Skill draft to the report file path and return only a status summary of 15 lines or fewer.
+```
+
+## Output Requirements
+
+Return internal Node Skill drafts that show:
+
+- Internal Node Skills own a single-Node goal, required Skill calls, completion evidence, and script guards.
+- If the protocol declares `requiredSkillCalls`, the matching Node must state the target Node,
+  required Skill, applies-to scope, and evidence requirement. Subagent cases must also tell the
+  implementation subagent prompt to load that Skill.
+- If the Node goal is not complete, continue working instead of exiting because a checklist is exhausted.
+- Automatic advancement must come from script outputs `NEXT:` and `SKILL:`, not agent guesses.
+- Nested Skill calls use only Skill names, not provider prefixes.
+- When users customize existing Comet Skills, preserve `open / design / build / verify / archive` and `.comet.yaml` semantics.
+- For arbitrary Skill composition, organize the result as a Comet-like multi-Node workflow.
+
+Forbidden:
+
+- Copying full source Skill bodies.
+- Provider prefixes such as `Superpowers writing-plans` or `OpenSpec openspec-propose`.
+- Mixing Chinese process sentences into English Skills.
+- Leaking audit reports, source hashes, or internal metadata into user-visible `SKILL.md`.
+
+## Self-Check
+
+Before returning, check:
+
+- Every Node explains required Skill calls, completion evidence, script guards, and recovery entry.
+- Every `requiredSkillCalls` item has a clear load instruction and evidence requirement in the
+  matching Node Skill.
+- Automatic advancement references script outputs `NEXT:` and `SKILL:`.
+- Skill calls use only Skill names, not provider prefixes.
+- User-visible English prose does not mix in Chinese process sentences.
+- No source Skill body was copied wholesale.
+
+## Required Claims
+
+- One `node-skill:<skill-name>` for every internal Node Skill
+
+Missing any claim must block Skill review.
+
+## Status Return
+
+Status must be one of `DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, or `BLOCKED`.
+
+Write the full report to the report file path. The summary returned to the main session must be 15 lines or fewer and include status, report path, claims, unresolved concerns, and recommended rework. If status is `BLOCKED` or `NEEDS_CONTEXT`, state exactly what context is missing, what was tried, and what the main session should do.

package/assets/skills/comet-any/reference/subagents/skill-reviewer.md

@@ -0,0 +1,124 @@
+# Skill Review Subagent
+
+This file is a portable lane brief, not a platform-native custom agent. If you need a Claude Code custom agent, generate a separate platform agent resource with frontmatter.
+
+## Responsibilities
+
+Review the other subagents' artifacts and claims, then decide whether the candidate Skill is usable like Comet. The review must give a clear conclusion: `Review passed` or blocking findings.
+
+Must cover:
+
+- `reference/skill-review.md`
+- `reference/authoring-lanes.json`
+
+## Inputs
+
+Read the common input from the main session, plus all artifacts, claims, and findings returned by the other five author roles.
+
+Use file handoff: the main session provides paths instead of pasting large bodies of text. Read the overview, common input, five author report files, artifact paths, and claims. Do not use main-session history as a substitute for artifact evidence.
+
+## Dispatch Template
+
+Use the current platform's subagent mechanism. The shape should include:
+
+```text
+description: "Review the Comet-like Skill outputs for <bundle-name>"
+model: <must explicitly specify model>
+prompt:
+  You are the Skill review subagent.
+  First read this brief, the common input path, five author report paths, artifact paths, claim list, and report file path.
+  Do not trust author reports; author reports are claims that must be cross-checked against artifacts and claims.
+  Do not tell the reviewer not to flag an issue, and do not pre-classify any issue as Minor.
+  Review is read-only. Do not modify the working tree, index, HEAD, or branch state.
+  Write the full review to the report file path and return both verdicts.
+```
+
+## Review Method
+
+Do not trust author reports. Inspect artifacts and claims first, then decide whether the authors' claims hold. Do not downgrade severity because "the author says this is intentional."
+
+The review must provide two verdicts:
+
+- Skill contract fit: whether the output satisfies the user-confirmed goal, workflow protocol,
+  `requiredSkillCalls`, claims, Node advancement, script guards, pause points, and recovery
+  requirements.
+- Usability quality: whether it is as usable as Comet: clear, recoverable, auditable, and not overexposing internal metadata.
+
+Evidence must cite artifact paths and claims. Do not write only "looks fine."
+
+## Blocking Conditions
+
+Any of these must produce blocking findings:
+
+- Missing `reference/skill-review.md`.
+- Missing `reference/authoring-lanes.json`.
+- Missing critical claims from the workflow entry author, script author, reference author, Skill core author, or pause point author.
+- Entry Skill writes Node routes as multiple immediate Node Skill loads instead of routing only the current Node through state scripts.
+- Missing `workflow-state.mjs`, `workflow-guard.mjs`, or `workflow-handoff.mjs` contract.
+- Missing any of the six generated scripts (`workflow-state`, `workflow-guard`, `workflow-handoff`, `comet-plan`, `comet-check`, `comet-hook-guard`) in the package.
+- Missing workflow entry, or Skill core has no internal Node Skill.
+- Node advancement is not expressed through script outputs `NEXT:` and `SKILL:`.
+- `requiredSkillCalls` declared by the workflow protocol are not clearly required in the matching
+  Node Skill, or a subagent handoff Node does not require the implementation subagent prompt to load that
+  Skill.
+- User pause points are missing, or can be bypassed by defaults.
+- English Skills mix in Chinese process sentences.
+- Nested Skill calls use provider prefixes.
+- User-visible `SKILL.md` leaks generated audit sections, source hashes, or internal metadata.
+- Customizing existing Comet Skills replaces or removes `open / design / build / verify / archive`, `.comet.yaml`, decision point, verify-result-transition, or archive-delta-sync.
+- Arbitrary Skill composition is missing automatic advancement, script guards, user pause points, recovery, or current draft hash eval evidence.
+
+## Severity
+
+- Critical: makes the generated Skill unusable, unrecoverable, unauditable, or breaks protected `/comet` semantics.
+- Important: makes the Node flow, script guards, pause points, Skill calls, or evidence chain untrustworthy; must be fixed before ready.
+- Minor: clarity, naming, or maintainability improvements that do not block ready.
+
+## Output Requirements
+
+Return:
+
+- `reference/skill-review.md`
+- `reference/authoring-lanes.json`
+- `review:skill-review`
+- Final `Review passed` or blocking findings.
+
+Output must include:
+
+- Two verdicts: Skill contract fit and usability quality.
+- Strengths: concrete artifacts that work well.
+- Issues grouped by Critical, Important, and Minor.
+- For every finding: artifact path, claim, problem, impact, and recommended fix.
+- `Review passed` or blocking findings.
+
+If any Critical or Important issue exists, do not return `Review passed`. If an author status is `BLOCKED` or `NEEDS_CONTEXT`, return blocking findings; the main session must add context, split the task, switch to a stronger model, or ask the user, and must not continue assembly.
+
+## Multi-vote Review (depth-aware)
+
+The skill-review lane is the DAG barrier and runs after every author lane. Its verdict is recorded with `comet creator authoring-record <name> --lane skill-review --file <review.json>` and becomes the real `skill-review.md` / `authoring-lanes.json` evidence — it is NOT a hardcoded approval.
+
+- `depth: full` → dispatch N=3 independent reviewers, each holding exactly one lens (`contract-fit`, `usability`, `evidence-trace`, `self-consistency`), none seeing the others' conclusions. Cross-voter findings are de-duplicated, then a finding is confirmed only by majority. Repeat until `dryThreshold` consecutive rounds find no new Critical/Important (capped by `maxRounds`). `self-consistency` must cross-check that referenced commands resolve, the declared package matches the generated package, and no phantom command reference (a name that is not a registered command) remains.
+- `depth: quick` → a single reviewer, single round.
+- `passed` is `true` only when zero Critical/Important findings remain. Minor findings are recorded but do not block.
+
+The recorded review object must match this shape (validated by `authoring-record`):
+
+```json
+{
+  "lane": "skill-review",
+  "status": "DONE",
+  "review": {
+    "passed": true,
+    "evidenceSource": "llm-multivote",
+    "voters": 3,
+    "lenses": ["contract-fit", "usability", "evidence-trace", "self-consistency"],
+    "rounds": 2,
+    "findings": [
+      { "severity": "minor", "path": "SKILL.md", "problem": "Wording nit.", "fix": "Rephrase." }
+    ],
+    "reviewedAt": "2026-06-28T00:00:00.000Z"
+  }
+}
+```
+
+A `passed: false` review is a readiness blocker (publish cannot proceed); a missing review is a warning (the package still carries an honest `deterministic-check-only` placeholder, never a fabricated approval).