prove-cli 0.4.0__tar.gz → 0.4.1__tar.gz

prove_cli-0.4.1/.claude/skills/challenge/SKILL.md

@@ -0,0 +1,290 @@
+---
+name: challenge
+description: >
+  Run a risk-scaled blind-spot discovery pass over a converged, exported
+  frame BETWEEN /think and /spec-to-plan (the seventh origin skill, third
+  leg in flow order): pressure-test the spec through structured lenses,
+  route every finding back through the existing deterministic moves as
+  proposed-only content the human adjudicates, and on a clean pass record
+  the examined lenses/surfaces and residual uncertainty — never a claim
+  that there are no unknown unknowns. Use when the user says "challenge
+  this spec", "blind-spot pass", "pressure-test the frame", "what are we
+  missing", "unknown unknowns", or after /think exports and before
+  `devague plan new`. Authored and maintained in agentculture/devague
+  (origin = devague); guildmaster pulls this skill from here and broadcasts
+  it to the AgentCulture mesh — it is NOT vendored from guildmaster like
+  the inbound skills here.
+type: command
+---
+
+# challenge — hunt the blind spots before the plan inherits them
+
+The skill is named **`challenge`**; it is the **blind-spot discovery leg** of
+the devague method — the *seventh* origin skill, sitting *third* in flow
+order, between the spec leg and the plan leg:
+
+```text
+scope -> think -> challenge -> spec-to-plan -> assign-to-workforce -> deviate -> summarize-delivery
+```
+
+Before this leg existed, a frame could converge on precisely stated claims
+while the original framing was still incomplete: open questions only captured
+uncertainty someone had already noticed — **nothing actively hunted omitted
+dimensions, hidden dependencies, or assumptions shared by everyone in the
+frame, and no record existed of which surfaces were ever examined**
+(issue 73's problem statement). Strictly speaking, an unknown unknown cannot
+be listed directly — once articulated, it becomes a known unknown. The useful
+capability is therefore to **raise the odds of discovering blind spots and
+lower the cost of the surprises that remain**, not to promise their
+elimination.
+
+That is the surprise-cost rationale: an articulated blind spot becomes a
+known unknown the method can manage; an unexamined one surfaces later as a
+mid-run `/deviate` or a production surprise. Discovery *before* planning is
+cheaper than either — a proposed claim the human rejects costs minutes; the
+same gap found mid-fan-out stops a wave, and found in production it costs
+whatever the blast radius costs.
+
+This doc is written for two readers. The **operator** — the main agent — runs
+the pass: sweeps the lenses, drives the deterministic CLI move by move, and
+proposes findings. The **gate-owning human** adjudicates: every finding lands
+`proposed`, and confirming, rejecting, or resolving it is the human exercising
+the existing **spec gate** (gate 1) — challenge adds no fourth gate, mirroring
+how `/deviate` amends gate 2 rather than adding one.
+
+## When it runs
+
+The timing is a recorded decision — quote it, don't re-derive it:
+
+> the challenge pass runs after /think exports: challenge the converged,
+> exported frame before `devague plan new`; findings reopen the frame,
+> reconverge, and re-export the same dated spec file — /think stays
+> self-contained (resolves q1)
+
+— decision c17 in `docs/specs/2026-07-15-challenge-skill.md`.
+
+Concretely: `/think` finishes its own arc (converge, export) untouched. Then
+`/challenge` pressure-tests the exported spec **before** `devague plan new`
+seeds a plan from it. Findings land as proposed claims, honesty conditions,
+questions, or parks — which reopens the frame — the human adjudicates, the
+frame **reconverges**, and `devague export` **re-exports the same dated
+file** (`docs/specs/<created-date>-<slug>.md`; exports are prefixed with the
+frame's creation date, so a re-export overwrites in place rather than
+spawning a duplicate). That reconverge-and-re-export loop repeats until the
+pass's findings are all adjudicated and the spec artifact carries them.
+
+## Proportionality — scale the pass to the risk
+
+The pass is **mandatory but proportional**: lightweight for ordinary work,
+rigorous for high-risk work (integration option 1 from issue 73, per the
+issue author — a distinct operator skill, no new CLI engine until the
+workflow proves it needs one). Which work is high-risk is likewise a recorded
+decision:
+
+> the named escalation signals that deepen the pass from lightweight to
+> rigorous: migrations, security-sensitive work, distributed state, hardware,
+> destructive operations, other hard-to-reverse changes, concurrency hazards,
+> and any surface that can lose user data (resolves q3)
+
+— decision c19 in `docs/specs/2026-07-15-challenge-skill.md`.
+
+If **any** escalation signal applies, run the rigorous form: every lens,
+deliberate counter-evidence hunting, and cheap probes where they would settle
+a real question. If none applies, a lightweight sweep — one pass over the
+lenses against the exported spec, minutes not hours — satisfies the method.
+Lightweight never means skipped: even the lightest pass leaves durable
+records (see the hard rules).
+
+## The lenses
+
+Sweep the exported spec, the live frame, and the surfaces the idea touches
+through these structured lenses (from issue 73):
+
+- **adjacent systems and hidden dependencies** — what else reads, writes, or
+  assumes the thing being changed;
+- **unstated assumptions and missing counter-evidence** — what everyone in
+  the frame believes without a claim saying so, and what was never checked
+  because nobody argued the other side;
+- **overlooked actors, lifecycle stages, data flows, and failure modes** —
+  who and what the frame forgot: other users, upgrade/downgrade paths,
+  half-completed operations;
+- **security, migration, concurrency, operations, and reversibility** — the
+  classic hard surfaces, each also an escalation signal when present;
+- **missing observability, containment, rollback, and recovery paths** —
+  when the surprise happens anyway, how it is seen, bounded, and undone;
+- **cheap probes or experiments** — small, scratch-space checks that could
+  expose a surprise now instead of mid-run (probes never mutate the repo or
+  `.devague/` state).
+
+## The method
+
+1. **Confirm the entry condition.** A converged frame that `/think` has
+   already exported, and no plan seeded from it yet (`devague status` shows
+   where the frame stands; the exported spec-md is the artifact under
+   challenge).
+2. **Set the depth.** Check the idea against the c19 escalation signals
+   above. Any hit → rigorous; none → lightweight. Say which you chose and
+   why — the depth decision is part of the pass's record.
+3. **Sweep the lenses read-only.** Read the exported spec claim by claim,
+   the frame's parked vagueness and resolved questions, and the actual
+   surfaces the idea touches. Nothing mutates during the sweep; the only
+   mutations are the deterministic moves that record findings.
+4. **Route every finding through an existing move.** Use the routing table
+   below. Everything the agent proposes carries `--origin llm` and lands
+   `proposed` — the pass cannot silently convert speculation into confirmed
+   requirements.
+5. **Let the human adjudicate.** `devague review` lists every proposal with
+   ids; `devague confirm` / `devague reject` / `devague question --resolve`
+   are user-only decisions. This is the existing spec gate doing its job.
+6. **Reconverge and re-export.** `devague converge`, then `devague export` —
+   the same dated spec file now carries the adjudicated findings and the
+   pass's provenance (the exported spec renders scope entries in its
+   Scope exploration section).
+7. **On a clean pass, record the pass itself.** A sweep that finds nothing
+   still records which lenses and surfaces were examined (`devague scope`
+   entries, one per lens/surface, e.g. `challenge pass / concurrency lens:
+   devague/store.py`) and what residual uncertainty remains (`park`). A bare
+   "no issues found" is not an outcome this skill produces.
+
+## Where findings land
+
+Challenge keeps **no parallel prose-only artifact** — the frame is the
+record, and every output category from issue 73 has an existing deterministic
+move to land in:
+
+| Output category (issue 73) | What it is | Landing move |
+|----------------------------|------------|--------------|
+| known facts | something the pass established, with provenance | `capture --kind requirement` / `--kind decision` / `--kind boundary` (`--origin llm` → lands `proposed`) |
+| assumptions | beliefs the frame leaned on unstated | `capture --kind assumption --origin llm`, then pressure-test with `interrogate --honesty` / `--hard-question` / `--contradicts` |
+| known unknowns / open questions | articulated uncertainty | `question "<text>"` when it needs a user decision; `park --kind unknown_nonblocking\|unknown_blocking` when not decidable now |
+| unexamined surfaces | what this pass did not (or could not) look at | `devague scope "<surface>" --finding "<what was and wasn't examined, and why>"` |
+| residual surprise risk | uncertainty that survives the pass | `park` on the frame while speccing; `devague plan risk --kind <kind>` once the plan exists |
+| resilience measures | containment, rollback, recovery the surprise cost demands | spec-side `capture --kind requirement` / `--kind boundary`; plan-side `devague plan risk` (see below) |
+
+Every finding names the **lens and surface** it came from (the
+`challenge pass / <lens>: <surface>` convention in scope entries; provenance
+citations inside claim text). That provenance bar is how the method hunts
+blind spots **without encouraging speculative issue generation** — a finding
+you cannot trace to something you actually read is speculation, not a
+finding.
+
+## Resilience placement — spec-side or plan-side
+
+Where a resilience measure lands is a recorded decision:
+
+> resilience measures land in both spec and plan by nature: spec-side as
+> requirement/boundary claims when they change what to build, plan-side as
+> plan risks or tasks when they change how to build it — the skill coaches
+> which is which (resolves q2)
+
+— decision c18 in `docs/specs/2026-07-15-challenge-skill.md`.
+
+The coaching: ask *"does this change **what** ships, or **how** it gets
+built?"* A rollback path the user needs, a fail-closed version check, a
+containment boundary — those change the product: `capture` them spec-side as
+`requirement` / `boundary` claims so the re-exported spec carries them.
+A staging sequence, a merge-order constraint, an uncertainty the workforce
+must build around — those change the build: land them plan-side via
+`devague plan risk --kind <kind>` (blocking or nonblocking, honestly chosen)
+once `/spec-to-plan` seeds the plan, where the plan's convergence gate keeps
+blocking risks visible until resolved.
+
+## Hard rules (do not violate)
+
+- **Never conclude there are no unknown unknowns.** Not after a rigorous
+  pass, not after a clean one. The only honest clean-pass output is a record
+  of which lenses and surfaces were examined — `devague scope` entries — plus
+  the residual uncertainty that remains — `park` — so the pass leaves durable
+  provenance instead of a comforting absolute (issue 73 success criteria;
+  the anti-fabrication contract in `docs/llm-guidance.md`).
+- **LLM-origin findings stay proposed until the user confirms.** Every
+  finding the agent proposes carries `--origin llm` and lands `proposed`;
+  only the user's `confirm` makes it real. The pass must not be able to
+  silently convert speculation into confirmed requirements.
+- **Findings route through existing deterministic moves only.** `capture`,
+  `interrogate`, `question`, `park`, `devague scope`, `devague plan risk` —
+  nothing else. No parallel prose artifact, no new CLI verb, engine, or
+  state model (issue 20; issue 73's stated preference). If it didn't land in
+  a move, it didn't land.
+- **Provenance on every finding.** Name the lens and the surface it came
+  from. If you didn't read it, don't claim it — same bar as `/scope`.
+- **Proportional, never skipped.** Lightweight is the floor, not an
+  exemption; any c19 escalation signal makes the rigorous form mandatory.
+  Skipping the pass entirely is not a depth setting.
+- **Not a fourth standing gate.** The three human gates stay: exported spec,
+  implementation split plan, final PR. Challenge output is adjudicated
+  inside the existing spec gate — mirroring how `/deviate` amends gate 2
+  rather than adding one.
+- **The sweep is read-only until it routes.** Reading spec, frame, and
+  surfaces never edits files or state; probes run in scratch space. The only
+  mutations are the recording moves themselves.
+
+## Worked example
+
+Challenging the exported spec for a store-schema migration (illustrative
+slug `store-schema-v3`) — "migrations" and "any surface that can lose user
+data" are both c19 escalation signals, so the pass runs rigorous:
+
+```bash
+# Entry condition: /think exported docs/specs/2026-07-15-store-schema-v3.md
+# and no plan exists yet. Depth: rigorous (migration + data-loss signals).
+
+# adjacent-systems lens: an older installed devague reads the same store
+devague capture --origin llm --kind assumption "older installed devague binaries refuse a v3 store via the fail-closed schema_version check in devague/store.py"
+devague interrogate c9 --origin llm --honesty "a v2-reading binary pointed at a v3 store exits with the version hint, not a traceback"
+devague scope "challenge pass / adjacent-systems lens: devague/store.py schema_version gate" --finding "older binaries fail closed on v3; seeded the compat assumption" --seeds c9
+
+# failure-mode lens: the migration can die halfway
+devague capture --origin llm --kind requirement "migration writes to a temp file and renames — a killed run never leaves a half-written store"
+
+# overlooked-actors lens: needs a user decision, not a guess
+devague question "do mesh agents share one store, or does each checkout own its own?"
+
+# reversibility lens: genuinely unknown, not decidable now
+devague park "whether a v3->v2 downgrade path is ever needed" --kind unknown_nonblocking
+
+# concurrency lens found nothing — record the clean pass, not a conclusion
+devague scope "challenge pass / concurrency lens: devague/store.py + delivery_store.py" --finding "single-writer CLI, no locking today; clean pass — residual risk only if two agents ever share a checkout"
+
+# --- HUMAN adjudicates: the existing spec gate at work ---
+devague review
+devague confirm c9 h4 c10
+devague question --resolve q1 --decision "each checkout owns its own store"
+
+# Reconverge and re-export — the SAME dated file, now carrying the pass
+devague converge
+devague export
+
+# Residual risk that changes HOW to build lands plan-side once
+# /spec-to-plan seeds the plan:
+devague plan new --frame store-schema-v3
+devague plan risk "two agents sharing a checkout could interleave store writes mid-migration" --kind unknown_nonblocking
+```
+
+Every finding above is traceable to a lens and a surface; the clean lens is
+recorded as examined rather than silently dropped; and nothing the agent
+proposed became confirmed without the human's `confirm`.
+
+## After the pass — hand off to /spec-to-plan
+
+Once the frame reconverges and the same dated spec file is re-exported, the
+pass is done — the examined surfaces, residual uncertainty, and adjudicated
+findings all live in frame state and render into the spec artifact. Continue
+with `/spec-to-plan` as usual: the plan seeds from the challenged frame, and
+any residual surprise risk you routed plan-side lands via
+`devague plan risk` as first-class plan state. If a surprise still gets
+through mid-fan-out, that is `/deviate`'s job — and every approved `dN`
+deviation record is evidence for what the *next* challenge pass's lenses
+should look harder at.
+
+## Provenance
+
+This is a **first-party** skill — its origin is `agentculture/devague`, the
+*seventh* in the outbound family after `/scope`, `/think`, `/spec-to-plan`,
+`/assign-to-workforce`, `/deviate`, and `/summarize-delivery`, sitting third
+in flow order as the blind-spot discovery leg between `/think` and
+`/spec-to-plan`. guildmaster pulls it from here and broadcasts it to the
+AgentCulture mesh; because devague is upstream, it is **never re-vendored
+back** from guildmaster's re-broadcast copy. The `cite, don't import` policy
+still holds: downstream repos copy it, they don't symlink or depend on it.
+See `docs/skill-sources.md`.

prove_cli-0.4.1/.claude/skills/deviate/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: deviate
+description: >
+  Stop an in-flight assign-to-workforce run the moment execution must diverge
+  from the confirmed plan, get explicit human approval for the divergence, and
+  record it as a first-class, append-only deviation record via `devague
+  deviate` before resuming — never fold a deviation silently into drift after
+  the fact. Use when the user says "deviate from the plan", "we need to change
+  the plan mid-run", "record a deviation", "this isn't matching the plan
+  anymore", or when a task agent discovers the confirmed plan no longer
+  matches reality partway through a workforce run. Authored and maintained in
+  agentculture/devague (origin = devague); guildmaster pulls this skill from
+  here and broadcasts it to the AgentCulture mesh — it is NOT vendored from
+  guildmaster like the inbound skills here.
+type: command
+---
+
+# deviate — record an approved mid-run departure from the confirmed plan
+
+The skill is named **`deviate`**; it is the **execution-time leg** of the
+devague method — the *sixth* leg, sitting between the two execution skills:
+
+```text
+scope -> think -> spec-to-plan -> assign-to-workforce -> deviate -> summarize-delivery
+```
+
+Where `/assign-to-workforce` fans out a converged plan's waves and
+`/summarize-delivery` closes the loop afterward, `/deviate` runs **during**
+the fan-out, at the exact moment reality stops matching the plan the human
+approved at gate 2 (the implementation split plan). It is not a new standing
+gate — it is the human owner of gate 2 **amending** the approved split
+mid-flight, scoped to the one deviation in front of them.
+
+The plan the user confirmed is a contract. Task agents hit constraints,
+discover a dependency was wrong, or find the acceptance criteria no longer
+make sense once code is in front of them. Until this skill existed, that
+reality either silently reshaped what got built (undocumented drift) or the
+run stalled with no recorded path forward. `/deviate` is that path: the
+departure is named, approved, and recorded **before** anyone keeps building
+against it.
+
+## The method
+
+1. **STOP the run.** The moment a task agent (or the main agent) discovers
+   the confirmed plan no longer matches what needs to happen, halt — do not
+   keep implementing against the stale contract and do not let the fan-out
+   continue past this task.
+2. **Present what, why, and what it affects.** Lay out, for the human:
+   - **what** is diverging — the specific change from the confirmed task(s);
+   - **why** — the constraint or discovery that forced it;
+   - **what it affects** — the plan item ref(s) involved (`--task`), any
+     other task ids or coverage targets it touches (`--affects`), and which
+     acceptance criteria are no longer accurate.
+3. **Get explicit human approval.** This is the one non-negotiable step. A
+   deviation is not real until a human says yes to *this specific* departure
+   — not a standing blanket permission, not an inference from silence.
+4. **Record it via `devague deviate`.** Once approved, record the deviation
+   as a first-class ledger entry (never edit the plan itself — the plan
+   stays the untouched historical contract; see `devague/delivery.py`). An
+   `--origin llm` record lands `proposed` and still needs the user's
+   `--confirm` — recording is not the same as approval landing as final.
+5. **Adjust the affected task briefs.** Update the working instructions the
+   task agent(s) are building against so they reflect the approved
+   departure, not the stale plan text.
+6. **Resume.** Only after the record exists (and, for an `llm`-origin record,
+   only after it is confirmed) does the fan-out continue.
+
+Deviations are never silently folded into drift after the fact — by the time
+`/summarize-delivery` runs, every departure from the plan already has a
+`dN` record with a reason, an approval, and an optional classification. The
+delivery summary quotes these records; it does not reconstruct drift from
+memory.
+
+## The shipped CLI surface
+
+This skill invokes the CLI directly and stays self-contained (if `devague`
+isn't on your PATH: `uv tool install devague`). Deviation state persists
+under `.devague/deliveries/<plan-slug>.json` — a peer of the plan store, keyed
+by the plan slug, and never touches the plan JSON itself.
+
+| Move | What it does |
+|------|---------------|
+| `devague deviate "<what>" --task <tN> --reason "<text>"` | Record a deviation against plan item `<tN>`. User-origin (the default) auto-approves. |
+| `devague deviate "<what>" --task <tN> --reason "<text>" --affects <ref> [<ref> ...]` | Same, also naming every other plan item ref or coverage target the deviation touches (repeatable). |
+| `devague deviate "<what>" --task <tN> --reason "<text>" --classification acceptable\|risky\|needs-follow-up` | Same, tagging the deviation with the classification the drift-entry contract consumes downstream. |
+| `devague deviate "<what>" --task <tN> --reason "<text>" --origin llm` | An LLM-proposed record; lands `proposed`, not `approved`. |
+| `devague deviate --confirm <dN>` | User-only: approve a `proposed` deviation. |
+| `devague deviate --reject <dN>` | User-only: reject a `proposed` (or any) deviation. |
+| `devague deviate --list [--json]` | Read every recorded deviation back (also the default action with no positional/flag). |
+| `devague deviate ... --plan <slug>` | Target a plan other than the current one. |
+
+`--reason` is required on every record — omitting it is refused with a hint.
+`--task` naming the plan item ref is likewise required.
+
+## Hard rules (do not violate)
+
+- **Never record a deviation the human did not approve.** `devague deviate`
+  without `--origin llm` auto-approves the instant it is run — so a
+  user-origin record IS the approval. Only run it after the human has said
+  yes to this specific departure, never preemptively "to be safe."
+- **Never continue past a refused approval.** If the human does not approve,
+  the run stays stopped on that task. Do not record the deviation anyway, do
+  not quietly implement the diverging approach, and do not advance the wave.
+- **LLM-origin records stay proposed until the user confirms.** `--origin
+  llm` lands `proposed`; only `devague deviate --confirm <dN>` (user-only)
+  makes it `approved`. Same anti-fabrication contract as every other origin
+  in the method — an agent's own proposal never self-confirms.
+- **Deviations are never silently folded into drift after the fact.** Every
+  departure from the confirmed plan gets a `dN` record at the moment it
+  happens — not reconstructed from memory when `/summarize-delivery` runs
+  later.
+- **The CLI stays non-orchestrating (issue #20).** `devague deviate` records
+  a decision the human already made; it does not spawn agents, gate merges,
+  mark tasks done, or make the approval decision itself. Recording is
+  deterministic — no LLM calls inside the CLI.
+- **This is not a fourth standing gate.** `/assign-to-workforce`'s three
+  human gates are the exported spec, the implementation split plan, and the
+  final PR. `/deviate` does not add a fourth — it is the human owner of gate
+  2 amending the approved split for one scoped, in-flight decision.
+
+## Worked example
+
+Mid-fan-out on task `t4`, the task agent discovers the acceptance criteria
+assumed a helper that task `t2` never actually shipped:
+
+```bash
+# 1. STOP — the main agent halts t4's worktree before more code lands
+#    against a criterion that can't be met as written.
+
+# 2. Present what/why/what-it-affects to the human:
+#    what:    t4's acceptance criterion 2 assumes a `--json` flag on a
+#             helper that t2 shipped without one
+#    why:     t2's scope was cut to land its wave on time
+#    affects: t4 (this task), and coverage target c9 (the criterion in
+#             question)
+
+# --- HUMAN: approves dropping the --json assumption from t4's criterion ---
+
+# 3. Record the approved deviation
+devague deviate "drop the --json assumption from t4's acceptance criterion" \
+  --task t4 --reason "t2 shipped its helper without --json to land its wave on time" \
+  --affects t2 --affects c9 --classification acceptable
+
+# 4. Adjust t4's working brief to match what was approved, then resume the
+#    task agent against the corrected instruction.
+
+# Read the ledger back at any point:
+devague deviate --list
+devague deviate --list --json
+```
+
+If the agent had proposed the record itself (`--origin llm`), the same
+record would land `proposed` and need an explicit
+`devague deviate --confirm d1` from the user before `/summarize-delivery`
+could cite it as approved.
+
+## After recording — resume, then hand off to /summarize-delivery
+
+Once the affected task briefs are adjusted and the fan-out resumes, nothing
+further is needed from this skill — the record already lives in the delivery
+store. When the run reaches `/summarize-delivery`, that skill's Drift From
+Plan and Mid-work Decisions sections quote these records by their `dN` id
+instead of reconstructing drift from memory, so the connective tissue between
+the confirmed plan and the delivery summary is the ledger this skill wrote,
+not anyone's recollection of the run.
+
+## Provenance
+
+This is a **first-party** skill — its origin is `agentculture/devague`, the
+*sixth* in the outbound family after `/scope`, `/think`, `/spec-to-plan`,
+`/assign-to-workforce`, and `/summarize-delivery`, covering the execution-time
+leg that runs inside an `/assign-to-workforce` fan-out. guildmaster pulls it
+from here and broadcasts it to the AgentCulture mesh; because devague is
+upstream, it is **never re-vendored back** from guildmaster's re-broadcast
+copy. The `cite, don't import` policy still holds: downstream repos copy it,
+they don't symlink or depend on it. See `docs/skill-sources.md`.

prove_cli-0.4.1/.claude/skills/scope/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: scope
+description: >
+  Explore the scope of a vague idea BEFORE framing it into a spec (the
+  idea→scope leg; the optional opening move ahead of /think). Survey the
+  surfaces the idea touches — code, docs, skills, CI, sibling repos — and seed
+  the coming Announcement Frame with boundary, non-goal, and assumption claims
+  that cite what was actually explored (provenance, not generic disclaimers).
+  Use when the user says "explore scope", "scope this idea", "what does this
+  touch", "map the scope", "scope exploration", or when an idea touches an
+  existing codebase and speccing it cold would mean guessing its boundaries.
+  Hand off to the sibling /think skill to build the frame. Authored and
+  maintained in agentculture/devague (origin = devague); guildmaster pulls this
+  skill from here and broadcasts it to the AgentCulture mesh — it is NOT
+  vendored from guildmaster like the inbound skills here.
+type: command
+---
+
+# scope — explore what an idea touches before you frame it
+
+The skill is named **`scope`**; it is the **opening leg** of the devague method
+— run it *before* the sibling **`/think`** skill frames an idea into a spec.
+Where `/think` converges on *what* to build, `/scope` grounds *where the idea
+lives*: which surfaces it touches, which it must not, and what is genuinely
+unknown — so the frame starts from explored territory instead of guesses.
+
+This comes from the sharper end-to-end method spec (devague#53): scope grounded
+up front means convergence measures real coverage instead of vibes. The
+exploration itself is **agent-side work** — the devague CLI stays deterministic
+and never explores anything (#20).
+
+## When to use — and when to skip
+
+Use `/scope` when the idea touches an existing codebase or ecosystem: a feature
+in a real repo, a process change across skills, anything where boundaries are
+discoverable rather than invented.
+
+**Skip it freely for small ideas.** Scope exploration is *not* a mandatory
+first stage — the move-driven adaptive arc stays intact, and an idea that fits
+in one announcement can go straight to `/think`. (This is a recorded non-goal
+of the method: no wizard.)
+
+## The method
+
+1. **Enumerate candidate surfaces.** List what the idea *might* touch: source
+   packages, CLI verbs, renderers, schemas, tests, docs, skills, CI workflows,
+   sibling repos. `git ls-files` and the repo's `CLAUDE.md` are the usual map.
+2. **Explore each surface read-only.** Read enough of each candidate to decide:
+   touched, not touched, or unknown. Exploration never mutates anything —
+   no edits, no state changes, no CLI moves yet.
+3. **Classify every finding.** Each explored surface yields one of:
+   - **in scope** — the idea changes it → becomes a `requirement` or
+     `assumption` claim in the frame;
+   - **out of scope** — the idea must not change it → becomes a `boundary` or
+     `non_goal` claim;
+   - **genuinely unknown** — can't tell without a decision → becomes a `park`
+     (open vagueness) or a `question` (pending user decision).
+4. **Record findings on the frame, with provenance.** Start the frame with
+   `devague new "<announcement>" --title "<short>"` (this is also `/think`'s
+   first move) — scope entries live on the frame, so it must exist first.
+   Record each explored surface as a first-class finding:
+   `` `devague scope "<surface>" --finding "<text>" [--seeds <claim-id> ...]` ``
+   — text that **cites the surface explored** ("the CLI stays deterministic
+   per issue 20; scope exploration is agent-side" beats "we won't overreach").
+   Capture the claim it seeded first (`capture --kind ...`), then pass its id
+   to `--seeds` — an unknown seed id is refused with a hint. Provenance, not
+   generic disclaimers: a reviewer should be able to trace every boundary claim
+   back to something you read.
+
+## How findings land (the shipped surface)
+
+This skill invokes the CLI directly and stays self-contained (if `devague`
+isn't on your PATH: `uv tool install devague`).
+
+The **primary** landing surface is the deterministic `devague scope` move,
+shipped in task t3 of the committed sharper-end-to-end-method plan
+(`docs/plans/2026-07-01-devague-ships-a-sharper-end-to-end-method-a-guided.md`,
+devague#53). It records an explored surface + finding as first-class frame
+state (`Frame.scope_entries` / `ScopeEntry`: `id` (`sN`), `surface`, `finding`,
+`seeds`) — deterministic recording only, no LLM calls, no subprocess, no
+filesystem exploration inside the CLI. Like `capture`, it needs a frame to
+already exist, so run `devague new` first:
+
+| Move | What it does |
+|------|--------------|
+| `devague scope "<surface>" --finding "<text>"` | Record a finding on the current frame. |
+| `devague scope "<surface>" --finding "<text>" --seeds <claim-id> [<claim-id> ...]` | Record a finding, linking it to the claim id(s) it went on to seed. An unknown seed id is refused with a hint (`run 'devague show' to see valid claim ids`). |
+| `devague scope --list [--json]` | Read every recorded entry back. |
+
+Boundary / non-goal / in-scope claims still land the same way they always
+did, through the normal frame moves — `devague scope` documents *what surface
+you explored and what you learned*, `capture` records *the claim that
+followed*:
+
+| Finding | Move |
+|---------|------|
+| in scope (the idea changes this) | `capture --kind requirement` / `--kind assumption` (with `--origin llm` if you proposed it) |
+| out of scope (must not change) | `capture --kind boundary` / `--kind non_goal` |
+| genuinely unknown, needs a user decision | `question "<text>"` (later `question --resolve <qid> --decision "<text>"`) |
+| genuinely unknown, not decidable now | `park "<text>" --kind unknown_blocking\|unknown_nonblocking` |
+
+## Hard rules (do not violate)
+
+- **Exploration is read-only.** Surveying scope never edits files, never
+  mutates frame state, never runs a mutating CLI move.
+- **Provenance in every seeded claim.** A scope-derived claim cites what was
+  explored. If you didn't read it, don't claim it.
+- **LLM proposals stay proposed.** Findings you capture with `--origin llm`
+  land `proposed`; the user confirms. Same anti-fabrication contract as
+  `/think`.
+- **Don't become a wizard.** Scope exploration is optional-by-size and
+  adaptive. Never block a small idea on a survey it doesn't need.
+
+## Worked example
+
+Scoping "devague exports should carry per-item instructions" against the
+devague repo itself:
+
+```bash
+# 1–2. enumerate + explore (read-only)
+git ls-files devague/ | head -30       # the CLI package map
+# read: devague/frame.py (claim model), devague/render/spec_md.py (renderer),
+#       docs/spec-contract.md (schema contract), .claude/skills/think/SKILL.md
+
+# 3. start the frame (also /think's first move — scope entries live on it)
+devague new "devague exports carry per-item instructions" --title "per-item instructions"
+
+# 4. capture each finding as a claim, then record the scope entry that seeded it
+devague capture --origin llm --kind requirement "claims gain an optional instruction field — devague/frame.py claim model + docs/spec-contract.md schema both need a bump"
+devague scope "devague/frame.py" --finding "claim model needs an optional instruction field per docs/spec-contract.md's schema contract" --seeds c2
+
+devague capture --origin llm --kind boundary "render/spec_md.py renders instructions verbatim; absent instructions render nothing — the renderer never fabricates filler"
+devague scope "render/spec_md.py" --finding "renderer must render instructions verbatim; absent instructions render nothing — never fabricate filler" --seeds c3
+
+devague capture --origin llm --kind non_goal "no LLM calls land inside the CLI (issue 20) — instruction text is authored by the operator/user, never generated in-CLI"
+devague scope "issue 20 (no LLM calls in-CLI)" --finding "instruction text is authored by the operator/user, never generated in-CLI" --seeds c4
+
+devague question "do instructions attach to frame claims, plan tasks, or both?"
+devague scope --list   # read every recorded finding back, with its seeded claim ids
+```
+
+Every claim above names the file or issue that was actually read — that is the
+provenance bar. Note the order: `--seeds` needs the claim id to already exist,
+so `capture` runs first and the matching `scope` call cites it back.
+
+## After scoping — hand off to /think
+
+The recorded scope entries and the claims captured alongside them both live on
+the same frame — there is nothing separate to export. `devague scope --list`
+is the durable, citable record of what was explored; a converged frame's
+exported spec-md also renders a `## Scope exploration` section from the same
+entries (surface, finding, and seeded claim ids), so the provenance survives
+into the buildable artifact (#53 t6). When the survey is done, continue with
+`/think`'s remaining moves (`interrogate`, `confirm`/`reject`, `converge`,
+`export`) to take the frame the rest of the way. The user confirms
+LLM-proposed claims there, as always.
+
+## Provenance
+
+This is a **first-party** skill — its origin is `agentculture/devague`, the
+*fourth* authored in the outbound family (after `/think`, `/spec-to-plan`, and
+`/assign-to-workforce`) but the **opening leg** of the flow, covering the
+pre-frame exploration that runs before `/think`. guildmaster pulls it from here
+and broadcasts it to the AgentCulture mesh; because devague is upstream, it is
+**never re-vendored back** from guildmaster's re-broadcast copy. The
+`cite, don't import` policy still holds: downstream repos copy it, they don't
+symlink or depend on it. See `docs/skill-sources.md`.