arcane-cli 0.15.4 → 0.15.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -36,18 +36,18 @@ type(scope): short description
|
|
|
36
36
|
|
|
37
37
|
### Commit Types
|
|
38
38
|
|
|
39
|
-
| Type | When to Use | Example
|
|
40
|
-
| ---------- | ----------------------------------------------- |
|
|
41
|
-
| `feat` | New feature or capability | `feat(prompts): add spell-commit-work for checkpointing`
|
|
42
|
-
| `fix` | Bug fix | `fix(auth): restore token validation after refactor`
|
|
43
|
-
| `docs` | Documentation only | `docs(decisions): add table of contents to DECISIONS.md`
|
|
44
|
-
| `refactor` | Code/structure change, no behavior change | `refactor(playbooks): reorganize setup steps`
|
|
45
|
-
| `chore` | Maintenance, deps, tooling, cleanup | `chore(deps): bump <dependency> to <version>`
|
|
46
|
-
| `test` | Adding or fixing tests | `test(security): add token-expiry test`
|
|
47
|
-
| `perf` | Performance improvements | `perf(api): reduce cold-start latency`
|
|
48
|
-
| `ci` | CI/CD pipeline changes | `ci(azure): add DevOps pipeline for repo sync`
|
|
49
|
-
| `style` | Code formatting, whitespace (rare in this repo) | `style(markdown): fix inconsistent heading levels`
|
|
50
|
-
| `revert` | Revert a previous commit | `revert: undo feat(prompts): add spell-commit-work`
|
|
39
|
+
| Type | When to Use | Example |
|
|
40
|
+
| ---------- | ----------------------------------------------- | -------------------------------------------------------- |
|
|
41
|
+
| `feat` | New feature or capability | `feat(prompts): add spell-commit-work for checkpointing` |
|
|
42
|
+
| `fix` | Bug fix | `fix(auth): restore token validation after refactor` |
|
|
43
|
+
| `docs` | Documentation only | `docs(decisions): add table of contents to DECISIONS.md` |
|
|
44
|
+
| `refactor` | Code/structure change, no behavior change | `refactor(playbooks): reorganize setup steps` |
|
|
45
|
+
| `chore` | Maintenance, deps, tooling, cleanup | `chore(deps): bump <dependency> to <version>` |
|
|
46
|
+
| `test` | Adding or fixing tests | `test(security): add token-expiry test` |
|
|
47
|
+
| `perf` | Performance improvements | `perf(api): reduce cold-start latency` |
|
|
48
|
+
| `ci` | CI/CD pipeline changes | `ci(azure): add DevOps pipeline for repo sync` |
|
|
49
|
+
| `style` | Code formatting, whitespace (rare in this repo) | `style(markdown): fix inconsistent heading levels` |
|
|
50
|
+
| `revert` | Revert a previous commit | `revert: undo feat(prompts): add spell-commit-work` |
|
|
51
51
|
|
|
52
52
|
### Scopes
|
|
53
53
|
|
|
@@ -303,10 +303,10 @@ When working across machines, topic branches are the coordination mechanism:
|
|
|
303
303
|
|
|
304
304
|
### Merge Strategy by Repo Risk
|
|
305
305
|
|
|
306
|
-
| Repo Type | Examples
|
|
307
|
-
| -------------- |
|
|
308
|
-
| **Docs repos** | docs hub, prototypes
|
|
309
|
-
| **Code repos** | application, API, storefront repos
|
|
306
|
+
| Repo Type | Examples | Merge Method | PR Required? |
|
|
307
|
+
| -------------- | ---------------------------------- | ------------ | ------------ |
|
|
308
|
+
| **Docs repos** | docs hub, prototypes | PR | Yes |
|
|
309
|
+
| **Code repos** | application, API, storefront repos | PR | Yes |
|
|
310
310
|
|
|
311
311
|
- **All repos have main branch protection.** Direct pushes to main are rejected. All changes must go through a PR.
|
|
312
312
|
|
|
@@ -319,22 +319,22 @@ When completing a PR in Azure DevOps, allow only these merge strategies by defau
|
|
|
319
319
|
|
|
320
320
|
Do **not** use Squash commit.
|
|
321
321
|
|
|
322
|
-
| Merge Type | Use? | Why
|
|
323
|
-
| --------------------------- | ------- |
|
|
324
|
-
| **Rebase and fast-forward** | **Yes** | Preserves linear history while keeping individual commits and attribution trailers intact.
|
|
325
|
-
| **Merge (no fast forward)** | **Yes** | Preserves full branch context and review traceability where explicit merge commits are preferred.
|
|
326
|
-
| Squash commit | **No** | Collapses commit history and breaks per-commit attribution/analytics and granular rollback.
|
|
327
|
-
| Semi-linear merge | No | Adds unnecessary merge commits on top of rebased commits; avoid by default.
|
|
322
|
+
| Merge Type | Use? | Why |
|
|
323
|
+
| --------------------------- | ------- | ------------------------------------------------------------------------------------------------- |
|
|
324
|
+
| **Rebase and fast-forward** | **Yes** | Preserves linear history while keeping individual commits and attribution trailers intact. |
|
|
325
|
+
| **Merge (no fast forward)** | **Yes** | Preserves full branch context and review traceability where explicit merge commits are preferred. |
|
|
326
|
+
| Squash commit | **No** | Collapses commit history and breaks per-commit attribution/analytics and granular rollback. |
|
|
327
|
+
| Semi-linear merge | No | Adds unnecessary merge commits on top of rebased commits; avoid by default. |
|
|
328
328
|
|
|
329
329
|
### Commit Governance
|
|
330
330
|
|
|
331
331
|
Commit execution rights depend on the interaction context:
|
|
332
332
|
|
|
333
|
-
| Context | Commit Behavior
|
|
334
|
-
| ----------------------------------------------------------------- |
|
|
335
|
-
| **Interactive session** (Copilot, Claude in VS Code, Claude Code) | **Must ask human** before committing. Stage changes, present proposed message, wait for approval.
|
|
336
|
-
| **Autonomous agent** at Magus+ power level
|
|
337
|
-
| **Autonomous agent** below Magus
|
|
333
|
+
| Context | Commit Behavior | Rationale |
|
|
334
|
+
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
|
|
335
|
+
| **Interactive session** (Copilot, Claude in VS Code, Claude Code) | **Must ask human** before committing. Stage changes, present proposed message, wait for approval. | Human is actively collaborating; commits are a shared decision. |
|
|
336
|
+
| **Autonomous agent** at Magus+ power level | May self-commit and self-merge within approved scope (per your power-level policy). Must use proper author/trailers. | Agent is operating independently with delegated authority. |
|
|
337
|
+
| **Autonomous agent** below Magus | Must commit to topic branch and queue merge for human review. | Insufficient autonomy level for unsupervised merges to main. |
|
|
338
338
|
|
|
339
339
|
**Interactive session rule applies to ALL interactive tools, regardless of agent identity.** Even a high-power-level agent cannot auto-commit when operating through an interactive editor session — the human is present and must approve.
|
|
340
340
|
|
|
@@ -403,19 +403,19 @@ git push origin --delete <branch> # delete remote branch (safety net —
|
|
|
403
403
|
|
|
404
404
|
**Known issues:**
|
|
405
405
|
|
|
406
|
-
| Issue
|
|
407
|
-
|
|
|
408
|
-
| Reviewer already assigned
|
|
409
|
-
| `az repos pr set-vote` succeeds but approval still blocked
|
|
410
|
-
| MCP `vote_pull_request` returns "Success" but vote stays 0
|
|
411
|
-
| `az rest --body '{"vote":10}'` fails
|
|
412
|
-
| `az repos pr update --status completed` fails with policy error
|
|
413
|
-
| MCP `create_pull_request` returns no data
|
|
414
|
-
| `gh pr create` not found
|
|
415
|
-
| `creatorVoteCounts` is false on branch policy
|
|
416
|
-
| `az repos pr update --status completed` returns `status: active` without error | PR silently not merged
|
|
417
|
-
| `git branch -d <branch>` fails after merge
|
|
418
|
-
| `git push origin --delete <branch>` fails with missing ref
|
|
406
|
+
| Issue | Symptom | Fix |
|
|
407
|
+
| ------------------------------------------------------------------------------ | ------------------------------------- | ------------------------------------------------------------------------------- |
|
|
408
|
+
| Reviewer already assigned | `reviewer add` returns already exists | Treat as idempotent success and continue |
|
|
409
|
+
| `az repos pr set-vote` succeeds but approval still blocked | Policy requires additional approver | Confirm vote state, then request second human approval |
|
|
410
|
+
| MCP `vote_pull_request` returns "Success" but vote stays 0 | `reviewer list` shows `vote: 0` | Use `Invoke-RestMethod` step 5 above |
|
|
411
|
+
| `az rest --body '{"vote":10}'` fails | Shell parsing error on Windows | Use `Invoke-RestMethod` |
|
|
412
|
+
| `az repos pr update --status completed` fails with policy error | "Needs 1 approval" | Verify `vote: 10` first, then retry |
|
|
413
|
+
| MCP `create_pull_request` returns no data | No PR ID/URL in response | Fall back to `az repos pr create` |
|
|
414
|
+
| `gh pr create` not found | `gh` CLI not installed | Use `az repos pr create` |
|
|
415
|
+
| `creatorVoteCounts` is false on branch policy | Vote registers but PR still blocked | A second human must approve via ADO web UI |
|
|
416
|
+
| `az repos pr update --status completed` returns `status: active` without error | PR silently not merged | Add `--squash false` to the command; the flag triggers the merge path correctly |
|
|
417
|
+
| `git branch -d <branch>` fails after merge | Branch is attached to a worktree | Skip local delete; run remote delete + prune |
|
|
418
|
+
| `git push origin --delete <branch>` fails with missing ref | Branch already deleted remotely | Treat as non-fatal and continue |
|
|
419
419
|
|
|
420
420
|
### Branch Lifecycle
|
|
421
421
|
|
|
@@ -482,14 +482,14 @@ See also: [Agent Workflow — Sync with main before opening a PR](#agent-workflo
|
|
|
482
482
|
|
|
483
483
|
### PR Requirements
|
|
484
484
|
|
|
485
|
-
| Requirement | Details
|
|
486
|
-
| ------------------ |
|
|
487
|
-
| **Work item link** | Optional. Linking is encouraged for traceability but enforce it only if your branch policy requires it.
|
|
488
|
-
| **Title format** | Conventional Commits format: `type(scope): description`
|
|
489
|
-
| **Description** | Must include: summary of changes, rationale, verification steps, and a linked work item ID if applicable
|
|
485
|
+
| Requirement | Details |
|
|
486
|
+
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
487
|
+
| **Work item link** | Optional. Linking is encouraged for traceability but enforce it only if your branch policy requires it. |
|
|
488
|
+
| **Title format** | Conventional Commits format: `type(scope): description` |
|
|
489
|
+
| **Description** | Must include: summary of changes, rationale, verification steps, and a linked work item ID if applicable |
|
|
490
490
|
| **Pre-PR sync** | **Mandatory rebase on latest `origin/<target>` before pushing.** See [🛑 Agent-mandatory pre-PR guard](#-agent-mandatory-pre-pr-guard) above — this applies even when opening PRs via raw `az repos pr create` / `gh pr create` / MCP tools. |
|
|
491
|
-
| **Branch cleanup** | After merge, delete the source branch (local and remote).
|
|
492
|
-
| **PR link format** | All PR references in agent output should be clickable markdown links to the PR, not a bare `PR #NNN`.
|
|
491
|
+
| **Branch cleanup** | After merge, delete the source branch (local and remote). |
|
|
492
|
+
| **PR link format** | All PR references in agent output should be clickable markdown links to the PR, not a bare `PR #NNN`. |
|
|
493
493
|
|
|
494
494
|
### Agent PR Workflow
|
|
495
495
|
|
|
@@ -522,6 +522,7 @@ Every commit must clearly identify **who produced the content** and **who approv
|
|
|
522
522
|
- If **you** wrote the content: don't override author. Your global Git config is used.
|
|
523
523
|
- If an **agent** produced the content: use `--author` to set the agent's identity.
|
|
524
524
|
- If an **interactive AI tool** (Copilot, Claude in VS Code) produced the content: use the tool-level identity.
|
|
525
|
+
- If the content is an **Arcane vendored scaffold or managed update**: do not invent a vendor email identity and do not use an agent author. Keep the operator's Git identity and record package provenance with `Vendor: arcane-cli` plus a programmatically derived `Vendor-Version` when available. Split mixed vendor/operator changes first.
|
|
525
526
|
|
|
526
527
|
### Agent Email Convention
|
|
527
528
|
|
|
@@ -531,14 +532,14 @@ Give every agent/tool a stable email under a domain you control. Most hosts trea
|
|
|
531
532
|
|
|
532
533
|
Maintain a registry of the identities you use, for example:
|
|
533
534
|
|
|
534
|
-
| Identity | Email
|
|
535
|
-
| --------------- |
|
|
536
|
-
| {OPERATOR_NAME} | `{OPERATOR_EMAIL}`
|
|
537
|
-
| {AGENT_NAME} | `{AGENT_EMAIL}`
|
|
538
|
-
| Merlin
|
|
539
|
-
| Lafayette
|
|
540
|
-
| Copilot | `copilot@{OPERATOR_DOMAIN}`
|
|
541
|
-
| Claude | `claude@{OPERATOR_DOMAIN}`
|
|
535
|
+
| Identity | Email | Type | Role |
|
|
536
|
+
| --------------- | ----------------------------- | ---------------- | -------------------------- |
|
|
537
|
+
| {OPERATOR_NAME} | `{OPERATOR_EMAIL}` | Human (owner) | — |
|
|
538
|
+
| {AGENT_NAME} | `{AGENT_EMAIL}` | Autonomous agent | Product Operations Manager |
|
|
539
|
+
| Merlin | `merlin@{OPERATOR_DOMAIN}` | Autonomous agent | CTO / Architecture Lead |
|
|
540
|
+
| Lafayette | `lafayette@{OPERATOR_DOMAIN}` | Autonomous agent | Full-Stack Developer |
|
|
541
|
+
| Copilot | `copilot@{OPERATOR_DOMAIN}` | GitHub Copilot | Tool |
|
|
542
|
+
| Claude | `claude@{OPERATOR_DOMAIN}` | Claude Code | Tool |
|
|
542
543
|
|
|
543
544
|
New agents are registered during onboarding.
|
|
544
545
|
|
|
@@ -546,19 +547,30 @@ New agents are registered during onboarding.
|
|
|
546
547
|
|
|
547
548
|
Agent-authored commits MUST include trailers in the commit message footer. Human commits MAY include them.
|
|
548
549
|
|
|
549
|
-
| Trailer | Required | Example
|
|
550
|
-
| -------------- | ----------- |
|
|
551
|
-
| `Agent` | Yes | `kellar`, `copilot`, `claude`
|
|
552
|
-
| `Model` | Yes | `claude-opus-4-20250918`, `gpt-4o`
|
|
553
|
-
| `Provider` | Yes | `anthropic`, `openai`
|
|
554
|
-
| `Role` | Recommended | `product-ops`, `developer`, `cto`
|
|
555
|
-
| `Task-Type` | Optional | `docs`, `code`, `review`, `marketing`
|
|
556
|
-
| `Approval` | Optional | `interactive`, `batch`, `post-review`
|
|
557
|
-
| `Channel` | Optional | `chat`, `cli`, `editor`
|
|
558
|
-
| `Risk-Class` | Optional | `low`, `medium`, `high`
|
|
559
|
-
| `Request-ID` | Optional | `req-001`
|
|
560
|
-
| `Session` | Optional | `session-01`
|
|
561
|
-
| `Rollback-Ref` | Optional | path or commit to the pre-change state
|
|
550
|
+
| Trailer | Required | Example |
|
|
551
|
+
| -------------- | ----------- | -------------------------------------- |
|
|
552
|
+
| `Agent` | Yes | `kellar`, `copilot`, `claude` |
|
|
553
|
+
| `Model` | Yes | `claude-opus-4-20250918`, `gpt-4o` |
|
|
554
|
+
| `Provider` | Yes | `anthropic`, `openai` |
|
|
555
|
+
| `Role` | Recommended | `product-ops`, `developer`, `cto` |
|
|
556
|
+
| `Task-Type` | Optional | `docs`, `code`, `review`, `marketing` |
|
|
557
|
+
| `Approval` | Optional | `interactive`, `batch`, `post-review` |
|
|
558
|
+
| `Channel` | Optional | `chat`, `cli`, `editor` |
|
|
559
|
+
| `Risk-Class` | Optional | `low`, `medium`, `high` |
|
|
560
|
+
| `Request-ID` | Optional | `req-001` |
|
|
561
|
+
| `Session` | Optional | `session-01` |
|
|
562
|
+
| `Rollback-Ref` | Optional | path or commit to the pre-change state |
|
|
563
|
+
|
|
564
|
+
### Vendored Framework Trailers
|
|
565
|
+
|
|
566
|
+
Vendored scaffold/update commits use these provenance trailers instead of an invented Arcane author identity:
|
|
567
|
+
|
|
568
|
+
| Trailer | Requirement | Value |
|
|
569
|
+
| ---------------- | ----------- | ------------------------------------------------------------------------------------------------------------- |
|
|
570
|
+
| `Vendor` | Required | `arcane-cli` |
|
|
571
|
+
| `Vendor-Version` | Conditional | Output of `arcane --version` / `spell --version`, whose value is read from the installed CLI's `package.json` |
|
|
572
|
+
|
|
573
|
+
Never type or infer `Vendor-Version`. If the installed CLI cannot be resolved programmatically, omit the version trailer and disclose incomplete provenance rather than guessing.
|
|
562
574
|
|
|
563
575
|
### Complete Examples
|
|
564
576
|
|
|
@@ -54,6 +54,10 @@ Workflow:
|
|
|
54
54
|
- **Invariant: one commit has exactly one author.** Changes spanning authors must be split into separate commits.
|
|
55
55
|
- Partition changed files by author first. Step 4 then groups by concern within each author partition; concern grouping must never recombine authors.
|
|
56
56
|
- **Human wrote it:** no `--author` override needed (uses global Git config)
|
|
57
|
+
- **Arcane vendored scaffold/update:** no `--author` override; the operator's Git identity records the repository action. Add `Vendor: arcane-cli` and, when derivable, `Vendor-Version: <version>` trailers.
|
|
58
|
+
- Derive the version at commit time by running `arcane --version` (or the resolved `spell --version` alias). The CLI reads its installed package's `package.json`; never type the version, copy it from memory, or infer it from the repository manifest.
|
|
59
|
+
- If the installed CLI version cannot be read programmatically, omit `Vendor-Version` and report that provenance is incomplete. Never guess.
|
|
60
|
+
- A batch mixing vendored files with human- or agent-authored changes spans provenance authors and must be split before concern grouping.
|
|
57
61
|
- **AI agent/tool produced it:** use `--author` with the agent's registered identity:
|
|
58
62
|
- Roster agent: `--author="{AGENT_NAME} <{AGENT_EMAIL}>"` — resolve `{AGENT_NAME}` / `{AGENT_EMAIL}` from the active agent config (see [[agent-policies]] / [[naming-conventions]]); ask if unset.
|
|
59
63
|
- Generic CLI/IDE tool: `--author="{TOOL_NAME} <{TOOL_NAME_LOWER}@{OPERATOR_DOMAIN}>"` — resolve `{TOOL_NAME}` from the channel in use and `{OPERATOR_DOMAIN}` from `.arcane.json`; ask if unset.
|
|
@@ -114,6 +118,8 @@ Workflow:
|
|
|
114
118
|
Agent: [lowercase-persona or tool name]
|
|
115
119
|
Model: [model identifier, e.g., claude-opus-4-20250918]
|
|
116
120
|
Provider: [anthropic or openai]
|
|
121
|
+
Vendor: [arcane-cli, for vendored scaffold/update commits]
|
|
122
|
+
Vendor-Version: [programmatically derived installed package version, when available]
|
|
117
123
|
Role: [agent role slug, if applicable]
|
|
118
124
|
Task-Type: [docs, code, review, marketing, infra]
|
|
119
125
|
Channel: [vscode, cli, chat]
|
|
@@ -126,6 +132,7 @@ Workflow:
|
|
|
126
132
|
- Reference ADRs if applicable (e.g., "Implements ADR-028")
|
|
127
133
|
- Trailers go after a blank line following the body (standard Git footer position)
|
|
128
134
|
- Required trailers for agent commits: `Agent`, `Model`, `Provider`
|
|
135
|
+
- Required trailer for Arcane-vendored commits: `Vendor: arcane-cli`; include `Vendor-Version` only when derived from the installed CLI at commit time
|
|
129
136
|
- Human-authored commits: trailers are optional
|
|
130
137
|
|
|
131
138
|
8. **Gate and execute the commit:**
|