convertible-cli 0.2.2__tar.gz → 0.4.0__tar.gz

convertible_cli-0.4.0/.devague/current

@@ -0,0 +1 @@
+convertible-gains-an-extensibility-layer-like-clau

convertible_cli-0.4.0/.devague/current_plan

@@ -0,0 +1 @@
+convertible-gains-an-extensibility-layer-like-clau

convertible_cli-0.4.0/.devague/frames/convertible-gains-an-extensibility-layer-like-clau.json

@@ -0,0 +1,445 @@
+{
+  "slug": "convertible-gains-an-extensibility-layer-like-clau",
+  "title": "Convertible gains an extensibility layer like Claude Code and Codex: reusable custom commands (named, parameterized task templates discovered from the repo/user config) plus hooks (operator-configured shell commands that fire at tool-loop lifecycle events \u2014 task start, pre-tool-call, post-tool-call, finish \u2014 and can gate, deny, or augment a tool call), both layered on the shared chassis so they fire identically for every engine.",
+  "schema_version": 1,
+  "status": "exported",
+  "created": "2026-05-27T16:12:18Z",
+  "updated": "2026-05-27T16:25:36Z",
+  "claims": [
+    {
+      "id": "c1",
+      "kind": "announcement",
+      "text": "Convertible gains an extensibility layer like Claude Code and Codex: reusable custom commands (named, parameterized task templates discovered from the repo/user config) plus hooks (operator-configured shell commands that fire at tool-loop lifecycle events \u2014 task start, pre-tool-call, post-tool-call, finish \u2014 and can gate, deny, or augment a tool call), both layered on the shared chassis so they fire identically for every engine.",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h8",
+          "text": "One drive run on each engine exercises both halves: a saved command template expands into a Task AND a configured hook fires during that run's loop, with both visible in the result artifact \u2014 demonstrating commands+hooks on the shared chassis.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c2",
+      "kind": "audience",
+      "text": "Convertible operators who drive repos with models and want a safety/policy gate plus reusable task recipes, and engine-wheel developers who need lifecycle behavior to live in the chassis (not per-engine).",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h12",
+          "text": "A concrete operator can name a recurring task they'd save as a command and a tool call they'd want gated by a hook; the engine-wheel-developer benefit holds because lifecycle behavior lives in the chassis, not in each wheel.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c3",
+      "kind": "before_state",
+      "text": "Today 'convertible drive' takes one raw instruction string and runs the tool-loop with no operator-authored gate: run_command/write_file execute whatever the model emits (D2 trusts the operator env), and every task must be retyped from scratch \u2014 there is no way to deny a tool call by policy or save a reusable recipe.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h13",
+          "text": "On main today, 'convertible drive' exposes no command-template flag and no hook config, and run_command/write_file execute unconditionally \u2014 verifiable by inspecting drive.py / loop.py / tools.py.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c4",
+      "kind": "after_state",
+      "text": "An operator drops command templates and a hooks config into convertible config; 'convertible drive --command <name> [args]' expands a saved template into a Task, and during the loop hooks fire at task-start / pre-tool / post-tool / finish \u2014 a pre-tool hook can deny or rewrite a tool call and feed a reason back to the model, a post-tool hook can run a formatter/linter, and every hook firing is recorded in the result artifact.",
+      "origin": "llm",
+      "status": "rejected",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c5",
+      "kind": "why_it_matters",
+      "text": "Running models against repos needs an operator-owned gate (the parked sandbox is still deferred; hooks are deterministic policy, not isolation) and recurring repo chores need reusable recipes \u2014 both are exactly the extensibility Claude Code and Codex ship, and putting them in the chassis means they bind every engine under the all-engines rule.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h14",
+          "text": "The operator gate and reusable recipes cannot be had with today's convertible without editing source; Claude Code and Codex both ship exactly these two mechanisms, confirming the need is real.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c6",
+      "kind": "boundary",
+      "text": "NOT a sandbox or resource-isolation layer (D2's trust model is unchanged; hooks are operator-authored gates, not confinement); NOT an interactive REPL/slash-command UI (convertible stays one-shot \u2014 no UserPromptSubmit/Notification/PreCompact session events); NOT a plugin/marketplace system; commands are Task templates only, not arbitrary code.",
+      "origin": "llm",
+      "status": "rejected",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c7",
+      "kind": "success_signal",
+      "text": "On both mock and vllm-openai engines: a saved command expands into the same Task shape, a pre-tool deny-hook blocks a run_command and the artifact records the denial + the model's continuation, and a post-tool hook's effect is observable \u2014 proving the lifecycle is chassis-level and engine-agnostic.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h15",
+          "text": "A single test/demo runs the same command + hook config on mock and vllm-openai and asserts identical result shape, a working pre-tool deny, and an observable post-tool effect.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c8",
+      "kind": "requirement",
+      "text": "R1 Commands: named task templates discovered from convertible config (repo-level and user-level), each a file with optional metadata (description, engine, constraints, arg-hint) and a body that becomes the instruction with positional/$ARGUMENTS substitution; 'convertible drive --command <name> [args...]' expands it into the same Task the contract already defines.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h1",
+          "text": "A command template round-trips into a Task: 'drive --command <name> args' produces the identical Task shape (id/repo/instruction/context/constraints/engine) that a raw 'drive \"...\"' produces, with args substituted, and runs unchanged on both engines.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c9",
+      "kind": "requirement",
+      "text": "R2 Hooks: a hooks config maps lifecycle events to matcher+command entries; on a matching event Convertible runs the operator's shell command. Pre-tool-call hooks can DENY (block the tool, feed the reason back to the model as the tool result) or ALLOW; post-tool-call hooks observe/transform; task-start and finish hooks bracket the drive.",
+      "origin": "llm",
+      "status": "rejected",
+      "honesty_conditions": [
+        {
+          "id": "h2",
+          "text": "A pre-tool hook that exits non-zero blocks the tool call: the executor does NOT run it, and the model receives the hook's stderr as the tool result and can continue \u2014 proven by a test where a deny-hook on run_command stops the command from running.",
+          "status": "rejected"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c10",
+      "kind": "requirement",
+      "text": "R3 Hook I/O contract: a hook receives a JSON event payload on stdin (event name, tool name, arguments, task id, repo path) and signals outcome by exit code (0=allow, non-zero=deny with stderr fed back) plus optional structured JSON stdout (decision + additionalContext), mirroring Claude Code's hook protocol.",
+      "origin": "llm",
+      "status": "rejected",
+      "honesty_conditions": [
+        {
+          "id": "h3",
+          "text": "The hook receives well-formed JSON on stdin and its exit-code+stdout are interpreted per the documented contract; a hook that emits structured JSON (decision/additionalContext) changes loop behavior accordingly, and the contract is identical across events.",
+          "status": "rejected"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c11",
+      "kind": "requirement",
+      "text": "R4 Lifecycle integration in the chassis: the events fire inside convertible/loop.py (and the drive boundary) so they apply to every engine identically; the mock engine is the reference and a hook firing on mock vs vllm-openai must be indistinguishable in the result shape (all-engines rule; guarded by the e2e shape test).",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h4",
+          "text": "The same hook config produces the same firings and same artifact entries whether --engine is mock or vllm-openai; the e2e shape test asserts a hook-driven run is identically shaped across both engines.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c12",
+      "kind": "requirement",
+      "text": "R5 Dashboard honesty: the result artifact records every hook firing (event, matched command, decision, exit code) and which command template (if any) produced the Task, so the JSON dashboard stays a faithful trace; a denied tool call appears as a non-ok step with the hook's reason.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h5",
+          "text": "Every hook firing and the originating command appear in the result artifact JSON (valid, with event/command/decision fields), and a denied tool call is recorded as a non-ok step carrying the hook's reason.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c13",
+      "kind": "requirement",
+      "text": "R6 Agent-first CLI surface: new verbs 'convertible commands list/overview' and 'convertible hooks list/overview' follow the conventions (register(sub), --json, noun-groups expose overview, an explain catalog entry each) and pass 'teken cli doctor . --strict'.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h6",
+          "text": "'convertible commands list --json' and 'convertible hooks list --json' emit structured output, the noun groups expose 'overview', each has an explain entry, and 'teken cli doctor . --strict' passes.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c14",
+      "kind": "requirement",
+      "text": "R7 Zero runtime deps preserved: command/hook discovery, config parsing, and hook execution use only the stdlib (subprocess, json, and a config format with a stdlib reader) \u2014 pyproject 'dependencies' stays [].",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h7",
+          "text": "After the feature, 'pip show convertible-cli' / pyproject shows dependencies = [] and the test suite runs with no third-party runtime import added.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c15",
+      "kind": "decision",
+      "text": "D-config: commands and hooks live under a '.convertible/' config dir \u2014 commands as individual template files, hooks as a single JSON settings file (JSON keeps the zero-dep rule with a stdlib reader); both resolve repo-level then user-level, mirroring Claude Code's .claude/ layout.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c16",
+      "kind": "decision",
+      "text": "D-scope: this ships as a post-v0 increment (v0.x), strictly ADDITIVE to the held v0 chassis; hooks+commands are not in v0's excluded set (router/sandbox/daemon/other-drivers), so they need no re-spec of the v0 line \u2014 but they must not reintroduce any excluded item.",
+      "origin": "llm",
+      "status": "rejected",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c17",
+      "kind": "decision",
+      "text": "D-trust: hooks and commands are trusted operator-authored config under D2's existing trust model (run with operator privileges, no isolation); how repo-shipped (vs user-level) hooks get trusted/enabled is parked, not assumed.",
+      "origin": "llm",
+      "status": "rejected",
+      "honesty_conditions": [],
+      "hard_questions": [
+        {
+          "id": "q1",
+          "text": "If repo-local '.convertible/' hooks auto-run on 'convertible drive', a malicious target repo gets arbitrary code execution on the operator's machine. Do repo-shipped hooks run by default, require an explicit opt-in/trust step, or are only user-level hooks honored in this increment?",
+          "resolved": false,
+          "blocking": false
+        },
+        {
+          "id": "q2",
+          "text": "risk: Auto-running repo-shipped hooks is a code-execution vector against the operator; mitigations (trust gate, --enable-hooks flag, user-level only) trade safety against the 'just works' ergonomics Claude/Codex offer.",
+          "resolved": false,
+          "blocking": false
+        }
+      ],
+      "links": []
+    },
+    {
+      "id": "c18",
+      "kind": "non_goal",
+      "text": "No interactive-session machinery: no UserPromptSubmit/Stop-requeue/PreCompact/Notification/SessionStart-style events, no MCP server hooks, no plugin marketplace, no networked hook transport \u2014 convertible stays a one-shot harness.",
+      "origin": "llm",
+      "status": "rejected",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c19",
+      "kind": "assumption",
+      "text": "Operators author their own command templates and hook scripts; Convertible discovers and runs them but never generates or fetches them.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c20",
+      "kind": "after_state",
+      "text": "An operator drops command templates and a hooks config under .convertible/; they can run 'convertible drive --command <name> [args]' (one-shot) OR open an interactive palette session that browses/selects discovered commands and accepts ad-hoc tasks. During every loop, hooks fire at task-start / pre-tool / post-tool / finish: a pre-tool hook can ALLOW, DENY (reason fed back to the model), or REWRITE the tool arguments in-flight; a post-tool hook runs formatters/linters; repo-shipped hooks run by default. Every hook firing and the originating command are recorded in the result artifact.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h16",
+          "text": "After the feature the described flow works end-to-end: a command file expands into a Task, a configured hook fires mid-loop, and both appear in the artifact \u2014 on both engines, with no per-engine code.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c21",
+      "kind": "boundary",
+      "text": "NOT a sandbox / resource-isolation layer (D2's trusted-operator-env model is unchanged; hooks are operator-authored policy gates, not confinement). NOT a long-running daemon/server or networked control plane (the interactive palette is a FOREGROUND TTY session, not a background service). NOT a plugin marketplace or MCP transport. Commands are Task templates, not arbitrary importable code.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h17",
+          "text": "No code path opens a socket, forks a daemon, or imports a command file as Python; hooks are only ever executed as subprocesses and the palette runs in the foreground \u2014 verifiable by review.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c22",
+      "kind": "non_goal",
+      "text": "Out of scope: MCP server hooks, a plugin marketplace, networked/remote hook transport, and a background daemon. The interactive palette IS in scope (per the scope decision); only non-foreground and networked machinery is excluded.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c23",
+      "kind": "decision",
+      "text": "D-scope (RESOLVED): hooks + commands + an interactive palette mode are folded INTO the v0 line (re-spec), not deferred to a later increment. This widens D1's 'CLI-first; REPL/daemon reserved' stance to admit an interactive FOREGROUND palette session (still no daemon/server), and widens the v0 boundary accordingly.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c24",
+      "kind": "decision",
+      "text": "D-interactive (RESOLVED): convertible gains an interactive foreground session (palette) in ADDITION to one-shot 'drive'; both are thin front-ends over the same chassis (Task contract + loop + hooks + artifact). The palette adds no engine-specific behavior. This is the one change that revises convertible's documented non-interactive identity.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [
+        {
+          "id": "q3",
+          "text": "risk: The interactive palette reverses convertible's documented non-interactive, agent-first identity (CLAUDE.md: results-to-stdout, one-shot; D1 reserved REPL). Widening v0 here risks scope sprawl and a second interaction model to maintain; mitigated by making the palette a thin front-end over the same chassis with no parallel code path.",
+          "resolved": false,
+          "blocking": false
+        }
+      ],
+      "links": []
+    },
+    {
+      "id": "c25",
+      "kind": "decision",
+      "text": "D-trust (RESOLVED): repo-shipped '.convertible/' hooks RUN BY DEFAULT on 'convertible drive', under D2's trusted-operator-env model \u2014 the user accepted the code-execution tradeoff for Claude/Codex-like ergonomics. A per-repo trust gate / escape hatch is a tracked follow-up, not a v0 blocker.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [
+        {
+          "id": "q4",
+          "text": "risk: Repo-shipped hooks running by default is a code-execution vector: cloning + driving a malicious repo executes its hooks with operator privileges. Accepted under D2 for ergonomics; the follow-up trust gate / --no-hooks escape hatch is the mitigation and must be documented loudly.",
+          "resolved": false,
+          "blocking": false
+        }
+      ],
+      "links": []
+    },
+    {
+      "id": "c26",
+      "kind": "requirement",
+      "text": "R2 Hooks (revised): a hooks config maps lifecycle events (task-start, pre-tool, post-tool, finish) to matcher+command entries; a matching event runs the operator's shell command. A pre-tool hook returns one of ALLOW (run as-is), DENY (skip the tool; feed the reason back to the model as the tool result), or REWRITE (run with hook-supplied replacement arguments). Post-tool hooks observe and run side-effects (formatters/linters); task-start/finish bracket the drive.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h9",
+          "text": "A pre-tool hook proves all three outcomes: a deny-hook on run_command stops the command and the model receives the reason; a rewrite-hook on write_file changes the path/content actually written; an allow-hook is a no-op \u2014 each observable in the artifact and identical on mock and vllm-openai.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c27",
+      "kind": "requirement",
+      "text": "R3 Hook I/O contract (revised): a hook receives a JSON event payload on stdin (event, tool, arguments, task id, repo path); it signals outcome by exit code (0=allow, non-zero=deny with stderr fed back to the model) PLUS optional structured JSON stdout carrying decision (allow|deny|rewrite), replacement arguments (for rewrite), and additionalContext \u2014 mirroring Claude Code's hook protocol. The contract is identical across all events.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h10",
+          "text": "The hook reads the documented JSON payload on stdin and the loop honors exit code AND structured stdout: exit!=0 denies with stderr fed back; stdout {decision:'rewrite', arguments:{...}} replaces the tool arguments; the same payload schema is sent for every event.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c28",
+      "kind": "requirement",
+      "text": "R8 Interactive palette: a foreground session verb (e.g. 'convertible session') opens an interactive palette that lists discovered commands, takes a selection + args (or an ad-hoc instruction), and runs it through the chassis. It is a front-end over 'drive' \u2014 identical Task, loop, hooks, and artifact \u2014 never a parallel code path, and adds no engine-specific behavior.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h11",
+          "text": "Running a command via the interactive palette yields a TaskResult + artifact byte-identical in shape to 'drive --command <name>'; the palette imports and calls the same drive path (no duplicated loop), proven by a test that drives one command both ways and asserts identical result shape.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    }
+  ],
+  "open_vagueness": [
+    {
+      "id": "v1",
+      "text": "Follow-up hardening: an optional per-repo trust gate / --no-hooks escape hatch for repo-shipped hooks. DECIDED this increment: repo hooks run by default (see D-trust c25).",
+      "kind": "follow_up",
+      "claim_id": null
+    },
+    {
+      "id": "v2",
+      "text": "Whether a finish-event hook may requeue/continue the loop (re-drive) or only observe + optionally fail the run; this increment likely observe-only",
+      "kind": "follow_up",
+      "claim_id": null
+    },
+    {
+      "id": "v3",
+      "text": "Exact command-template metadata schema (which keys: description/engine/constraints/arg-hint) and the stdlib-parseable header format",
+      "kind": "unknown_nonblocking",
+      "claim_id": null
+    },
+    {
+      "id": "v4",
+      "text": "Whether post-tool hooks may rewrite a tool result/arguments in-flight, or only observe + run side-effects (formatters)",
+      "kind": "unknown_nonblocking",
+      "claim_id": null
+    }
+  ]
+}