prove-cli 0.3.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.3.0 → prove_cli-0.4.1}/.claude/skills/recall/scripts/recall.sh

@@ -6,10 +6,11 @@
 # forwards every flag verbatim — so `recall.sh "<query>" --mode hybrid --json`
 # is exactly `eidetic recall "<query>" --mode hybrid --json`.
 #
-# The store is the files backend at ~/.eidetic/memory by default — a home-dir
-# path OUTSIDE any git worktree, so Claude and the colleague backend (which runs
-# in throwaway worktrees) read the SAME memories. Set EIDETIC_DATA_DIR to opt out
-# of sharing; set EIDETIC_MONGO_URI / NEO4J_URI + --backend for a server store.
+# The store is the files backend. Default location resolves per-operation:
+# PUBLIC records inside a git repo → <repo-root>/.eidetic/memory (committed,
+# team-shared); PRIVATE records, or any record outside a git repo →
+# $HOME/.eidetic/memory (never committed). Recall reads both stores and merges.
+# An explicit EIDETIC_DATA_DIR wins and short-circuits to that single dir.
 
 set -euo pipefail
 
@@ -34,12 +35,10 @@ resolve_eidetic() {
         fi
         dir=$(dirname "$dir")
     done
-    cat >&2 <<'EOF'
-error: eidetic CLI not found.
-hint: install it with `uv tool install eidetic-cli` (or `pipx install eidetic-cli`),
-      or run from inside the eidetic-cli checkout with `uv` available.
-      The console script is `eidetic` (dist name: eidetic-cli).
-EOF
+    # In a vendored copy there is no eidetic-cli checkout to fall back to, so the
+    # only honest remedy is to install the CLI. One `error:` + one `hint:` line.
+    printf 'error: eidetic CLI not found.\n' >&2
+    printf 'hint: install it with: uv tool install eidetic-cli (or pipx install eidetic-cli); the console script is eidetic.\n' >&2
     return 1
 }
 
@@ -65,10 +64,17 @@ EOF
 }
 
 case "${1:-}" in
-    -h | --help | help | "")
+    -h | --help)
         usage
         exit 0
         ;;
+    "")
+        # A missing query is a usage error, not success. The bareword `help` is
+        # a legitimate search term, so it is intentionally NOT a usage alias.
+        printf 'error: no query given.\n' >&2
+        printf 'hint: recall.sh "<query>" [--mode ...] [--json]; run recall.sh --help for usage.\n' >&2
+        exit 1
+        ;;
 esac
 
 resolve_eidetic || exit 2
@@ -100,9 +106,12 @@ resolve_scope() {
             # inline `# comment` or trailing space can't bleed into the scope),
             # then strip surrounding quotes only — matching the canonical parser
             # in .claude/skills/cicd/scripts/_resolve-nick.sh.
+            # `|| true`: under `set -o pipefail`, `head -n1` closing the pipe
+            # early can SIGPIPE `sed`, making the substitution non-zero and
+            # aborting the script. An empty parse must yield "" here, not exit.
             suffix=$(sed -n \
                 's/^[[:space:]]*-\{0,1\}[[:space:]]*suffix:[[:space:]]*\([^[:space:]]*\).*/\1/p' \
-                "$dir/culture.yaml" | head -n1 | tr -d "\"'")
+                "$dir/culture.yaml" | head -n1 | tr -d "\"'" || true)
             break
         fi
         dir=$(dirname "$dir")
@@ -127,7 +136,20 @@ if ! has_flag --scope "$@"; then
     EIDETIC_SCOPE=$(resolve_scope)
     if [ -n "$EIDETIC_SCOPE" ]; then
         SCOPE_ARGS+=(--scope "$EIDETIC_SCOPE")
-        has_flag --visibility "$@" || SCOPE_ARGS+=(--visibility private)
+        # rollout-cli eidetic-memory recipe POLICY OVERRIDE (not eidetic's
+        # upstream private default): default to PUBLIC, so a plain recall queries
+        # the in-repo public pool (<repo>/.eidetic/memory) this repo writes to.
+        # Pass --visibility private to also surface this agent's private ($HOME)
+        # notes. The two-store read model reads both dirs regardless.
+        has_flag --visibility "$@" || SCOPE_ARGS+=(--visibility public)
+    elif ! has_flag --visibility "$@"; then
+        # No suffix AND no explicit --visibility: the query runs against
+        # eidetic's own default (scope=default, visibility=public), not this
+        # agent's private personal scope — so an empty result isn't silently
+        # misread. Warn on stderr (stdout stays clean for --json). Warn ONLY
+        # here: an explicit --scope (outer guard) or --visibility (this guard) is
+        # a deliberate choice, honored verbatim, so either flag silences this.
+        printf 'warning: no culture.yaml suffix resolved; querying the public default scope rather than a private personal scope. Pass --scope or --visibility to target deliberately.\n' >&2
     fi
 fi
 

{prove_cli-0.3.0 → prove_cli-0.4.1}/.claude/skills/remember/scripts/remember.sh

@@ -12,10 +12,11 @@
 # Upsert is idempotent by id (and dedups by content hash): re-remembering the
 # same record updates it in place, never duplicates.
 #
-# The store is the files backend at ~/.eidetic/memory by default — a home-dir
-# path OUTSIDE any git worktree, so a record Claude remembers is recallable by
-# the colleague backend (which runs in throwaway worktrees), and vice versa.
-# Set EIDETIC_DATA_DIR to opt out of sharing; use --backend mongo|neo4j (with
+# The store is the files backend. Default location resolves per-operation:
+# PUBLIC records inside a git repo → <repo-root>/.eidetic/memory (committed,
+# team-shared); PRIVATE records, or any record outside a git repo →
+# $HOME/.eidetic/memory (never committed). An explicit EIDETIC_DATA_DIR still
+# wins and short-circuits to that single dir. Use --backend mongo|neo4j (with
 # EIDETIC_MONGO_URI / NEO4J_URI) for a server-backed shared store.
 
 set -euo pipefail
@@ -40,12 +41,10 @@ resolve_eidetic() {
         fi
         dir=$(dirname "$dir")
     done
-    cat >&2 <<'EOF'
-error: eidetic CLI not found.
-hint: install it with `uv tool install eidetic-cli` (or `pipx install eidetic-cli`),
-      or run from inside the eidetic-cli checkout with `uv` available.
-      The console script is `eidetic` (dist name: eidetic-cli).
-EOF
+    # In a vendored copy there is no eidetic-cli checkout to fall back to, so the
+    # only honest remedy is to install the CLI. One `error:` + one `hint:` line.
+    printf 'error: eidetic CLI not found.\n' >&2
+    printf 'hint: install it with: uv tool install eidetic-cli (or pipx install eidetic-cli); the console script is eidetic.\n' >&2
     return 1
 }
 
@@ -60,7 +59,9 @@ Usage:
 
 A record needs `id`, `text`, and `type`; `hash` and `metadata` are recommended
 (hash is derived from text when omitted). Upsert is idempotent by id.
-Public data only. Every flag is forwarded verbatim to `eidetic remember`.
+Records default to this agent's PRIVATE personal scope (--scope from the
+culture.yaml suffix); pass --visibility public to contribute to the shared
+public pool. Every flag is forwarded verbatim to `eidetic remember`.
 See `eidetic explain remember`.
 EOF
 }
@@ -72,6 +73,16 @@ case "${1:-}" in
         ;;
 esac
 
+# No record argument AND stdin is an interactive terminal → `eidetic remember`
+# would block forever waiting for NDJSON. Show usage instead of hanging. A piped
+# or redirected stdin (`cat records.ndjson | remember.sh`) is not a TTY and
+# proceeds to the batch path normally.
+if [ "$#" -eq 0 ] && [ -t 0 ]; then
+    usage >&2
+    printf 'hint: pass a JSON record as an argument, or pipe NDJSON on stdin.\n' >&2
+    exit 1
+fi
+
 resolve_eidetic || exit 2
 
 # ── default to this agent's PERSONAL, PRIVATE scope (culture.yaml `suffix`) ──
@@ -100,9 +111,12 @@ resolve_scope() {
             # inline `# comment` or trailing space can't bleed into the scope),
             # then strip surrounding quotes only — matching the canonical parser
             # in .claude/skills/cicd/scripts/_resolve-nick.sh.
+            # `|| true`: under `set -o pipefail`, `head -n1` closing the pipe
+            # early can SIGPIPE `sed`, making the substitution non-zero and
+            # aborting the script. An empty parse must yield "" here, not exit.
             suffix=$(sed -n \
                 's/^[[:space:]]*-\{0,1\}[[:space:]]*suffix:[[:space:]]*\([^[:space:]]*\).*/\1/p' \
-                "$dir/culture.yaml" | head -n1 | tr -d "\"'")
+                "$dir/culture.yaml" | head -n1 | tr -d "\"'" || true)
             break
         fi
         dir=$(dirname "$dir")
@@ -127,7 +141,19 @@ if ! has_flag --scope "$@"; then
     EIDETIC_SCOPE=$(resolve_scope)
     if [ -n "$EIDETIC_SCOPE" ]; then
         SCOPE_ARGS+=(--scope "$EIDETIC_SCOPE")
-        has_flag --visibility "$@" || SCOPE_ARGS+=(--visibility private)
+        # rollout-cli eidetic-memory recipe POLICY OVERRIDE (not eidetic's
+        # upstream private default): default to PUBLIC so a plain remember lands
+        # in <repo>/.eidetic/memory — committed, team- and mesh-shared. Pass
+        # --visibility private to keep a record in $HOME (uncommitted).
+        has_flag --visibility "$@" || SCOPE_ARGS+=(--visibility public)
+    elif ! has_flag --visibility "$@"; then
+        # No suffix AND no explicit --visibility: the record falls back to
+        # eidetic's own default (scope=default, visibility=public). Don't let an
+        # expected-private record go public silently — warn on stderr (stdout
+        # stays clean for --json). Warn ONLY here: an explicit --scope (outer
+        # guard) or --visibility (this guard) means the caller chose deliberately
+        # and is honored verbatim, so either flag silences this.
+        printf 'warning: no culture.yaml suffix resolved; this record falls back to the public default scope. Pass --scope or --visibility to place it deliberately.\n' >&2
     fi
 fi