Lane C: CLI commands and the orca-dart skill

Base: upstream main 51e183a08e0 (fork fast-forwarded 2026-10-31). See "Revision 2026-10-31" at the end.

Goal: agents can read and update Dart tasks with orca dart ..., guided by a bundled orca-dart skill that installs from the Dart card.
Delivers: G4 (CLI and skill half; the install row on the card is Lane B).
Depends on: Lane 0 merged (it already provides ORCA_DART_SKILL_NAME); Lane A RPC methods for the final live run, read-only. Input: the user's existing skill at the existing local Dart skill (Nyayasathi project) (SKILL.md, README.md; it uses OAuth and npm run dartai, which the Orca skill replaces with orca dart ...).

Files owned (about 6 new and 5 edits for the CLI, plus skill sources)

New: src/cli/handlers/dart.ts and src/cli/handlers/dart-write.ts (handlers stay in src/cli/handlers/, like Jira's, because src/cli/handler-group-manifest.test.ts:9 scans only that folder for unroutable handler keys), src/cli/dart/ (handler group, request builders, formatters, target gate), src/cli/specs/dart.ts (command specs), skill-guides/orca-dart.md, skill-stubs/orca-dart.md.
Templates (current upstream Jira CLI, flat layout): src/cli/jira-handler-group.ts, src/cli/jira-target.ts, src/cli/jira-format.ts, src/cli/handlers/jira.ts, src/cli/handlers/jira-write.ts, src/cli/specs/jira.ts, and the shipped orca-jira skill (skill-guides/, skill-stubs/orca-jira.md, skill-stubs/_shared), including its safe-write rules. Putting Dart under src/cli/dart/ instead of flat is a deliberate choice to keep upstream merges small.
Edit: src/cli/handler-group-manifest.ts (add DART_HANDLER_GROUP beside JIRA_HANDLER_GROUP and LINEAR_HANDLER_GROUP; the file also has PLUGIN_HANDLER_GROUPS now), src/cli/specs/index.ts (beside JIRA_COMMAND_SPECS), src/main/startup/cli-command-names.ts:46-47 (add 'dart' beside 'jira' and 'linear'; src/cli/specs/cli-command-names-parity.test.ts derives roots from COMMAND_SPECS and fails until it is added), config/scripts/generate-bundled-skill-guides.mjs (three literal edits at :15-55: 'orca-dart' in CANONICAL_GUIDE_NAMES, 'orca-dart': [] in GUIDE_ALIASES, and an orca-dart entry in STUB_TOPICS backed by skill-stubs/orca-dart.md). src/cli/reference-input.ts is not edited in v1 (Jira's equivalent uses a summary-lookup method that the Dart contract does not have). src/cli/args.ts is NOT edited: upstream replaced its hand-listed command roots with spec.browserPageTarget (args.ts:138-139), so a dart spec needs no args.ts change (leave browserPageTarget unset).
Generated (run, do not hand-edit): skills/orca-dart/SKILL.md, src/cli/bundled-skill-guides.ts, resources/skills/*, bundled-skill-sources.ts via pnpm generate:bundled-skill-guides and pnpm generate:skill-bundle-manifest, run on the new base (do not reuse any output generated on the old base).

Must not touch

The Dart card component (Lane B owns it; Lane C only supplies the skill name constant). Ship only orca-dart; alias and stub entries are add-only, so add no dart-tickets. The upstream orca plugin command group (stablyai#36280, stablyai#36288) is unrelated; do not touch it.

Check first (on the new base)

1. The guide generator changed (-57 lines): guide markdown is serialized one line at a time (build: serialize bundled guides one markdown line at a time stablyai/orca#33712), and fullMarkdown/composeFullMarkdown was replaced by a references array. Read the script and the orca-jira guide before writing orca-dart.
2. Whether skill-stub-composition.mjs and skill-stubs/_shared impose a shape on a new stub (unverified); copy skill-stubs/orca-jira.md.

Steps

1. Commands (JSON-first), each backed by a Lane 0 contract method: orca dart status (dart.status), config (dart.config: dartboards, statuses, tags, priorities, assignees by name), list (--mine uses the user id from dart.status; status, dartboard, tag, priority; --title maps to Dart's title filter; add --text only if Lane P confirms a parameter that also searches descriptions, so the flag never promises more than it does; dart.listTasks), get <id|url> (dart.getTask), comment list|add, create (dart.createTask), update (dart.updateTask: status, priority, assignee, tags, title, description, by name). Version 1 has no key lookup: accept id or htmlUrl. The CLI never sends no_defaults=false and rejects unknown filter flags itself, because Dart ignores unknown parameters silently. Failures print the host's English error string and its dart.* errorCode (taskProviderFailure returns { ok: false, error, errorCode }; only the renderer localizes, the CLI has no copy map).
2. Gate, like the Jira target gate (src/cli/jira-target.ts:38-45): every orca dart command first calls status.get; if the runtime does not advertise dart.provider.v1, it throws RuntimeClientError('incompatible_runtime', 'Update Orca on the execution host to use Dart.') and exits non-zero. Test with a capability-less runtime.
3. Skill guide: command reference, untrusted-data rule for task text, the API gaps (no key, no status graph, substring search), how to resolve names via orca dart config, and safe-write rules modelled on orca-jira. Start from the user's existing skill; keep what it learned.
4. Generate and verify the bundle.

Guide rules (a test enforces them)

src/cli/specs/bundled-guide-flags.test.ts extracts every ORCA <cmd> --<flag> example from the bundled guides (now also from guide.references[*].markdown) and validates it against COMMAND_SPECS. Every command and flag in skill-guides/orca-dart.md must exist in src/cli/specs/dart.ts; write the guide from the spec, not from memory. Edit only the sources (skill-guides/, skill-stubs/); skills/orca-dart/SKILL.md, src/cli/bundled-skill-guides.ts and bundled-skill-sources.ts are generated. --reference <dart-id> is not supported in v1: reference-input.ts accepts Jira keys and full URLs only.

Done when

• pnpm test src/cli/specs/bundled-guide-flags.test.ts src/cli/specs/cli-command-names-parity.test.ts src/cli/handler-group-manifest.test.ts passes, plus a key-parity test: the keys of COMMAND_SPECS whose path starts with dart equal DART_HANDLER_GROUP.keys, and a direct assertion that CLI_COMMAND_NAMES contains 'dart'.
• CLI parse and format tests pass (mock-backed); the capability gate test passes; help text lists orca dart.
• pnpm verify:bundled-skill-guides and pnpm verify:skill-bundle-manifest pass.
• Live run (orchestrator or user step, not the lane worker, since workers never receive the token): with Lane A running against the Lane P credential in an isolated profile, orca dart status and list return real data, read-only (create and update only against mocks unless the user names a throwaway dartboard). The lane report records "live run by "; no token or real names and ids in any committed output.

Revision 2026-10-31 (b): OMP review applied

1. Handlers live in src/cli/handlers/dart*.ts so the manifest drift test covers them; key-parity and CLI_COMMAND_NAMES assertions added.
2. The three generator edits spelled out.
3. --title instead of --text unless Lane P confirms description search.
4. Gate written out (status.get, dart.provider.v1, incompatible_runtime, message, test).
5. The live run is an orchestrator or user step; the lane's own acceptance is mock-backed.

Revision 2026-10-31

1. Re-based on 51e183a08e0; full paths for every file.
2. Removed src/cli/args.ts from "Edit": obsolete, browser-page support is now spec.browserPageTarget.
3. Named the real Jira CLI template files and the shipped orca-jira skill as templates.
4. Added "Check first" for the changed guide generator (line-by-line serialization, references array) and the stub composition; regenerate on the new base.
5. Noted the new PLUGIN_HANDLER_GROUPS and orca plugin group (no overlap).