provenance-cli 0.1.0__tar.gz → 0.2.0__tar.gz

provenance_cli-0.2.0/.agents/skills/spec-capture-expectations/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: spec-capture-expectations
+version: "1.0"
+description: "Extract implicit user expectations and compile them into the spec. Use when starting a session or picking up a new task, when user words imply a behavior, constraint, or rule not yet in the spec, when a request reveals an assumption, edge case, or threshold to write down, or when deciding whether to add or update a spec entry."
+triggers:
+  - session start or picking up a new task
+  - user words imply a behavior, constraint, or rule not yet in the spec
+  - request reveals an assumption, edge case, or threshold to write down
+  - deciding whether to add or update a spec entry
+---
+
+## Mission
+
+On every task, extract implicit user expectations and compile them into the spec so the spec remains the single, correct record of what the user expects — not what was guessed or left in conversation.
+
+---
+
+## Pre-requisites
+
+- **Spec directory** present: `prov/`, `spec/`, or `specs/`.
+- **Read access** to existing spec files (to check what is already captured).
+- **Write access** to spec files when adding or updating entries (only after user confirms in Phase 3 of the request flow).
+
+---
+
+## Instructions
+
+### Step 1 — Before acting, run the five questions
+
+For the current request, answer (see Reference for detail):
+
+1. Is there a behavior implied here that is not yet in the spec?
+2. Would a future reader of the spec infer the same thing the user expects?
+3. Is there a number, threshold, limit, or edge case the user assumed?
+4. Does this reveal a domain-wide constraint ("always", "never")?
+5. Is an existing entry now wrong or incomplete?
+
+### Step 2 — Decide: add, update, or skip
+
+Use the tables in Reference: **When to add a new entry** and **When NOT to add**. Add when user states or implies a behavior, specifies a constraint, an edge case is missing, or a bug fix reveals correct behavior never specified. Do not add for competent-developer defaults, implementation-only details, or duplicates.
+
+### Step 3 — Record implicit expectations in the right form
+
+- User’s words reveal unstated behavior → add requirement with `> user: "exact quote"` and `~` when implemented (see Reference example).
+- You infer a value they didn’t give (e.g. "keep it fast") → add entry with `> inferred: reasoning` and `  ! assumed <value> — <reason unconfirmed>`. Surface the `!` in Phase 3; user confirms, corrects, or defers (see Reference example).
+
+### Step 4 — Apply assumption discipline
+
+Every gap you fill on the user’s behalf gets a `!` line. When surfacing `!`: **Confirm** → remove `!`; **Correct** → rewrite statement, remove `!`; **Defer** → keep `!` (it will appear in every future diff until confirmed). See Reference → Assumption discipline.
+
+### Step 5 — Feed into the request flow
+
+All new or changed entries are proposed in Phase 3 and written in Phase 4 of the request flow. Do not add entries without going through the flow (propose → confirm → write).
+
+---
+
+## Reference
+
+### The principle
+
+Every task is a chance to compile user intent into the spec. A well-maintained spec is one where a fresh agent, given only the spec and no prior context, would produce a system that matches everything the user actually expects. Never leave expectations only in code or only in conversation — compile them.
+
+### Five questions (detail)
+
+1. **Is there a behavior implied here that is not yet written in the spec?** If the user's request assumes something works a certain way and the spec doesn't say so, that's a missing entry.
+2. **Would a future reader of the spec infer the same thing the user expects?** If not, update the entry — wrong statement, missing constraint, wrong scope.
+3. **Is there a number, threshold, limit, or edge case the user assumed?** Record in the spec with a `!` line if unconfirmed, or as a confirmed statement if they said it.
+4. **Does this reveal a domain-wide constraint?** If the user says "always", "never", or "under no circumstances", that's a `C:slug:` constraint entry, not just a requirement.
+5. **Is an existing entry now wrong or incomplete?** The new request may reveal that an old entry was imprecise; update it in the same task.
+
+### When to add a new entry
+
+| Signal | Action |
+|--------|--------|
+| User states a behavior explicitly | Add requirement entry with `> user: "their words"` |
+| User implies a behavior ("obviously it should...") | Add entry with `> inferred: <reasoning>` and `!` line |
+| User specifies a constraint ("always", "never", "required") | Add `C:slug:` constraint entry |
+| User's request would fail in an edge case not yet covered | Add entry for that edge case |
+| Fixing a bug reveals the correct behavior was never specified | Add entry for the correct behavior |
+| User corrects the agent's assumption | Remove `!`, update the statement to match the correction |
+
+### When NOT to add a new entry
+
+- Competent-developer defaults (error handling, logging patterns, standard HTTP responses) — skip.
+- Implementation details the user never mentioned and that don't affect user-observable behavior — skip.
+- Anything already correctly covered by an existing entry — skip; don't duplicate.
+
+### How to record an implicit expectation — examples
+
+**User's words reveal unstated behavior:**
+
+```
+user: "make sure the export always includes the full history"
+```
+
+→ Add:
+
+```
+export-full-history: Exports always include the complete history of the record.
+  > user: "make sure the export always includes the full history"
+  ~ src/exports/history.py
+```
+
+**You infer a value they didn't give:**
+
+```
+user: "keep it fast"
+```
+
+→ "Fast" is unspecified. Add:
+
+```
+export-performance: Export completes within 5 seconds for records up to 10,000 entries. [planned]
+  > inferred: user said "keep it fast" — interpreted as 5s / 10k entries
+  ! assumed 5s / 10k entries — "fast" is unconfirmed
+```
+
+Surface the `!` in Phase 3. The user either confirms, corrects, or defers.
+
+### Assumption discipline
+
+- `!` = "I decided this; the user has not confirmed it."
+- No `!` = "The user said this, or it's an unambiguous default."
+- When you surface a `!` to the user: **Confirm** → remove `!` (becomes user-specified). **Correct** → rewrite statement, remove `!`. **Defer** → keep `!`; do not remove it; it will appear in every future diff until the user explicitly confirms. The `!` is the record that this was not their explicit choice.
+
+### The compounding spec
+
+Over time, with every task handled this way, the spec converges on a complete, accurate picture of user intent. Each task adds signal. The spec becomes the memory of the system — not what the agent guessed, not what was obvious in the moment, but what the user actually wants. Never leave an expectation only in code. Never leave it only in conversation. Compile it.
+
+---
+
+## Error Handling
+
+| If this happens | Do this |
+|-----------------|--------|
+| You're unsure whether something is user expectation or implementation detail | Prefer capturing it with a `!` line so the user can confirm or remove. Do not leave it only in code. |
+| User said something vague ("fast", "simple") and you chose a concrete value | Add a `!` line stating the assumed value and that the original was unconfirmed. Surface in Phase 3; do not remove `!` without user action. |
+| You find an existing entry that's wrong but the user didn't ask to change it | Include the correction in your Phase 3 proposal ("I'm also updating X because the current spec says Y and the code/behavior is Z"). Get explicit confirmation. |
+| You already added an entry and the user says "that's not what I meant" | Treat as correction: update the statement and provenance, remove or adjust `!`. Do not leave the wrong entry in place. |
+| Multiple possible interpretations of the user's words | Propose one interpretation with a `!` line; in Phase 3 list the alternatives and ask which one they want. Do not implement until they choose. |

provenance_cli-0.2.0/.agents/skills/spec-drift-sync/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: spec-drift-sync
+version: "1.0"
+description: "Resolve drift between spec and code with the sync protocol, applying only user-confirmed fixes. Use when running prov sync or prov reconcile, after bulk refactors, large merges, or importing existing code, when the user asks to reconcile spec and code, or after autonomous code changes that may have left the spec out of date."
+triggers:
+  - running prov sync or prov reconcile
+  - after bulk refactors, large merges, or importing existing code
+  - user asks to reconcile spec and code
+  - after autonomous code changes that may have left spec out of date
+---
+
+## Mission
+
+Resolve drift between spec and code by running the sync protocol, presenting each drift item to the user with context, and applying only user-confirmed fixes so that spec and code match.
+
+---
+
+## Pre-requisites
+
+- **prov CLI** with `prov sync` and `prov reconcile` (and patch subcommands: `mark-implemented`, `remove-ref`, `update-ref`, `remove-backlink`). If prov is not available, document that drift resolution was skipped.
+- **Spec directory** and **codebase** in the same repo (or paths known).
+- **Read access** to spec files and code; **write access** to spec files (and optionally code for removing backlinks) after user confirms.
+
+---
+
+## Instructions
+
+### Step 1 — Run the drift report
+
+Run `prov sync <path>` (e.g. `prov sync src/`) or `prov reconcile <path>` for read-only. Read the full output. Identify each reported item by type (silent implementation, phantom slug, dead ref). See Reference → What drift is.
+
+### Step 2 — Present each item to the user
+
+For each drift item: state type, slug, and location (file, line or path). State what the spec currently says vs what the code currently does. Offer the resolution options from Reference → Resolution by type. Ask: "What should I do?" Do not apply any fix until the user answers. Use the example presentation format in Reference if helpful.
+
+### Step 3 — Apply only confirmed fixes
+
+Use the exact commands in Reference → Patch commands. For silent implementation: `mark-implemented` or `remove-backlink`. For phantom slug: add entry via request flow or `remove-backlink`. For dead ref: `update-ref` or `remove-ref` (and consider `[planned]` or removing the entry). Only after user confirms each item.
+
+### Step 4 — Validate and commit
+
+Run `prov validate` (zero errors). Run `prov diff`. Commit spec (and any code changes) with a message such as `spec: reconcile src/<path>`.
+
+### Step 5 — After autonomous code changes
+
+When the agent made code changes without the normal request flow (e.g. bulk refactor, automated migration), run `prov sync src/` before committing and include a short drift summary in the PR description. See Reference → After autonomous code changes.
+
+---
+
+## Reference
+
+### What drift is
+
+Drift is a gap between what the spec says and what the code does. Three types:
+
+| Type | Description | Detected by |
+|------|-------------|-------------|
+| **Silent implementation** | `[planned]` entry but code already has `spec:` backlink | `prov sync` |
+| **Phantom slug** | `spec:` in code references a slug with no spec entry | `prov sync` |
+| **Dead ref** | `~` path in spec no longer exists as a file or directory | `prov sync` |
+
+### Example presentation to the user
+
+```
+SILENT IMPLEMENTATION: session-expiry
+  Spec says: [planned]
+  Code has:  # spec: session-expiry  in src/middleware/session.py:44
+
+  Options:
+    A. Mark as implemented — remove [planned], the code ref counts
+    B. Remove the backlink — code shouldn't claim to implement this yet
+    C. Skip — leave it as-is for now
+
+  What should I do?
+```
+
+### Patch commands (apply only after user confirms)
+
+```bash
+# Silent implementation → mark as implemented
+prov sync mark-implemented <slug>
+
+# Phantom slug → remove the backlink (if the slug shouldn't exist)
+prov sync remove-backlink <file> <line> <slug>
+# or → add the missing spec entry via request flow (if the code is correct)
+
+# Dead ref → remove the stale path
+prov sync remove-ref <slug> <ref>
+# or → update to the new path
+prov sync update-ref <slug> <old-path> <new-path>
+```
+
+### Resolution decisions by drift type
+
+**Silent implementation** — Spec says `[planned]` but the code already implements it.
+
+- **Mark implemented** (`prov sync mark-implemented <slug>`): The implementation is correct and complete. Remove `[planned]`, add `~` ref.
+- **Remove backlink** (`prov sync remove-backlink ...`): The code should not claim to implement this yet. The spec's `[planned]` is correct.
+
+**Phantom slug** — Code has `# spec: some-slug` but `some-slug` doesn't exist in the spec.
+
+- **Add the spec entry**: The code is right; the spec is missing the entry. Go through request flow Phase 3 → 4. Use provenance `> code: <file:line> — phantom slug, prov sync; user confirmed spec entry` and `! statement inferred from implementation — user confirmed after sync`. See spec-entry-format for provenance source types.
+- **Remove the backlink**: The `spec:` comment is wrong or outdated.
+
+**Dead ref** — A `~` path in the spec no longer exists.
+
+- **Update the ref** (`prov sync update-ref ...`): The file moved or was renamed. Update to the new path.
+- **Remove the ref** (`prov sync remove-ref ...`): The code was deleted. The implementation is gone; the entry may need `[planned]` restored or be removed entirely.
+
+### After autonomous code changes
+
+When the agent has made code changes without going through the normal request flow (e.g. bulk refactor, automated migration), always run reconcile before committing:
+
+```bash
+prov sync src/        # full drift report
+prov validate         # confirm zero errors
+prov diff             # review spec changes
+```
+
+Include the drift summary in the PR description so the human reviewer can see what changed in the spec alongside the code.
+
+### Read-only drift check
+
+To see drift without applying any fixes:
+
+```bash
+prov reconcile src/              # full read-only report
+prov reconcile src/ --since HEAD  # since last commit (if supported)
+```
+
+Output sections: PHANTOM SLUGS, SILENT IMPLEMENTATIONS, DEAD REFS, CLEAN (if none).
+
+### Provenance for entries added from code
+
+When adding a spec entry for a phantom slug (code has `spec:` but no entry), the entry is code-derived:
+
+- **Provenance**: `> code: <file:line> — phantom slug, prov sync; user confirmed spec entry`
+- **Assumption**: `! statement inferred from implementation — user confirmed after sync`
+- Always pair `code:` provenance with `!` until the user explicitly confirms the statement reflects their intent.
+
+---
+
+## Error Handling
+
+| If this happens | Do this |
+|-----------------|--------|
+| **Silent implementation** — spec has `[planned]` but code has `spec:` | Present options: A. Mark implemented (update spec, add `~`). B. Remove backlink (code shouldn't claim it yet). C. Skip. Do not choose for the user. |
+| **Phantom slug** — `spec:` in code but no spec entry | Present options: A. Add the spec entry (via request flow). B. Remove the backlink. Do not add an entry without user confirmation. |
+| **Dead ref** — `~` path in spec does not exist | Present options: A. Update ref to new path. B. Remove ref (and possibly set entry back to `[planned]` or remove entry). Do not leave a `~` pointing at a missing file. |
+| User says "skip" or "leave it for now" for an item | Do not apply any fix for that item. Move to the next item. You may note in the commit message that some drift was left unresolved. |
+| `prov sync` or `prov reconcile` is not available | Do not invent patch commands. Tell the user that drift was detected but prov sync is required to fix it; list the drift items you can infer from grep/code inspection if possible. |
+| After applying fixes, `prov validate` still reports errors | Fix the new errors (e.g. duplicate slug, missing `>`, dangling ref). Do not commit until validate passes. |

provenance_cli-0.2.0/.agents/skills/spec-entry-format/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: spec-entry-format
+version: "1.0"
+description: "Apply the correct spec entry format: node types, sigils, provenance, backlinks, and commit messages. Use when writing or editing spec files, adding or updating ~ code refs or spec: backlinks, reading an unfamiliar spec entry, or checking commit or entry format."
+triggers:
+  - writing or editing spec files
+  - adding or updating ~ code refs or spec: backlinks
+  - reading an unfamiliar spec entry
+  - checking commit or entry format
+---
+
+## Mission
+
+Apply the correct spec entry format (node types, sigils, invariants, backlinks, commit messages) so the parser and grep-based retrieval work and the spec stays valid.
+
+---
+
+## Pre-requisites
+
+- **Spec directory** present: `prov/`, `spec/`, or `specs/`.
+- **grep** (or equivalent) for slug checks and pattern search.
+- **prov CLI** (optional): `prov check-slug`, `prov validate`. If absent, use `grep -r "^<slug>:" spec/` for slug availability.
+
+---
+
+## Instructions
+
+### Step 1 — Before writing any entry: check slug
+
+Run `prov check-slug <proposed-slug>` or `grep -r "^<proposed-slug>:" spec/`. If the slug exists, pick a different one or edit the existing entry. Slugs: kebab-case, 2–4 words, describe **behavior** not domain (see Reference → Slug rules).
+
+### Step 2 — Use the correct node type and structure
+
+Use **Requirement**, **Constraint**, or **Question** format from Reference. Each has a statement line and sub-lines with `  >`, `  !`, `  @`, `  ?`, `  ~` (each on its own line, exactly 2-space indent).
+
+### Step 3 — Enforce file invariants
+
+Every primary entry at **column 0**. Every sub-line **exactly 2 spaces** (not 4, not tab). Sigils only on their own sub-lines; never inline in the statement. One statement line per entry. See Reference → File format invariants.
+
+### Step 4 — Add code backlinks when implementing
+
+In code, at the top of each function/class/block that implements a spec entry: `# spec: slug` (or `// spec: slug`). Multiple slugs: `# spec: slug-a, C:slug-b`. One comment per logical block. See Reference → Code backlinks.
+
+### Step 5 — Use the correct commit format
+
+See Reference → Commit format. Spec-only vs code+spec; always include the `spec: ...` line when code and spec change together.
+
+---
+
+## Reference
+
+### Reading an entry — anatomy
+
+```
+session-expiry: Sessions expire after 30 days of inactivity.
+  > inferred: user said "standard session timeout, nothing crazy" — interpreted as 30 days
+  ! assumed 30 days — "nothing crazy" is unconfirmed
+  @ C:jwt-stateless
+  ~ src/middleware/session.py:44
+  ~ src/middleware/session.py:101
+```
+
+| Part | Meaning |
+|------|---------|
+| `session-expiry` | Slug — permanent, globally unique. Used in `spec:` backlinks in code. |
+| Statement | What the system does. Current state only. |
+| `>` | Provenance — use source prefix: user, inferred, code, regulatory, derived. See Provenance source types below. |
+| `!` | Agent filled this in; user has not confirmed it. |
+| `@` | This entry depends on another slug. |
+| `~` | Code implementing this entry. One line per ref. |
+| `[planned]` | Not yet implemented. No `~` lines. Remove when implemented. |
+
+### Provenance source types
+
+Every `>` line must identify where the entry came from. Use exactly one of these — do not invent new types.
+
+| Type | Format | When used | `!` required? |
+|------|--------|-----------|---------------|
+| user | `> user: "exact words"` | Direct quote from user | No |
+| inferred | `> inferred: reasoning` | Agent interpretation of user intent | Yes |
+| code | `> code: path — context` | Discovered during sync, drift, reverse-engineering | Yes |
+| regulatory | `> regulatory: source — citation` | Legal, compliance, platform requirement | No |
+| derived | `> derived: slug — reasoning` | Logical consequence of another entry | No |
+
+For Q nodes: `> blocks: slug` remains valid.
+
+Examples:
+
+```
+> user: "we'll just do Google login for now"
+
+> inferred: user said "nothing crazy" for timeout — interpreted as 30 days
+! assumed 30 days — not confirmed
+
+> code: src/auth/google.py — phantom slug, prov sync 2026-03-10
+! statement inferred from implementation — user confirmed after sync
+
+> regulatory: GDPR Article 17 — right to erasure within 30 days
+
+> derived: C:jwt-stateless — stateless tokens can't maintain server-side revocation list
+```
+
+### Node types at column 0
+
+```
+slug:    requirement — user-observable behavior
+C:slug:  constraint  — non-negotiable rule governing a domain
+Q:slug:  question    — unresolved decision blocking implementation
+```
+
+Sub-lines always 2-space indent. Never 4 or tab.
+
+### Slug rules
+
+- kebab-case, 2–4 words, describe **behavior** not domain.
+- Good: `session-expiry`, `guest-access`. Bad: `auth-session` (domain prefix), `limit` (too vague).
+
+### Requirement format
+
+```
+slug: Statement describing user-observable behavior. [planned if not yet coded]
+  > user: "exact quote" | inferred: reasoning | code: path — context | regulatory: source — citation | derived: slug — reasoning
+  ! assumption (required for inferred and code; only when agent filled a gap)
+  @ dependency-slug (if this entry depends on another slug)
+  ? Q:blocking-question (if blocked by an open question)
+  ~ src/path/to/file.py:line (one per line, only when implemented)
+```
+
+### Constraint format
+
+```
+C:slug: Non-negotiable rule statement.
+  > user: "exact quote" or regulatory: source — citation
+```
+
+### Open question format
+
+```
+Q:slug: Question that must be resolved before implementation?
+  > blocks: slug-of-the-requirement-it-blocks
+```
+
+### File format invariants — never violate
+
+1. Every primary entry starts at **column 0**. No leading spaces.
+2. Every sub-line is indented **exactly 2 spaces**. Not 4. Not a tab.
+3. The `~` sigil appears only on its own sub-line. Never inline in the statement.
+4. Each entry has one statement line (the line with `slug: statement`). Multi-sentence statements on that one line are fine.
+
+Violating these breaks the parser and grep-based retrieval.
+
+### Complete domain file example
+
+```markdown
+# Auth
+
+> OAuth-based auth and stateless JWT sessions. Two roles: admin/member.
+
+## Constraints
+
+C:oauth-only: OAuth only — no email/password.
+  > user: "I don't want to deal with password resets"
+
+C:jwt-stateless: Sessions are stateless JWT — no server-side session store.
+  > user: "I don't want to manage session infrastructure"
+
+## Requirements
+
+google-login: Users authenticate via Google OAuth.
+  > user: "we'll just do Google login for now"
+  @ C:oauth-only
+  ~ src/api/auth/google.py
+  ~ src/api/auth/callback.py
+
+session-expiry: Sessions expire after 30 days of inactivity.
+  > inferred: user said "standard session timeout, nothing crazy" — interpreted as 30 days
+  ! assumed 30 days — "nothing crazy" is unconfirmed
+  @ C:jwt-stateless
+  ~ src/middleware/session.py:44
+
+admin-revoke: Admins can revoke any user session immediately. [planned]
+  > user: "need a kill switch for bad actors"
+  ! assumed token blocklist approach — not stated by user
+  @ session-expiry
+  ? Q:admin-revoke-scope
+
+## Open Questions
+
+Q:admin-revoke-scope: Does admin-revoke apply to one session or all sessions?
+  > blocks: admin-revoke
+
+## Out of scope
+
+MFA, SSO/SAML.
+
+## Refs
+
+~ src/api/auth/
+~ src/middleware/session.py
+~ src/models/user.py
+```
+
+### Code backlinks
+
+Every function or class that implements a spec entry carries a `spec:` comment. One per logical block; multiple slugs comma-separated. Place at top of block.
+
+```python
+# spec: session-expiry
+def refresh_session(token: str) -> Session:
+
+# spec: billing-session-sync, C:usage-cap
+class PlanLimitMiddleware:
+```
+
+```typescript
+// spec: admin-revoke
+async function revokeSession(userId: string): Promise<void>;
+```
+
+### What the spec never contains
+
+Do not write: "Previously this was X", "Changed from X to Y", "Deprecated — use other-slug", "We chose JWT because...", or any description of how the system got to its current state. No entry without a `>` line. No implementation detail the user did not specify without a `!` line. The spec is always current state only.
+
+### Commit format
+
+```bash
+# Spec-only changes
+spec(auth): add session-expiry, C:jwt-stateless
+spec(auth): implement admin-revoke
+spec(auth): close Q:admin-revoke-scope
+spec(billing): update plan-limits statement
+spec: reconcile src/api/
+
+# Code + spec in same commit
+feat(auth): implement session expiry
+spec: implement session-expiry, add ! assumption for 30-day value
+```
+
+### Grep quick reference
+
+Replace `spec/` with `prov/` or `specs/` if that is your spec root.
+
+```bash
+# Orient
+grep -rh "^>" spec/*.md spec/*/*.md 2>/dev/null
+grep -r "^Q:" spec/
+grep -r "\[planned\]" spec/
+grep -r "^  !" spec/
+grep -r "^C:" spec/
+
+# What governs this path?
+grep -r "~src/path/to/file" spec/
+grep -r "~src/path/" spec/
+
+# Find by slug
+grep -r "^session-expiry:" spec/
+grep -A 25 "^session-expiry:" spec/
+
+# Dependents and implementers
+grep -r "^  @ session-expiry" spec/
+grep -rn "spec: session-expiry" src/
+
+# Keyword search
+grep -rEi "session|auth|timeout" spec/
+
+# Slug availability (before writing)
+grep -r "^my-new-slug:" spec/
+
+# Duplicate check
+grep -rhE "^[a-z][a-z0-9-]*:|^C:|^Q:" spec/ | cut -d: -f1,2 | sort | uniq -d
+```
+
+### prov CLI — quick reference
+
+```bash
+prov orient              # session start
+prov scope <path>        # what governs this file/dir
+prov context <slug>      # full entry + deps
+prov impact <slug>       # blast radius
+prov find <keywords>     # search entries
+prov domain <name>       # full domain
+prov check-slug <slug>   # slug availability
+prov validate            # before every commit
+prov diff [ref]          # semantic change manifest
+prov reconcile <path>    # drift detection (read-only)
+prov sync [path]         # interactive drift resolution
+prov rebuild             # regenerate optional .spec/ cache
+prov init                # scaffold CONTEXT.md
+```
+
+---
+
+## Error Handling
+
+| If this happens | Do this |
+|-----------------|--------|
+| `prov validate` reports "ghost-scope" or "no > line" | Add a `  > ` line with appropriate source prefix (user, inferred, code, regulatory, derived). Do not commit without it. |
+| `prov validate` reports "dead-ref" | Remove the `~` line or update the path to the real file. Do not leave a `~` pointing to a missing path. |
+| `prov validate` reports "phantom-slug" | Either add the missing spec entry for that slug or remove the `spec: slug` backlink from code. Do not leave a backlink with no entry. |
+| You accidentally used 4 spaces or tab for sub-lines | Change to exactly 2 spaces. Parser and grep rely on 2-space indent. |
+| You put `~` or `@` inline in the statement | Move them to separate sub-lines with 2-space indent. One ref per line. |
+| Slug already exists elsewhere | Choose a different slug or update the existing entry; do not create a duplicate. Use `prov check-slug` or grep before writing. |