@rpamis/comet 0.3.9 → 0.4.0-beta.10

package/assets/skills/comet-hotfix/SKILL.md

@@ -1,18 +1,20 @@
 ---
 name: comet-hotfix
-description: "Comet preset path: Bug fix / hotfix. Skip brainstorming, directly open → build → verify → archive. Applicable for behavior fixes, scenarios not involving new capability design."
+description: "Use only when explicitly invoked as /comet-hotfix or routed by the root Comet skill/runtime to the hotfix preset; fix an existing behavior bug, not an ordinary unmanaged bugfix."
 ---
 
 # Comet Preset Path: Hotfix
 
+Before starting or recovering, read and follow `comet/reference/classic-layout.md`. Every OpenSpec CLI call in this file must use the adapter, and every file path must use the `<classic-*>` logical roots bound by that protocol.
+
 Quick bug fix workflow: open → build → verify → archive. Skip brainstorming and full plan, applicable for behavior fixes not involving new capability design.
 
 **Applicable conditions** (all must be met):
 1. Fix bugs in existing functionality, no new capability
 2. No interface changes or architecture adjustments
-3. Change scope is predictable (usually ≤ 2 files)
+3. Change scope is predictable (file count is a hint only, not a hard upgrade condition; see Upgrade Assessment below)
 
-**Not applicable**: If fix process discovers need for architecture adjustments, should upgrade to full `/comet` workflow.
+**Not applicable**: If the fix process hits a qualitative-change signal (see "Upgrade Assessment" section), the user decides whether to upgrade to the full `/comet-classic` workflow.
 
 ---
 
@@ -20,20 +22,13 @@ Quick bug fix workflow: open → build → verify → archive. Skip brainstormin
 
 ### 0. Output Language Constraint
 
-Streamlined OpenSpec artifacts must use the language of the user request that triggered this workflow.
+Streamlined OpenSpec artifacts must use the configured Comet artifact language. Before `.comet.yaml` exists, read `classic.language` from project `.comet/config.yaml`, then fall back to global `~/.comet/config.yaml`; after initialization, use `comet state get <name> language`.
 
 Execution chain: open → build → root cause check → verify → archive. Hotfix provides default decisions for each phase: streamlined open, direct build, root cause confirmation, scale-based verification, and final archive confirmation after verification passes.
 
-Locate Comet scripts before starting:
+Before starting, locate Comet scripts via `comet/reference/scripts.md`. When resuming from any entry point, first use `comet/reference/context-recovery.md` to confirm phase/workflow.
 
-```bash
-COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
-if [ -z "$COMET_ENV" ]; then
-  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
-  return 1
-fi
-. "$COMET_ENV"
-```
+When resuming an existing hotfix change, the first state operation must be `comet state select <change-name>`. For a new change, run the command immediately after `.comet.yaml` initialization and before source writes.
 
 ### 1. Quick Open (preset open)
 
@@ -41,58 +36,77 @@ Reuse Comet open capability to create change, but use hotfix defaults: do not ex
 
 **Immediately execute:** Use the Skill tool to load the `openspec-new-change` skill. Skipping this step is prohibited.
 
-After the skill loads, follow its guidance to create streamlined artifacts:
-  - `proposal.md` — problem description + root cause analysis + fix goal (no solution comparison needed)
-  - `design.md` — fix solution (one is enough, no multi-solution comparison needed)
-  - `tasks.md` — fix task list
-- **No delta spec needed** (unless fix changes existing spec acceptance scenarios)
+<!-- external-openspec-skill-override -->
+**External OpenSpec Skill override:** Do not execute its direct official CLI, fixed-cwd, or fixed physical OpenSpec path instructions. Route every OpenSpec command through `comet classic openspec -- <args...>` and use the `<classic-*>` logical roots bound for this run for every change and artifact path.
 
-Initialize Comet state file:
+After the skill loads, create the change skeleton first, then immediately initialize recoverable state and bind the current change:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" init <name> hotfix
+comet state init <name> hotfix
+comet state select <name>
+comet state check <name> open
 ```
 
-Verify initialized state:
+If the `select` / `check` output is `BLOCKED` because `bound_branch` does not match the current branch, immediately pause under `comet/reference/decision-point.md` and let the user choose one option: switch back to the bound branch and rerun entry verification, or run `comet state rebind <change-name>` after the user explicitly confirms the current branch should take over this change, then rerun entry verification. Do not switch branches or rebind on your own.
+
+Entry workspace isolation is a user decision point; do not use `current` as the default isolation mode. Pause under `comet/reference/decision-point.md` and let the user choose one option:
+
+- A. Work directly on the current branch: run `comet state set <name> isolation current` to truthfully bind the current branch
+- B. Create a branch: create and switch to `hotfix/YYYYMMDD/<change-name>`, then run `comet state set <name> isolation branch`
+- C. Create a worktree: first use the Skill tool to load Superpowers `using-git-worktrees`; let that skill create the isolated workspace, then run `comet state set <name> isolation worktree` inside the worktree
+
+After B/C, rerun this in the actual execution branch or worktree:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" check <name> open
+comet state select <name>
 ```
 
+Then create the streamlined artifacts:
+  - `proposal.md` — problem description + root cause analysis + fix goal (no solution comparison needed)
+  - `design.md` — fix solution (one is enough, no multi-solution comparison needed)
+  - `tasks.md` — fix task list
+- **No delta spec needed** (unless fix changes existing spec acceptance scenarios)
+
 Run phase guard to transition open → build:
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply
+comet guard <change-name> open --apply
 ```
 
 Check `auto_transition` to decide whether to continue:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" next <name>
+comet state next <name>
 ```
 
 - `NEXT: auto` → continue to Step 2
-- `NEXT: manual` → pause, follow `HINT` to prompt user to run `/<SKILL>` manually
+- `NEXT: manual` → return control with `HINT` and end the current invocation; do not ask whether to continue
 
 ### 2. Direct Build (preset build)
 
-Use hotfix defaults: `build_mode: direct`. Skip Superpowers `brainstorming` and `writing-plans` (unless tasks > 3; if exceeds 3 tasks, transfer to `/comet-build`'s plan and execution method selection — note this does NOT trigger full workflow upgrade, only switches execution method).
+Use hotfix defaults: `build_mode: direct`, `tdd_mode: direct`, and `review_mode: off`. `isolation` must keep the entry workspace isolation the user confirmed in Step 1; do not change it back to `current` on your own. Here `direct` skips full planning/TDD orchestration; it never skips reproduction, regression coverage, or verification. Skip Superpowers `brainstorming` and `writing-plans`; **task count alone does not route to `/comet-build`**. Keep larger task lists ordered in the current hotfix and ask about upgrading only when a qualitative-change signal or scope tripwire is hit.
 
-Before continuing or starting changes, handle uncommitted changes through `comet/reference/dirty-worktree.md`. If attribution shows the fix scope exceeds hotfix, handle it through this file's "Upgrade Conditions".
+Before continuing or starting changes, handle uncommitted changes through `comet/reference/dirty-worktree.md`. If attribution shows a qualitative-change signal or file-count tripwire is hit, handle it through this file's "Upgrade Assessment".
 
-**Immediately execute:** Execute tasks one by one according to tasks.md:
+Before implementation, **reproduce the bug and record failing evidence first**:
 
-1. Read `openspec/changes/<name>/tasks.md`, get incomplete task list
+1. Confirm the reported old behavior with minimal repeatable steps and record the command, input, and actual result
+2. When automatable, add and run a regression test that fails for this bug; confirm the failure is caused by the bug rather than the environment or test itself
+3. If automation is temporarily impossible, record why plus repeatable manual failing evidence in the proposal/verification report; never edit code without evidence
+
+After RED evidence exists, execute tasks one by one according to tasks.md:
+
+1. Read `<classic-change-dir>/tasks.md`, get incomplete task list
 2. For each incomplete task:
    - Modify code according to task description
    - Run project formatter (e.g., `mvn spotless:apply`, `npm run format`)
-   - Run related tests to confirm pass
+   - First rerun the new failing regression test and confirm it turns green, then run related tests
    - Check corresponding `- [ ]` to `- [x]` in tasks.md
    - Commit code, commit message format: `fix: <brief fix description>`
 3. After all tasks complete, explicitly run relevant project tests and build commands
 
 **If fix affects existing spec acceptance scenarios**:
-- Create delta spec in `openspec/changes/<name>/specs/<capability>/spec.md`
+- Create delta spec in `<classic-change-dir>/specs/<capability>/spec.md`
 - Only include `## MODIFIED Requirements` section
 
 During hotfix execution, whenever a crash, unexpected behavior, test failure, or build failure appears while running the program, tests, build, or manual verification, must use the Skill tool to load the Superpowers `systematic-debugging` skill. Before root-cause investigation is complete, must not propose or implement source-code fixes.
@@ -107,14 +121,14 @@ For specific investigation, minimal failing test, fix verification, and keeping
 2. Search and verify problem code no longer exists
 3. If root cause not eliminated, return to Step 2 to continue fix (still in build phase, no state transition needed)
 
-**Upgrade conditions**:
-- Root cause check reveals deep architecture issues → Stop hotfix, handle per "Upgrade Conditions" section
-- Fix requires additional interface changes → Stop hotfix, handle per "Upgrade Conditions" section
+**Upgrade assessment signals**:
+- Root cause check reveals deep architecture issues → Hits a qualitative-change signal; pause per the "Upgrade Assessment" section and let the user decide
+- Fix requires additional interface changes → Hits a qualitative-change signal (introduces new public API); pause per the "Upgrade Assessment" section and let the user decide
 
 After root cause is confirmed eliminated, run phase guard to transition build → verify:
 
 ```bash
-"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply
+comet guard <change-name> build --apply
 ```
 
 State automatically updates to `phase: verify`, `verify_result: pending`, then enter verification.
@@ -125,7 +139,7 @@ Reuse `/comet-verify`, with comet-verify's scale assessment deciding lightweight
 
 **Immediately execute:** Use the Skill tool to load the `comet-verify` skill. Skipping this step is prohibited.
 
-Small-scale hotfixes without delta spec usually meet lightweight verification conditions (≤ 3 tasks, ≤ 2 files), comet-verify's scale assessment will select the lightweight verification path (6 quick checks, including lightweight code review). If hotfix created delta spec, enter full verification path according to comet-verify's scale assessment rules.
+Small-scale hotfixes without delta spec usually meet lightweight verification conditions (≤ 3 tasks, changed files below the scale threshold), comet-verify's scale assessment will select the lightweight verification path (6 quick checks; default `review_mode: off` does not dispatch automatic code review). If the user wants to increase review, they can run `comet state set <name> review_mode standard` or `thorough` before verification. If hotfix created delta spec, enter full verification path according to comet-verify's scale assessment rules.
 
 After verification passes, record `.comet.yaml` `verify_result` as `pass` according to `/comet-verify` rules, must not skip this status before archiving. After verification passes, still enter `/comet-archive`'s final archive confirmation; do not automatically run the archive script.
 
@@ -143,14 +157,13 @@ If there is delta spec, sync to main spec according to comet-archive rules, and
 <IMPORTANT>
 Hotfix workflow is **one-time continuous execution**. After invoking `/comet-hotfix`, agent must automatically advance through hotfix steps, without pausing to wait for user input mid-way.
 
-Exception: when `.comet.yaml` has `auto_transition: false`, after each phase guard advances `phase`, do not auto-invoke the next skill. In this case, use `"$COMET_BASH" "$COMET_STATE" next <name>` output and pause for manual continuation as instructed.
+Exception: when `.comet.yaml` has `auto_transition: false`, end the current invocation at each phase boundary and return control with `HINT`; the user may run the next phase later. This is a manual handoff, not a new confirmation point.
 
-The following situations must also pause and wait for user confirmation:
+The following genuine user decisions still pause:
 
-1. Encountering upgrade conditions (see "Upgrade Conditions" section). **Must use the current platform's available user input/confirmation mechanism to pause and wait for the user to explicitly confirm** upgrading to full workflow
-2. workspace isolation and execution-method selection when tasks exceed 3 and transfer to `/comet-build`
-3. verify phase (comet-verify) verification-failure and branch-handling decisions
-4. Final archive confirmation (before comet-archive runs the archive script)
+1. Encountering an upgrade-assessment signal (see "Upgrade Assessment" section). **Must use the current platform's available user input/confirmation mechanism to pause and wait for the user to explicitly choose**: continue the hotfix flow, or upgrade to the full `/comet-classic` workflow
+2. Verify-phase acceptance of WARNING/SUGGESTION deviations, Spec drift handling, or strategy after the automatic repair limit; the first 3 clearly repairable failures close automatically
+3. Final archive confirmation and the branch-handling decision after the archive commit
 
 Execution order: quick open → direct build → root cause check → verification → archive → complete
 
@@ -159,28 +172,27 @@ After each step completes, immediately enter next step. Within each phase, must
 
 ---
 
-## Upgrade Conditions
+## Upgrade Assessment
+
+Hotfix upgrade assessment only decides whether to move from the preset workflow to full; file count never upgrades automatically, and `comet state scale` only decides verification weight.
 
-Upgrade to full `/comet` when **any** of the following conditions are met:
+If `/comet-classic` passes an intent frame from the entry, hotfix must recheck `risk_signal` and escalation signals only before build: new capability, public API, schema change, cross-module coordination, or deep architecture work. When any signal matches, enter the existing escalation decision point; do not reimplement entry intent recognition.
 
-| Condition | Explanation |
-|-----------|-------------|
-| Change involves **3+ files** | Exceeds single-point fix scope |
-| Architecture changes | New modules, new interfaces, new dependencies |
-| Database schema changes | Structural adjustments |
-| Introduces new public API | Fix creates new external interface |
-| Fix scope exceeds single function/module | Requires coordinated changes |
+Continuously check these qualitative-change signals: cross-module coordination, needing a new capability, database schema changes, introducing a new public API, or touching a deep architecture problem (in hotfix context this often surfaces during the root-cause elimination check). If any signal appears, the agent **must not self-upgrade or self-decide to continue**.
 
-When upgrade conditions are met, **must follow the `comet/reference/decision-point.md` protocol to pause and wait for the user to explicitly confirm** upgrading to the full `/comet` workflow. Do not directly enter `/comet-design`, and do not automatically supplement Design Doc.
+The file-count tripwire is only a prompt: when changed files exceed the hint threshold (for example > 4 files), ask the user whether to continue hotfix or upgrade full. More files do not necessarily mean qualitative change. A bug fix is usually focused on 1-3 files, so exceeding the threshold means the change surface is larger and is worth having the user confirm it still fits the preset scope.
 
-After user confirms upgrade, **must first update the workflow and phase fields** before entering full flow:
+When a qualitative-change signal or file-count tripwire is hit, **must pause under the `comet/reference/decision-point.md` protocol and wait for the user's explicit choice**. Do not directly enter `/comet-design`; do not automatically add a Design Doc.
+
+After the user chooses upgrade (option B), use the legal state-machine upgrade channel, a single command that converts the preset workflow to full and rolls back to design:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" set <name> workflow full
-"$COMET_BASH" "$COMET_STATE" set <name> phase design
+comet state transition <name> preset-escalate
 ```
 
-Then on current change basis, supplement Design Doc: **Immediately use the Skill tool to load the `comet-design` skill**, proceed normally with full workflow. If user does not confirm upgrade, stop hotfix and report that current change has exceeded hotfix scope.
+This command atomically sets `workflow`/`classic_profile` to `full`, rolls `phase` back to `design`, clears `design_doc`, and clears preset-only `build_mode`, `tdd_mode`, `review_mode`, `isolation`, and `verify_mode`. Then add the Design Doc on the current change: **immediately use the Skill tool to load the `comet-design` skill**. On entering build, run the full joint workflow-configuration decision again.
+
+When the user chooses continue (option A), continue the hotfix workflow and record the user's reason for continuing.
 
 ---
 
@@ -189,16 +201,16 @@ Then on current change basis, supplement Design Doc: **Immediately use the Skill
 - Bug fixed, tests pass
 - Change archived
 - If spec changes, synced to main spec
-- **Phase guard**: Before build → verify run `"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply`; before verify → archive follow `/comet-verify` and run `"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply`
+- **Phase guard**: Before build → verify run `comet guard <change-name> build --apply`; before verify → archive follow `/comet-verify` and run `comet guard <change-name> verify --apply`
 
 ## Automatic Handoff to Next Phase
 
 Follow `comet/reference/auto-transition.md`. Key command:
 
 ```bash
-"$COMET_BASH" "$COMET_STATE" next <name>
+comet state next <name>
 ```
 
 - `NEXT: auto` → invoke the skill pointed to by `SKILL` to continue hotfix workflow (`phase: build` returns `comet-hotfix`, `verify` returns `comet-verify`, `archive` returns `comet-archive`)
-- `NEXT: manual` → do not invoke the next skill; prompt user to manually run `/<SKILL>` per `HINT`
+- `NEXT: manual` → do not invoke the next skill; return control with `HINT`, end the invocation, and do not create another confirmation point
 - `NEXT: done` → workflow is complete, no further action needed

package/assets/skills/comet-native/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: comet-native
+description: Use when the user explicitly invokes /comet-native, asks to start or resume a Native change, or the entry router selects Native; clarify requirements, read state, and drive Shape → Build → Verify → Archive.
+---
+
+# Comet Native
+
+Native stores requirements, complete target specifications, state, and evidence. You understand, implement, and verify; the Runtime owns state, boundaries, and recovery.
+
+## Progressive loading
+
+Start with this file only. Read one reference when the corresponding task appears:
+
+- If Shape contains unresolved user-visible behavior, read the [clarification reference](reference/clarification.md).
+- If you need advanced options, receipts, partial scope, or an external-role handoff command, read the [command reference](reference/commands.md).
+- If you need to edit the brief, specifications, or verification report, read the [artifact reference](reference/artifacts.md).
+- If interruption, stale evidence, a repair stop, conflict, lock, or migration occurs, read the [recovery reference](reference/recovery.md).
+
+## Core rules
+
+Read these values from `.comet/config.yaml`:
+
+- `native.clarification_mode`: defaults to `sequential`;
+- `native.archive_confirmation`: defaults to `automatic`;
+- `native.max_verify_failures`: defaults to `5`.
+
+Config, selection, change state, and formal artifacts on disk take precedence over chat memory. Do not directly edit Runtime-managed state, evidence, locks, or transaction files.
+
+The Native main workflow does not depend on any external Skill.
+
+Do not receive signing private keys or impersonate an external approval role. When an external action is missing, follow the Runtime continuation, wait, and hand off the required command.
+
+## Start or resume
+
+1. Run `comet native status` to identify the current change and phase.
+2. Run `comet native show <change-name>` for the target. In Verify, Archive, or Build after a failure, also run `status <change-name> --details`.
+3. When more acceptance items are needed, follow `acceptancePage.nextCursor`. If findings are truncated, handle the returned findings and then read details again.
+4. After confirming the target, run `comet native select <change-name>`.
+5. Read only the formal artifacts, implementation, tests, and project rules needed by the current phase.
+
+If multiple reasonable candidates remain, ask the user to select one. Create a change only after confirming that no matching active change exists:
+
+```text
+comet native new <change-name> \
+  --creation-authorization <owner-provided-path> \
+  --language en
+```
+
+If the Runtime reports missing external authorization, stop creation and wait for the owner. Use only the Native artifact root selected by project configuration.
+
+## Shape
+
+First investigate facts available from the repository, tools, and runtime environment. Ask the user only when different choices would materially change user-visible results and the existing requirements do not resolve the choice reliably. You own implementation choices.
+
+When behavior is unresolved, read the clarification reference and follow `clarification_mode`. After every user answer, immediately update Decisions, the brief, and the complete target specifications in the same change. Keep unresolved items `[blocking]`; do not modify project implementation or advance while a blocker remains.
+
+After all user decisions are resolved, check again for silent assumptions. Give the user a shared-understanding summary covering the goal, scope, key decisions, acceptance criteria, and non-goals. Only after explicit confirmation may you remove the final blocker and advance:
+
+```text
+comet native next <change-name> --summary <summary> --confirmed
+```
+
+If the brief or specifications change confirmed behavior, obtain confirmation again. Do not edit confirmation state manually.
+
+## Build
+
+Implement the simplest reliable solution that satisfies the brief and complete target specifications. Work may proceed in batches. Long tasks may use a checkpoint for recovery context, but a checkpoint is not completion evidence.
+
+When requirements change, update the formal artifacts first. If a new user decision appears, return to the Shape clarification and confirmation boundary.
+
+After the candidate implementation is complete, review it against the complete specifications and every acceptance item for omissions, then advance with real project artifacts:
+
+```text
+comet native next <change-name> \
+  --summary <summary> \
+  --artifact <project-path>
+```
+
+If no code changed or the Runtime cannot prove complete scope, read the command reference. Never describe unknown or incomplete scope as complete.
+
+## Completion Loop
+
+After entering Build, converge through this loop:
+
+1. Run `status <change-name> --details` and read the currently required acceptance pages. After a Verify failure, prioritize failed or missing acceptance items and failed checks.
+2. Complete one related batch of real repairs. You may write a checkpoint before interruption, but a checkpoint is not completion evidence.
+3. When a candidate implementation exists, reread the brief, complete specifications, and every acceptance item, then perform one complete review.
+4. Run real validation and submit the Verify result.
+5. `fail` returns to Build and repeats from step 1 without running Archive; only `pass` enters Archive.
+
+The loop ends only at `done`, `await-user`, `blocked`, or an explicit caller stop point. One Agent turn, one checkpoint, or the Agent saying “complete” is not a terminal state. The Agent finds and repairs gaps; the Runtime decides whether completion has been proven.
+
+## Verify
+
+Run real validation based on the acceptance items, complete target specifications, and change risk. Record actual results in `verification.md` and the acceptance evidence. A check that did not run or failed cannot be reported as passed.
+
+Use acceptance IDs and receipts returned by the Runtime. Read the artifact and command references when you need to generate the evidence block, record an automated or manual receipt, request a waiver, or hand off independent review. The current Agent does not perform external signing.
+
+Submit `pass` only when the Runtime accepts the complete, fresh acceptance matrix, required checks, and independent review. Reverify after relevant implementation, specification, report, or evidence changes.
+
+`fail` returns to Build. Fix the failed or missing acceptance items and failed checks reported by the Runtime before verifying again; another `next` call is not itself a repair. When the Runtime reaches its repeated-gap stop condition or the `native.max_verify_failures` budget, stop and wait for a user decision.
+
+An intermediate Verify failure never runs Archive or triggers archive confirmation. Continue Build → Verify until pass, a Runtime block, or a required user decision.
+
+## Archive
+
+Preview only after the final Verify pass:
+
+```text
+comet native archive <change-name> --dry-run
+```
+
+After a successful preview:
+
+- `automatic`: run the exact commit command returned by the continuation;
+- `required`: show the implementation, verification, and specification-operation summary, then wait for the user to archive now or keep the change active.
+
+Do not reuse an old preflight. If facts drift or a canonical conflict or unfinished transaction appears, follow the continuation and the recovery reference.
+
+## Continuation and stop points
+
+Shape, Build, and Verify transitions return `next: auto | manual` together with `continuation.disposition: continue | await-user | blocked | done`, required inputs, and the next action. Archive does not advance through `next`; a successful archive returns `done`. After every transition, act on that Runtime continuation:
+
+- `continue`: reread the phase and currently required artifacts, then continue;
+- `await-user`: wait for input that genuinely belongs to the user or an external role;
+- `blocked`: handle the findings and read the recovery reference when needed;
+- `done`: the change is complete.
+
+`next: auto` means only that the current transition succeeded; later work has not run automatically. If the caller explicitly requests a stop after a transition, update the formal artifacts, run the one allowed transition, make no tool calls after the transition succeeds, then output the agreed marker and end the turn, even when the continuation is `continue`.
+
+`workspace-root-changed` and `workspace-inspection-unavailable` are read-only advisories and do not block progression or Archive by themselves. Unknown workspace-integrity findings, confirmed conflicts, stale evidence, and repair stops must be resolved; when the Runtime requires workspace identity repair, run read-only doctor and then follow its explicit `doctor --repair` report.
+
+Never place tokens, passwords, private keys, connection strings, or other credentials in summaries, reasons, reports, or artifacts.

package/assets/skills/comet-native/reference/artifacts.md

@@ -0,0 +1,141 @@
+# Native Artifact Reference
+
+Read this file only when editing the brief, complete target specifications, verification report, or acceptance evidence.
+
+## Artifact boundary
+
+The Agent primarily edits:
+
+```text
+<artifact-root>/comet/changes/<change-name>/
+  brief.md
+  specs/<capability>/spec.md
+  verification.md
+```
+
+Project configuration, current selection, and change state are read inputs. Do not manually change Runtime-managed phase, confirmation, specification operations, scope, evidence, checkpoints, locks, or transaction fields.
+
+The Native artifact root is selected only by `.comet/config.yaml`. Do not scan another workflow's directories or create a second state root.
+
+## Scope snapshot boundaries
+
+Git snapshots contain tracked and non-ignored untracked files, with each submodule/gitlink treated atomically. Non-Git projects use a bounded physical-tree snapshot.
+
+- `git-selection-changed`: wait until Git writes are stable, then retry. It cannot be authorized as partial scope.
+- `physical-selection-changed` or `physical-enumeration-limit`: wait for a stable filesystem or reduce the project tree, then retry. Neither can be authorized as partial scope.
+- When scope details exceed the budget, the Runtime reports a `scope-detail-overflow` count and content hash instead of guessing omitted paths. Do not edit evidence or treat an incomplete snapshot as complete.
+
+## Project configuration
+
+Configuration that directly affects Agent behavior:
+
+```yaml
+native:
+  artifact_root: docs
+  language: en
+  clarification_mode: sequential
+  archive_confirmation: automatic
+  max_verify_failures: 5
+```
+
+- `clarification_mode`: `sequential` or `batch`.
+- `archive_confirmation`: `automatic` or `required`.
+- `max_verify_failures`: total Verify-fail submissions allowed for one confirmed contract.
+
+Missing fields default to `sequential`, `automatic`, and `5`. Configuration changes do not keep old evidence fresh or clear existing blockers automatically.
+
+## Brief
+
+`brief.md` uses these level-one headings:
+
+```text
+# Outcome
+# Scope
+# Non-goals
+# Acceptance examples
+# Constraints and invariants
+# Decisions
+# Open questions
+# Verification expectations
+```
+
+Outcome, Scope, Non-goals, and Acceptance examples must contain substantive content.
+
+Blocking items in Open questions use these fixed forms:
+
+```text
+- [blocking] <current Sequential question>
+- [blocking] Q1: <question>
+- [blocking] CONFIRM: <final shared understanding>
+```
+
+Keep unanswered or ambiguous questions. After the user confirms a decision, write it into Decisions and the complete target specifications before removing its blocker. Do not preserve hidden reasoning.
+
+## Complete target specifications
+
+Write specifications at:
+
+```text
+changes/<change-name>/specs/<capability>/spec.md
+```
+
+Each file describes the complete capability behavior after Archive, not an incremental patch against old text.
+
+- New capability: write the complete specification.
+- Existing capability: write the complete replacement specification.
+- Removed capability: run `comet native spec remove`; do not only delete the file.
+
+The Runtime records create, replace, remove, and the canonical baseline. On a canonical conflict, reread and rewrite the complete target specification before using `spec rebase`. Do not edit Runtime state or hashes manually.
+
+## Verification
+
+`verification.md` uses these non-empty level-one headings:
+
+```text
+# Acceptance evidence
+# Commands and results
+# Skipped checks
+# Spec consistency
+# Known limitations and risks
+# Conclusion
+```
+
+Record real commands, results, and reviewable facts. Put checks that did not run under Skipped checks. A failing result cannot be reported as pass.
+
+## Acceptance evidence
+
+Use acceptance IDs returned by the Runtime; do not calculate them. Prepare the entries array, then run:
+
+```text
+comet native evidence format [--entries <path>]
+```
+
+Place the command output unchanged under `# Acceptance evidence`. The basic input shape is:
+
+```json
+[
+  {
+    "acceptance_id": "acceptance-<sha256>",
+    "status": "passed",
+    "evidence_refs": ["runtime/evidence/receipts/<sha256>.json"]
+  },
+  {
+    "acceptance_id": "acceptance-<sha256>",
+    "status": "failed",
+    "evidence_refs": [],
+    "skipped_reason": "actual failure or incomplete reason"
+  },
+  {
+    "acceptance_id": "acceptance-<sha256>",
+    "status": "waived",
+    "evidence_refs": [],
+    "waiver_ref": "runtime/evidence/waivers/<sha256>.json"
+  }
+]
+```
+
+- `passed` references a currently valid typed receipt.
+- `failed` states the actual failure or skipped reason.
+- `waived` references the waiver returned by an external signer.
+
+Do not hand-format the machine block, reuse an evidence ref from another change, or report failed, skipped, or blocked results as passed.

package/assets/skills/comet-native/reference/clarification.md

@@ -0,0 +1,54 @@
+# Native Clarification Reference
+
+Read this file only when Shape contains unresolved user-visible behavior.
+
+## Whether to ask
+
+Separate information into three categories:
+
+- **Investigable fact**: repository state, tool capability, dependency defaults, and runtime environment. The Agent investigates it.
+- **User decision**: alternatives materially change output, defaults, failure behavior, scope, or irreversible effects. The user confirms it.
+- **Implementation choice**: algorithm, structure, or working method that does not change user-visible results. The Agent decides it.
+
+Ask only when ambiguity would materially change user-visible results and cannot be resolved reliably from the user's request, formal specifications, or an applicable contract. Do not invent questions to cover a checklist or send implementation choices to the user.
+
+Rewrite ambiguous behavior as comparable “input → output” or “trigger → result” cases. Each question includes:
+
+- Question: the user-visible difference to decide;
+- Recommendation: the preferred option and why;
+- Impact: the practical result of each option.
+
+## Sequential
+
+1. Investigate facts required by the current question.
+2. Find the most upstream unresolved question whose prerequisites are settled.
+3. Save one `- [blocking] <question>` in the brief.
+4. Ask only that question and wait for the answer.
+5. After the answer, immediately update Decisions, the brief, and the complete target specifications, then inspect the remaining questions.
+
+Keep ambiguous, partial, or unanswered content `[blocking]`. An answer decides only the behavior it covers explicitly.
+
+## Batch
+
+Each round contains only questions whose prerequisite decisions and environmental facts are settled and whose answers do not depend on one another:
+
+1. Save `- [blocking] Q1: <question>`, `- [blocking] Q2: <question>` in the brief.
+2. Ask the entire round together, giving Question, Recommendation, and Impact for each item.
+3. Update the formal artifacts after the answer. Keep unanswered or ambiguous questions `[blocking]`.
+4. Compute the next round from the new answers.
+
+Do not compress independent decisions into one multi-select question or split one ready batch across multiple rounds.
+
+## Persistence and final confirmation
+
+Write every confirmed answer immediately into Decisions and the complete target specifications of the existing change. Do not update only the brief, wait until final confirmation to write specifications, or create another change for a clarification answer.
+
+After all identified questions are resolved:
+
+1. Check for remaining silent assumptions.
+2. Give the user a summary of the goal, scope, key decisions, acceptance criteria, and non-goals.
+3. Save `- [blocking] CONFIRM: <confirmation>` in the brief.
+4. Wait for explicit user confirmation.
+5. Remove the blocker and advance with `--confirmed`.
+
+The initial feature request is not the final shared-understanding confirmation. If the user changes or rejects the summary, update the formal artifacts and continue clarification.