@rpamis/comet 0.4.0-beta.5 → 0.4.0-beta.7

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

@@ -0,0 +1,118 @@
+# Native command reference
+
+Prefer the installed `comet native` command. If the host exposes only Skill files, use this Skill's bundled runtime:
+
+```text
+node <comet-native-skill-root>/scripts/comet-native-runtime.mjs <command> [options]
+```
+
+Both entry points use the same arguments, stdout, stderr, and exit codes. Normal discovery searches upward from the current directory for `.comet/config.yaml` or the repository root; generated launchers may also pass the hidden `--project-root <path>` option.
+
+## Project and artifact root
+
+```text
+comet native init [--root <artifact-root>] [--language en|zh-CN]
+comet native root show
+comet native root move <artifact-root>
+```
+
+`artifact-root` must be a project-relative path and defaults to `docs`. `.` creates `<project>/comet/`; `docs` creates `<project>/docs/comet/`. `init --language` persists the project's default Native language in `.comet/config.yaml`; later `new` commands inherit it when `--language` is omitted. Running `init --language` again changes the default for future changes without rewriting existing ones. Existing configuration rejects a conflicting `--root`. Change the root only through `root move`, never by editing configuration directly.
+
+## Change management
+
+```text
+comet native new <change-name> [--language en|zh-CN]
+comet native spec remove <change-name> <capability>
+comet native spec rebase <change-name> --summary <text>
+comet native list [--cursor <token>]
+comet native show <change-name>
+comet native status [--cursor <token>]
+comet native status <change-name> [--details [--acceptance-cursor <token>]]
+comet native select <change-name>
+```
+
+`new` creates default configuration and `<project>/docs/comet/` when configuration is absent. Write complete target specifications at `specs/<capability>/spec.md`; `next` infers create/replace and freezes the canonical hash. Use `spec remove` to remove a capability instead of editing `spec_changes`.
+
+After a concurrent canonical change causes a conflict, reread and rewrite the complete target specification. Then use `spec rebase` to refresh operation/hash, return to Build, and clear the previous verification conclusion.
+
+`show` returns state, the brief, and proposed complete specifications. `status` returns a bounded view of phase, evidence freshness, finding summary, checkpoint, repair state, and continuation. `status <change-name> --details` also returns:
+
+- up to 50 detailed findings;
+- the `findingsTruncated` flag;
+- recovery details;
+- the first `acceptancePage`.
+
+When findings are truncated, handle the returned findings and then read details again. When `nextCursor` is non-null, pass it to `--acceptance-cursor` until it becomes null. Acceptance cursors are valid only with a specific change and `--details`, and bind to the current acceptance hash.
+
+`status` and `show` are always read-only. Run `select` explicitly when resuming a confirmed target change; do not add a `resume` command. Both `new` and `select` write the shared project-level `.comet/current-change.json` with `workflow` fixed to `native`; neither modifies a Classic change.
+
+`list` and `status` without a change name return the same read-only paginated projection, with at most 24 changes per page. Pass a non-null `nextCursor` back unchanged through `--cursor`. The cursor is bound to the complete visible name set; adding or removing changes makes an old cursor fail explicitly instead of shifting the page. At most 4096 visible changes are accepted, and a serialized page is capped at 512 KiB. `show` also bounds the number of specifications, per-file and cumulative reads, and final output size; it rejects oversized input instead of truncating requirement text.
+
+## In-phase progress and built-in checks
+
+```text
+comet native checkpoint <change-name> \
+  --summary <text> \
+  --next-action <text> \
+  [--artifact <project-relative-path>]... \
+  [--expect-revision <n>]
+
+comet native check <change-name>
+```
+
+`checkpoint` stores only an in-phase summary, next action, and content-addressed artifact manifest. It uses revision/CAS to prevent overwrites and does not change the phase. `check` is available only in Verify after an implementation scope exists. It runs Comet's built-in bounded, read-only text scan. It does not invoke Git, a shell, project scripts, external Skills, or any external process; it accepts no arbitrary command, path, environment, or timeout options and does not modify project files, the change, Run, or trajectory. Results, issue counts, and scope freshness are written to an independent content-addressed receipt. A check that finds issues or becomes stale exits with 1, but still writes the receipt.
+
+## Phase progression
+
+```text
+comet native next <change-name> --summary <text> \
+  [--confirmed] \
+  [--artifact <project-relative-path>]... \
+  [--no-code-reason <text>] \
+  [--allow-partial-scope <sha256> --partial-reason <text> --confirmed] \
+  [--result pass|fail] \
+  [--report <change-relative-path>] \
+  [--receipt <runtime/evidence/check-receipts/...json>] \
+  [--failure-category <token>]... \
+  [--failed-check <token>]... \
+  [--override-repair <sha256> --override-summary <text>]
+
+comet native archive <change-name> --dry-run
+comet native archive <change-name> --expect-preflight <sha256>
+```
+
+- Shape: advance after the brief and proposed specifications pass; add `--confirmed` only when this turn contains a decision the user just confirmed. On successful entry to Build, the Runtime binds approval to the current contract hash.
+- Build: recheck the brief and proposed specifications; provide at least one real project artifact or use `--no-code-reason`. If the contract changed after approval, status/next requires the user to reconfirm the current contract; pass `--confirmed` only after obtaining that confirmation. If complete scope cannot be proven, the first call returns a scope hash and bounded unattributed details without advancing; changes beyond the detail budget are represented by a `scope-detail-overflow` count and content hash. Retry only after the user accepts the specific risk, with the exact `--allow-partial-scope`, a reason, and `--confirmed`.
+- Verify: provide both `--result` and a complete `--report`. An optional `--receipt` must be fresh for the current change, revision, contract, and implementation scope. A failure returns to Build and may use failure categories and check IDs to form a no-progress signature; a pass enters Archive.
+- Repair: the third identical failure returns a manual stop. A genuine scope change on an ordinary Build `next` closes the old repair episode and continues. With unchanged scope, only one override is allowed, using the exact signature returned by status plus a non-empty summary. Neither a semantic repair budget nor an exhausted override can be bypassed; the generic Run iteration is only an event sequence number, not a permanent stop condition for a long-lived change.
+- Archive: only `archive` completes this phase; `next` cannot substitute for it. First run `--dry-run`, then pass the returned `preflightHash` unchanged to `--expect-preflight`. The runtime recomputes it under the mutation lock before committing.
+
+## Diagnosis and recovery
+
+```text
+comet native doctor [<change-name>]
+comet native doctor [<change-name>] --repair
+comet native doctor [<change-name>] --repair [--strategy continue|rollback]
+```
+
+Read-only doctor does not modify files. `--repair` is limited to provably safe selection cleanup, stale locks, evidence retention, ordinary phase transitions, workspace identity repair, and deterministic transaction recovery. It never rewrites user-authored YAML, Markdown, or specifications.
+
+`--strategy` is an optional transaction-recovery argument, not a requirement for ordinary repair. Ordinary transitions support only `continue`, not `rollback`.
+
+Doctor also reports evidence-retention candidates without changing them. Explicit `--repair` removes only derived evidence/receipts in active changes that are at least 30 days old, outside the latest 32 items of each evidence kind, and proven unreferenced by the dependency closure. Archived evidence, current-state references, dependencies, newer files, and the latest 32 of every kind are always retained. Removal is ordered dependents before dependencies and first moves files into a same-directory quarantine. After interruption, read-only doctor reports recovery required; explicit repair restores files only when there is no overwrite and identity still matches. Pending journals, damage, source/quarantine conflicts, and unknown or special files fail closed rather than deleting data to reclaim space.
+
+Ordinary write commands such as `new`, `next`, `archive`, and `root move` never take over stale locks automatically. Only explicit `doctor --repair` may do so after proving the local owner is gone, lock identity is unchanged, and no conflicting recovery transaction exists. Active locks and locks that cannot be proven stale are always preserved.
+
+## Output and exit codes
+
+Every command supports `--json`. JSON mode emits exactly one object with `command`, `exitCode`, `data`, and a structured `error` on failure.
+
+| Exit code | Meaning |
+| --- | --- |
+| `0` | Success |
+| `1` | Built-in `check` completed but found issues or became stale |
+| `64` | Invalid arguments or usage |
+| `65` | Invalid configuration, state, or artifacts |
+| `73` | Lock, transaction, concurrent hash, or root conflict |
+| `75` | Repair stagnation or a hard stop blocks continuation |
+| `70` | Unexpected internal failure |

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

@@ -0,0 +1,143 @@
+# Native recovery reference
+
+## Context recovery order
+
+Resume from facts on disk every time:
+
+1. Read the project's `.comet/config.yaml` and confirm the single artifact root and `native.clarification_mode`; use `sequential` when the field is absent. If `pending_root_move` exists, run doctor first.
+2. Run the read-only `comet native status`. With multiple active changes, read the shared project-level `.comet/current-change.json` and confirm `workflow: native` plus the target change, or ask the user to choose explicitly.
+3. Run the read-only `show` and `status <change-name> --details` for the target change. Read `comet-state.yaml`, the brief, proposed complete specifications, verification, bounded structured findings, the `findingsTruncated` flag, and the latest checkpoint. When findings are truncated, handle the returned items and reread details. Fetch Verify/Archive acceptance IDs separately through `acceptancePage.nextCursor`; do not depend on a missing old response.
+4. After confirming the target, run `comet native select <change-name>` to establish the shared selection. There is no separate `resume` command, and read-only commands never select a change implicitly.
+5. Read relevant canonical specifications, implementation, rules, tests, and current workspace state.
+6. Execute Shape, Build, Verify, or Archive according to the phase instead of guessing from chat history.
+
+When state, Run state, trajectory, or a transaction journal is malformed, stop writing and run read-only doctor. Never bypass the problem by editing `phase` manually.
+
+## Clarification-round recovery
+
+When Shape or Build contains `[blocking]` items, recover the current open decisions from Open questions in the brief. Do not reconstruct answers from chat history. Sequential mode recovers one most-upstream question; Batch mode recovers the round's entire ready question set from its saved numbers. Changing configuration does not clear existing blockers: first map the user's answers to the saved questions, then use the current `clarification_mode` to compute the next round.
+
+Continue investigating facts available from the repository, tools, or runtime environment yourself. Independent facts may be investigated in parallel when the host supports it, but recovery must not depend on any optional parallel capabilities. A fact still under investigation delays only the questions that depend on it.
+
+In Batch mode, unanswered questions remain `[blocking]`. After all questions are resolved, recover or establish the final shared-understanding confirmation. Remove that blocking item and enter Build only after explicit user confirmation. This process adds no phase, change-state field, or separate decision-tree file.
+
+Before interrupting a long task within the same phase, write a checkpoint when useful:
+
+```text
+comet native checkpoint <change-name> \
+  --summary <completed-facts> \
+  --next-action <next-action> \
+  [--artifact <project-relative-path>] \
+  [--expect-revision <n>]
+```
+
+On resume, check checkpoint freshness first. If phase, revision, or manifest changed, treat it as historical context rather than forcing its old next action onto new state. The runtime reports stale reasons explicitly in details.
+
+## Ordinary phase progression
+
+Before updating Run state, `comet-state.yaml`, trajectory, and checkpoint, `next` writes a prepared journal to the change's `runtime/transition.json`. It removes the journal only after every update completes.
+
+`status` and doctor report an unfinished transition. Running `next` again or entering Archive makes the runtime continue it deterministically. You can also run:
+
+```text
+comet native doctor <change-name> --repair --strategy continue
+```
+
+An ordinary phase transition has no canonical-file side effects, so it supports only `continue`, not `rollback`. Preserve a malformed journal and stop instead of assembling state by hand.
+
+## Missing or incomplete baselines
+
+`new` requires a complete baseline. Git projects evaluate only tracked and non-ignored untracked files; ignored caches and nested-repository contents do not create omissions.
+
+If the Runtime reports `baseline-snapshot-missing` or `baseline-snapshot-incomplete`, do not rebuild the baseline from current files or present it as an automatic doctor repair. That would erase historical differences since the change was created.
+
+Restore the original baseline from a trusted backup, or preserve the user-authored brief, specifications, and implementation facts while creating a new change with a complete baseline.
+
+## Stale evidence and controlled fallback
+
+After entering Verify, a change to the brief, proposed specifications, or project snapshot makes status point the stale implementation scope to a controlled fallback. Run the returned summary-only `next` command to return to Build, reconfirm the changed contract, and generate a fresh scope. In Archive, a change to any bound fact such as the implementation scope, verification report, or check receipt triggers the same fallback. Do not delete findings, reuse the old pass, or replace hash refs manually.
+
+Archive requires a two-step preflight; an old ready result is never commit authorization:
+
+```text
+comet native archive <change-name> --dry-run
+comet native archive <change-name> --expect-preflight <just-returned-sha256>
+```
+
+The second command recomputes contract, canonical base, scope, verification, current-root conflicts, and recovery state while holding the lock. Any change rejects the commit and requires a new preflight.
+
+## Verify failures and repair stops
+
+A Verify failure honestly returns to Build. When stable, non-sensitive `--failure-category` and `--failed-check` values are supplied, the runtime validates their tokens, count, and bounds, then forms a signature from failure + contract + scope. The second identical signature warns; the third without scope progress creates a manual stop, while exhausting the episode's semantic budget creates a hard stop.
+
+- Genuine implementation-scope change means mechanical progress. An ordinary Build `next` closes the old episode and automatically starts a new one; the previous hard stop does not freeze the new implementation.
+- If scope is unchanged but there is one explicit new hypothesis, use the exact signature from status plus a non-empty summary for a single `--override-repair`.
+- If the signature has already been overridden or the episode reached hard stop, do not weaken verification or fabricate a pass. Preserve the state and ask the user to change scope/constraints or stop.
+
+A pass closes the active repair episode. If old Archive evidence later becomes stale and the same failure returns, it is a new episode, while the original trajectory remains as an audit fact. The generic Engine iteration budget is not part of this product semantic.
+
+## Canonical specification conflicts
+
+Archive stops when another change modifies a canonical specification after the current change froze its `base_hash`. Do not edit the hash:
+
+1. Re-read the latest canonical specification, brief, and proposed complete specification.
+2. Rewrite the complete target specification to reflect user intent, resolving one user decision first when necessary.
+3. Run `comet native spec rebase <change-name> --summary <summary>`.
+4. The runtime refreshes operation/hash, reopens the change in Build, and clears the old verification conclusion.
+5. Implement again, record a newly confirmed decision with `--confirmed` when needed, then rerun Verify and Archive.
+
+If another change already removed the target of a remove intent, rebase drops that satisfied intent. Other remove intents freeze the latest canonical hash before re-verification.
+
+## Parallel-work advisory in the current workspace
+
+Status and Archive compare capability, operation, base hash, and declared artifacts across changes visible in the current Native root. Definite conflicts must be resolved first, and possible overlap also blocks Archive. This cannot see unintegrated worktrees, remote branches, or other machines, so it is not a distributed lock.
+
+`workspace-root-changed` and `workspace-inspection-unavailable` are explicit advisories. They explain where current root facts came from and do not independently block progression or Archive. Findings list concrete drift components such as `native-root-ref`, `project-root-path`, and `native-root-path`. Native does not read Git branch, HEAD, or worktree changed paths by default.
+
+Do not treat every `workspace-*` finding as advisory. Unknown workspace-integrity findings remain errors. When the Runtime requires workspace identity repair, run read-only doctor first and then follow its report with explicit `doctor --repair`.
+
+## Archive transactions
+
+Archive uses a global lock, staged specifications, an append-only per-operation event log, and backups. After interruption, the canonical tree may be mid-transaction, but the journal preserves the unfinished facts.
+
+Archive stage, backup, apply, and rollback copies all read through protected handles. The runtime validates source file, realpath, parent-directory identity, size, and expected hash before and after opening, then rechecks the destination before atomic commit. A path that passed an earlier containment check is not assumed to still identify the same file.
+
+Write/remove first bind the original canonical object identity and contents into the transaction, atomically rename the object into same-directory isolation, and revalidate it. Write installs a transaction-private candidate without overwrite. Rollback likewise isolates and validates the post object before restoring the original without overwrite. Even when a concurrent replacement has identical content hash, the runtime refuses to overwrite it when it is a different file object and preserves the scene.
+
+Reading `events.jsonl` is bounded by total bytes, event count, and per-event bytes. If a crash leaves only a provable prefix of the final canonical JSON event, the runtime performs CAS against the original bytes' hash/size and atomically rewrites to the last complete event before the next append. A damaged middle line, complete but invalid final line, non-canonical JSON tail, or concurrent rewrite fails closed. A complete event without a trailing newline is not removed, and repeated operations remain exactly-once by `type + operationId`.
+
+```text
+comet native doctor <change-name>
+comet native doctor <change-name> --repair --strategy continue
+comet native doctor <change-name> --repair --strategy rollback
+```
+
+- `continue` resumes after the last completed operation and converges on a committed archive.
+- `rollback` restores canonical files and the active change in reverse order.
+- The runtime validates the moved archive tree, final state, protected Run, trajectory event, and completion decision before writing `archive-finalization-started`. Rollback remains safe before this marker. Once written, the transaction has crossed the irreversible boundary and only continue is allowed, preventing an active change from being restored after completion evidence exists.
+
+Read the paths, transaction ID, and conflict details reported by doctor first. If current hashes match neither side of the journal, preserve all trees and stop automated repair.
+
+## Artifact-root moves
+
+`root move` progresses through `copying`, `ready`, and `switched`. Configuration's `pending_root_move` is the recovery source of truth; ordinary Native write commands fail closed while it exists.
+
+- `copying`: the old root is current and target staging may be incomplete.
+- `ready`: staging passed per-file path, size, and SHA-256 verification, but configuration has not switched.
+- `switched`: configuration points to the new root. Only after another equivalence, parent-chain, and directory-identity check is the old root renamed into a transaction-ID-bound sibling quarantine, revalidated, then removed. Continue/rollback recognizes this quarantine after interruption and settles deterministically instead of recursively deleting an old path.
+
+Use doctor's explicit continue or rollback strategy. If the two tree hashes differ, delete neither tree and give the user both reported paths.
+
+## Locks and safe repair
+
+Doctor distinguishes active locks, provably stale local locks, and remote locks whose owners cannot be determined. Remove a stale lock only when its owner process is known not to exist and no unfinished transaction depends on it; never break active or unknown locks automatically.
+
+Locks bind owner metadata, lock-file identity, and in-process FIFO ordering. Ordinary mutations never take over based on an apparently old timestamp. Only explicit doctor repair may perform identity-revalidated takeover. This prevents an old owner from deleting the new owner's lock and creating split brain.
+
+Doctor may safely clear a selection that points to a missing change. It does not rewrite damaged configuration, change YAML, briefs, specifications, or verification reports; repair those files manually from user intent, then inspect again.
+
+Evidence retention follows the explicit-repair boundary. Doctor reports candidates by default. `--repair` removes only active-change derived evidence or receipts that are at least 30 days old, outside the latest 32 items per evidence kind, and proven unreferenced by the dependency closure.
+
+Removal is ordered dependents before dependencies and first renames each candidate into a unique same-directory `.gc` quarantine. If interrupted before final deletion, a later read-only doctor reports `evidence-retention-recovery-required`; explicit repair restores without overwrite only when the original path remains absent and quarantine content and identity are valid.
+
+Cleanup is deferred and fails closed for original/quarantine conflicts, multiple quarantines, archived evidence, pending recovery, missing dependencies, damaged documents, unknown entries, symlinks, or other special files.

package/assets/skills/comet-native/scripts/comet-native-hook-guard.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from './comet-native-runtime.mjs';
+
+process.exitCode = await main(['hook-guard', ...process.argv.slice(2)]);