arcane-cli 0.17.1 → 0.19.0

package/dist/assets/.arcane/governance/git-conventions.md

@@ -312,10 +312,17 @@ When working across machines, topic branches are the coordination mechanism:
 
 | Repo Type      | Examples                           | Merge Method | PR Required? |
 | -------------- | ---------------------------------- | ------------ | ------------ |
-| **Docs repos** | docs hub, prototypes               | PR           | Yes          |
+| **Docs repos** | docs hub, prototypes               | PR or local ff-only | No — see note |
 | **Code repos** | application, API, storefront repos | PR           | Yes          |
 
-- **All repos have main branch protection.** Direct pushes to main are rejected. All changes must go through a PR.
+> **Docs-only repositories.** A PR is *not* required. `cicd-standards.md` records
+> the docs-only exception (ADR-048): branch discipline still applies — branch,
+> work, then fast-forward merge — but a review gate is optional where there is no
+> build to validate. This table previously said "PR required: Yes", contradicting
+> that exception; the exception governs. Repositories that produce artifacts keep
+> the PR requirement in full.
+
+- **Code repos have main branch protection.** Direct pushes to main are rejected, and all changes go through a PR. Docs-only repositories keep branch discipline (branch → work → fast-forward merge) but may merge locally without a PR, per the exception above.
 
 #### Azure DevOps PR Merge Type
 

package/dist/assets/.arcane/governance/records-conventions.md

@@ -0,0 +1,118 @@
+---
+title: Records Conventions
+audience: both
+last_updated: YYYY-MM-DD
+status: active
+tags: [records, documentation, retention, supersession]
+---
+
+# Records Conventions
+
+How superseded documents are retained, linked to what replaced them, and when
+they may not be deleted. Applies to documentation and records repositories.
+
+## Executive Summary
+
+- A superseded document **stays where it is** and gains a tombstone header. It is
+  not moved to an archive directory.
+- Every tombstone names its replacement, so a reader who arrives at the old
+  document by an old link is never stranded.
+- Deletion is a separate, explicit decision from supersession — and some records
+  may not be deleted at all.
+- These are framework conventions, not legal advice. Where a retention
+  obligation applies, that obligation governs.
+
+---
+
+## Why in place, not an archive directory
+
+Moving a superseded document breaks every existing link to it — from other
+documents, from commit messages, from external systems, from someone's notes.
+The reader most likely to arrive at an outdated document is exactly the reader
+who needs to be told it is outdated and where to go instead, and a broken link
+cannot tell them anything.
+
+Keeping the document at its original path and marking it in place means:
+
+- Old links keep resolving, and now resolve to a page that redirects the reader.
+- The document's own history stays continuous in `git log <path>` rather than
+  splitting across a rename.
+- No repository-wide layout is imposed on subjects whose organisation is
+  determined by something other than Arcane.
+
+A universal archive directory is deliberately **not** prescribed. Where an
+external retention system is authoritative, that system's layout wins.
+
+## Tombstone header
+
+Prepend to the superseded document, above its existing content:
+
+```markdown
+> **Superseded — 2026-08-23.** Replaced by [Current Title](../path/to/replacement.md).
+> Retained for reference; do not treat as current.
+```
+
+Add the matching frontmatter so the state is machine-readable, not only prose:
+
+```yaml
+---
+status: superseded
+superseded_on: 2026-08-23
+superseded_by: path/to/replacement.md
+---
+```
+
+Rules:
+
+- `superseded_by` is required. A tombstone that does not say what replaced it is
+  worse than no tombstone: it tells the reader to stop without telling them
+  where to go.
+- If a document was superseded by *several* documents, list all of them.
+- If a document was retired without replacement, say so explicitly
+  (`superseded_by: none — <reason>`), rather than leaving the field off.
+- Do not delete the original content. The tombstone is a header, not a
+  replacement for the body.
+- **Add the reverse link on the replacement**, so the relationship is
+  discoverable from either end. A reader who finds only the current document
+  should still be able to see what it replaced:
+
+  ```yaml
+  ---
+  supersedes: path/to/old-document.md
+  ---
+  ```
+
+  One-directional linking only helps readers who arrive at the old document.
+  The reverse direction is what preserves the record's own history.
+
+## Retention and deletion
+
+Supersession and deletion are different decisions and must not be conflated.
+Marking a document superseded is a routine editorial act. Deleting it is not.
+
+**Deletion is prohibited without an explicit, recorded decision when any of the
+following is true:**
+
+- The document records a decision, agreement, or obligation that other parties
+  relied on.
+- The document is referenced by an external system, a contract, or a filing.
+- A retention period applies to it — whether by regulation, contract, or the
+  operator's own policy.
+- The repository is marked `content_sensitivity: sensitive` and the document's
+  own existence is part of the record.
+
+When deletion *is* approved, record it: what was deleted, when, on whose
+authority, and why. A deletion nobody can account for later is indistinguishable
+from data loss.
+
+**Arcane does not ship a retention schedule.** Retention periods are
+jurisdiction-, industry-, and contract-specific; a framework default would be
+guesswork wearing the costume of a standard. Record the applicable period per
+subject where one exists, and treat its absence as "unknown, therefore do not
+delete", not as "no obligation".
+
+## Related
+
+- [[DECISIONS]]
+- [[governance/decision-documentation-standard|Decision Documentation Standard]]
+- [[governance/git-conventions|Git Conventions]]

package/dist/assets/.arcane/governance/universal-agent-rules.md

@@ -72,6 +72,32 @@ See also: [[README]], [[DECISIONS]], [[governance/git-conventions|Git Convention
 
 ---
 
+## Sensitive Repositories
+
+21. **Reference, don't transcribe, when the repository is marked sensitive.** If
+    `.arcane.json` has `content_sensitivity: "sensitive"`, the repository's own
+    documents are the sensitive material — not just credentials inside them. In
+    that mode:
+    - **Cite paths, never contents.** Write "see `records/2024/lease.md`", not a
+      quotation, summary-with-details, or paraphrase of what it says. This
+      applies to journal entries, decision records, commit messages, PR
+      descriptions, and TODO items alike — every one of those is a durable,
+      often-published artifact that outlives the session.
+    - **Retain no screenshots of repository contents.** Read them, act on them,
+      then do not save them. The screenshot-curation heuristics above are
+      superseded here: "when ambiguous, save it" inverts to "when ambiguous,
+      don't."
+    - **A sanitized summary is still permitted where it carries no recoverable
+      detail** — "three lease agreements, one expiring this quarter" is fine;
+      naming the parties, addresses, sums, or dates is not.
+    - This is a governance default, not an access control. It constrains what
+      agents *write down*; it does not restrict what they may read, and it is
+      not a substitute for repository permissions or the push-safety controls in
+      `git-conventions.md`.
+    - Absent or `"standard"` means normal behaviour — this rule adds nothing.
+
+---
+
 ## Naming Conventions
 
 16. **Three naming tiers — never mix them:**

package/dist/assets/.claude/commands/spell-adopt-docs.md

@@ -0,0 +1,9 @@
+# Adopt Docs
+
+Invoke the Arcane `spell-adopt-docs` spell workflow.
+
+See the full prompt at `.github/prompts/spell-adopt-docs.prompt.md` for the complete workflow definition.
+
+---
+
+@.github/prompts/spell-adopt-docs.prompt.md

package/dist/assets/.github/prompts/spell-adopt-docs.prompt.md

@@ -0,0 +1,157 @@
+---
+name: Spell — Adopt Docs
+description: Bring an existing document tree under Arcane governance without moving anything first — inventory, propose a mapping, get approval, then apply in reversible steps. Dry-run by default.
+argument-hint: Optional path to the tree to adopt (defaults to the repository root). Add `--apply` only after reviewing a dry run.
+agent: agent
+---
+
+## Executive Summary
+
+- This spell adopts a folder of documents that already exists, rather than
+  scaffolding a new one.
+- It **never moves, renames, or deletes anything until you approve a specific
+  written mapping** — the default run is read-only.
+- It works with `subject_root: "."`, so a tree that already lives at the
+  repository root is adopted where it is. Restructuring is offered, never
+  required.
+- Every mutating phase states its rollback before it runs.
+- In a repository marked `content_sensitivity: sensitive`, the inventory records
+  paths and shapes, never document contents.
+
+---
+
+## Preconditions
+
+Stop and report, without changing anything, if any of these fail:
+
+1. **`.arcane.json` exists.** If not: "Run `spell init` first — adoption needs a
+   profile and a subject root to map into."
+2. **The working tree is clean** (`git status --porcelain` is empty). Adoption's
+   rollback story is "revert the commit"; that only works from a clean baseline.
+   Report the dirty paths and stop.
+3. **The target path exists and is inside the repository.** Reject absolute
+   paths and anything resolving outside the repo root.
+
+Read, in order: `.arcane.json` (for `subject_root`, `content_sensitivity`,
+`profile`), then `.arcane/governance/records-conventions.md`, then
+`.arcane/governance/naming-conventions.md` if installed.
+
+## Phase 1 — Inventory (always read-only)
+
+Walk the target tree and build a picture of what is actually there. Do not open
+a document to summarize its subject matter; classify from path, name, extension,
+and size.
+
+Report:
+
+- **Total counts** by extension, and total size.
+- **Depth and shape** — how deep the tree goes, which directories hold the bulk.
+- **Naming patterns observed** — dated (`2024-03-01-...`), numbered, free-form,
+  or mixed. Report what you see; do not judge it yet.
+- **Collisions with Arcane's own layout** — anything already at `TODO.md`,
+  `DECISIONS.md`, `IDEAS.md`, `README.md`, `journal/`, `.arcane/`, `.github/`,
+  `.claude/`. These are the only paths where adoption could overwrite something.
+- **Files Git will treat as binary** under the installed `.gitattributes`, and
+  any that are large enough to be worth an explicit LFS decision later.
+- **Anything unreadable** — permission errors, broken symlinks, zero-byte files.
+  Report them; never silently skip.
+
+**If `content_sensitivity` is `"sensitive"`:** the inventory is paths, counts,
+extensions and sizes only. Do not quote filenames that are themselves revealing
+in the session summary — say "12 files under `clients/`", not the list — and do
+not open documents to characterize their contents.
+
+## Phase 2 — Propose a mapping
+
+Produce a written proposal. This is the artifact the operator approves, and it
+must be specific enough that they can predict every effect.
+
+For each group of files, state one of:
+
+| Disposition | Meaning |
+|---|---|
+| **Leave in place** | No move. The default, and the right answer for most trees. |
+| **Move** | Old path → new path, explicitly, per file or per directory. |
+| **Rename** | Old name → new name, with the rule that produced it. |
+| **Ignore** | Added to `.gitignore` rather than governed. |
+| **Flag** | Needs an operator decision this spell will not make (see below). |
+
+Always also state:
+
+- **What `subject_root` will be** afterwards, and whether adoption changes it.
+  If the tree is already at the repository root, propose `"."` and say plainly
+  that this means no restructuring.
+- **Which collisions from Phase 1 you propose to resolve, and how.** Never
+  propose overwriting an existing `TODO.md`/`DECISIONS.md`/`README.md`; propose
+  merging or leaving the operator's file untouched.
+- **What will NOT be touched** — an explicit list is part of the proposal, not
+  an omission from it.
+
+Flag rather than decide:
+
+- Anything that looks like credentials, keys, or personal data.
+- Anything suggesting a retention obligation (contracts, filings, tax records)
+  — see `records-conventions.md`; deletion and relocation of those is an
+  operator decision.
+- Superseded-looking duplicates (`final-v2-FINAL.docx`). Propose the tombstone
+  convention from `records-conventions.md`; do not pick a winner.
+
+End with: **"Approve this mapping? (yes / edit / cancel)"** and stop. A dry run
+ends here, always.
+
+## Phase 3 — Apply (only after explicit approval, and only with `--apply`)
+
+Apply in the order below. Each step states its rollback *before* it runs, and
+each step is a separate commit. Revert them in reverse order — reverting an
+earlier phase while a later one still stands will conflict, because the later
+phase built on the paths the earlier one created.
+
+1. **Write `subject_root` to `.arcane.json`** (if it changes).
+   *Rollback: revert the commit; no files moved yet.*
+2. **Add ignore entries** for anything dispositioned "Ignore".
+   *Rollback: revert the commit; files are untouched on disk either way.*
+3. **Renames**, using `git mv` so history follows the file.
+   *Rollback: revert the commit. If a rename collides with an existing path,
+   stop the whole phase — do not overwrite, do not continue to step 4.*
+4. **Moves**, using `git mv`, deepest paths first so parent directories are
+   never removed out from under a pending move.
+   *Rollback: revert the commit.*
+5. **Tombstones** for anything the operator confirmed as superseded, per
+   `records-conventions.md`.
+   *Rollback: revert the commit; original content was never deleted.*
+
+Hard rules for this phase:
+
+- **Never delete a document.** Adoption moves, renames, and marks. Deletion is a
+  separate, explicit operator decision (`records-conventions.md`).
+- **Never overwrite an existing file.** On any collision, stop and report.
+- **Stop at the first failure.** Do not attempt partial recovery mid-phase —
+  report what completed, what did not, and the exact `git revert` command for
+  each commit already made.
+- If the repository is `content_sensitivity: sensitive`, commit messages name
+  paths and counts only, never contents.
+
+## Phase 4 — Report
+
+Output:
+
+```
+Adopted <N> files under {SUBJECT_ROOT}
+
+Moved      <n>   (commit <sha>)
+Renamed    <n>   (commit <sha>)
+Tombstoned <n>   (commit <sha>)
+Left as-is <n>
+Ignored    <n>
+Flagged    <n>   — needs your decision, listed below
+```
+
+Then list every flagged item with the decision it needs. Finish with the
+suggested next step: `spell-todo` to capture the flagged decisions, or
+`spell-commit-work` if anything remains uncommitted.
+
+## Related
+
+- [[.arcane/governance/records-conventions|Records Conventions]] — supersession and retention
+- [[.arcane/governance/git-conventions|Git Conventions]] — branch and merge discipline
+- [[.arcane/governance/universal-agent-rules|Universal Agent Rules]] — sensitive-repository behaviour

package/dist/assets/.github/prompts/spell-close-session.prompt.md

@@ -102,6 +102,10 @@ Rules:
    - If screenshots were provided during the session, reference them in troubleshooting or journal entries.
 
 7. **Process screenshots** (if provided during the session).
+   - **First check `content_sensitivity` in `.arcane.json`.** If it is
+     `"sensitive"`, retain no screenshots of repository contents and transcribe
+     nothing from them into the journal — record the document path instead. See
+     universal-agent-rules.md, "Sensitive Repositories".
    - Screenshots should already be saved to `assets/screenshots/YYYY-MM-DD/` — agents must save them immediately when the user pastes them (see global screenshot rule in `copilot-instructions.md`).
    - At close-session time, review all screenshots saved during the session.
    - Keep only screenshots that provide durable evidence for journal/runbook documentation.

package/dist/assets/docs-baseline/gitattributes

@@ -0,0 +1,53 @@
+# Line-ending baseline (EF-17). Text normalizes to LF in the repository and
+# checks out per-platform; binary formats are marked so Git never rewrites or
+# diffs them as text.
+* text=auto eol=lf
+
+# Documents — binary. Office formats are ZIP containers: a line-ending rewrite
+# corrupts them, and a textual diff is noise either way.
+*.pdf   binary
+*.docx  binary
+*.doc   binary
+*.xlsx  binary
+*.xls   binary
+*.pptx  binary
+*.ppt   binary
+*.odt   binary
+*.ods   binary
+*.odp   binary
+*.rtf   binary
+
+# Images
+*.png   binary
+*.jpg   binary
+*.jpeg  binary
+*.gif   binary
+*.bmp   binary
+*.tif   binary
+*.tiff  binary
+*.webp  binary
+*.ico   binary
+*.heic  binary
+
+# Scans and audio/video attachments commonly filed with records
+*.mp3   binary
+*.mp4   binary
+*.mov   binary
+*.wav   binary
+
+# Archives
+*.zip   binary
+*.7z    binary
+*.gz    binary
+*.tar   binary
+
+# Fonts
+*.woff  binary
+*.woff2 binary
+*.ttf   binary
+*.otf   binary
+
+# Git LFS is deliberately NOT configured here. It requires server-side support
+# and changes clone behaviour for everyone, so it is an opt-in decision rather
+# than a default. Consider it when a binary is large or changes often -- once
+# a large file is committed without LFS, removing it needs a history rewrite.

package/dist/assets/docs-baseline/gitignore

@@ -0,0 +1,15 @@
+# Editor and OS noise
+.DS_Store
+Thumbs.db
+Desktop.ini
+*~
+.*.swp
+
+# Office lock/temp files — these appear whenever a document is open and must
+# never be committed.
+~$*
+*.tmp
+
+# Local-only working area. Anything here is yours and is never installed,
+# updated, or read by Arcane.
+.local/