Build brief: shell-cli — the guarded local operations plane for AI agents

[OriNachum]

Build brief: shell-cli — the guarded local operations plane for AI agents

This issue is the architectural source of truth for shell-cli. It supersedes
the original narrow “extract six tools from Colleague” framing while preserving
that extraction as the first compatibility slice.

The identity is settled:

• repository and PyPI distribution: shell-cli
• console command: shell
• import package: shell
• first consumer: agentculture/colleague

The repository is currently a green scaffold. Development has not started, so
we will establish the complete boundary before copying implementation.

1. Vision

shell-cli is the guarded local operations plane for AI agents.

Colleague should decide why, when, and which action to take.
shell-cli should provide one place to plan, authorize, execute, observe, and
record the local operation.

That includes more than the six model-facing tools. Files, arbitrary commands,
curated tests, lint, hooks, Git/worktree mechanics, and trusted external CLIs
all eventually need the same operation lifecycle even when their higher-level
semantics stay elsewhere.

The separation is:

Colleague                 shell-cli                    capability CLIs
-----------------------   --------------------------   ----------------------
reason and plan           materialize environment      devague semantics
choose capabilities       normalize operation          eidetic semantics
apply roles               evaluate operation policy    culture semantics
orchestrate agents        execute locally              coherence semantics
interpret results         capture effects/evidence     webglass web semantics
validate completion       report structured outcome

shell-cli is not another agent. It contains no model, planner, memory, web
browser, or domain workflow. It is the execution substrate beneath them.

2. The operation is the core abstraction

An operation is any local observation, mutation, process invocation, or
environment lifecycle action.

The boundary is work-affecting I/O, not every internal byte Colleague ever
writes. Runtime-private bookkeeping such as artifacts, trace/flight feeds,
telemetry buffers, caches, and lock files remains with its owning runtime unless
it executes code or touches the target workspace. This prevents shell-cli from
becoming a god-layer around ordinary application internals.

Every operation follows one lifecycle:

flowchart LR
    C["Colleague intent"] --> O["Operation"]
    O --> P["Policy + preview"]
    P --> B["Environment backend"]
    B --> E["Result + evidence"]
    E --> C

Loading

The pure library contract should be provider-neutral and JSON-serializable:

operation = Operation(
    kind="process.exec",
    arguments={"argv": ["python", "-m", "pytest"]},
    profile="project",
    apply=True,
    caller={"agent": "colleague", "task_id": "...", "tool": "run_tests"},
)

result = operations.execute(operation, environment)

The concrete names may improve during design, but the semantics are fixed:

Operation

• stable operation id
• kind and normalized arguments
• intent: observe, mutate, execute, or lifecycle
• execution profile
• caller/provenance metadata
• explicit preview/apply intent
• timeout and resource request

OperationResult

• status: previewed, denied, succeeded, failed, or timed_out
• structured output and a bounded human/model rendering
• policy verdict and reason
• known effects: changed paths, bytes written, Git refs/diff, created resources
• evidence: backend, root, cwd, mounts, network, timing, exit code, truncation
• honest completeness marker for effects that cannot be fully observed
• neutral media observation when applicable

A preview is never reported as success. A shell command preview describes what
would run; it does not pretend to predict the command's effects.

3. Environments have two independent axes

Do not encode “host,” “worktree,” and “Docker” as one overloaded mode.

Workspace/root axis

• operator checkout
• existing caller-provided worktree
• shell-managed generic worktree, when that capability is migrated

Runner axis

• HostRunner
• ContainerRunner using Docker or Podman
• a future VM/remote runner behind the same contract

The useful matrix is:

Workspace	Runner	Guarantee
Checkout	Host	Guarded host execution; no isolation
Worktree	Host	Reviewable/recoverable changes; no process isolation
Checkout	Container	Execution isolation against the selected checkout
Worktree	Container	Preferred autonomous mode: isolated execution + reviewable changes

Colleague already uses worktree + host for work/drive and parallel
children. Interactive sessions run checkout + host, and failed worktree
creation may degrade to in-place execution. shell-cli must preserve those
behaviours during migration rather than rebuilding a simpler competing
worktree system.

An environment therefore distinguishes at least:

• source_root: trusted repository/control context
• work_root: the tree operations may observe/change
• runner: host/container implementation
• read-only paths
• mount policy
• network policy
• environment-variable and secret policy
• user identity, resource limits, and timeout defaults

Policy is snapshotted from trusted control context before model mutations; an
agent must not be able to edit its own active authorization by changing a file
inside the work root.

4. Three operation profiles

Every subprocess must declare why it is running. Avoid treating all
subprocess.run calls as equally trusted.

project

Executes repository-controlled code:

• model-issued shell commands
• tests
• lint/format tools
• affected-test runners
• repository hooks when configured as project code

Target: containerized by default, network disabled unless explicitly granted.

control

Executes trusted agent/control-plane programs:

• git worktree/handoff mechanics
• devague, eidetic, culture, and coherence CLIs
• neighbour clone management
• Docker/Podman itself when materializing a container runner

Host execution is expected, but it should use argv vectors, executable
allow-lists, minimal environment inheritance, explicit cwd, bounded output, and
evidence. Raw shell strings are not appropriate for control operations.

observe

Structured reads such as file listing, text/media loading, status, and diff.
These are confined to the selected root and never imply process isolation.

5. Where every Colleague operation goes

“All operations have a place” does not mean all semantics move into shell-cli.
The mechanism moves; domain intent stays with its owner.

Current Colleague action	Target operation level	Semantic owner
read_file, list_dir	fs.read, fs.list	shell-cli
write_file, edit_file	fs.write, fs.edit	shell-cli
view_media	confined neutral fs.media observation	shell-cli; Colleague adapts model payload
run_command	process.shell, profile project	shell-cli
run_tests	curated process.exec, profile project	Colleague chooses argv; shell-cli executes
lint / affected tests	process.exec, profile project	Colleague chooses gate; shell-cli executes
hooks	process.exec with declared profile	Colleague owns hook lifecycle; shell-cli executes
worktree add/remove/prune	generic Git/worktree operations	Colleague owns task/branch lifecycle; shell-cli owns mechanism
commit/diff/merge/handoff Git calls	generic Git operations	Colleague owns handoff semantics; shell-cli executes
neighbour cloning	Git control operation	Colleague selects neighbours; shell-cli executes
Devague / Culture / Eidetic / Coherence	trusted CLI control operation	each CLI owns semantics; shell-cli invokes
subagent launch	child environment request	Colleague owns orchestration; shell-cli materializes local environment
finish, deepthink, model completion	not a local shell operation	Colleague
web search/navigation	not shell semantics	webglass-cli provider
artifacts, flight feeds, telemetry buffers, caches, locks	runtime-private bookkeeping	owning runtime; direct stdlib I/O

The end state should make direct process creation in Colleague exceptional and
mechanically guarded. Project-code execution must not bypass the selected
shell environment merely because it came from run_tests, lint, or a hook
instead of run_command.

6. Library first, CLI second

The importable API is primary. The CLI is a front end over exactly the same
operation engine.

Canonical CLI groups:

shell env describe|create|destroy
shell fs read|list|stat|write|edit|media
shell process exec|shell
shell git status|diff|worktree|commit|merge
shell policy check|explain
shell operation show
shell whoami|learn|explain|doctor

Compatibility aliases such as shell read, shell edit, and shell run may
exist, but they must not distort the library model.

Every command supports structured JSON. Results go to stdout; diagnostics go
to stderr. Long-running operations support streaming events and cancellation.

Mutation and execution verbs preview by default in the human/agent CLI and
require --apply. Reads execute immediately. Imported callers must also state
apply=True explicitly. The Colleague compatibility adapter passes it for
today's immediately-applied write_file, edit_file, and run_command
semantics.

7. Layered safety model

Safety has four distinct layers. Do not merge their claims.

1. Capability authorization — Colleague. Roles decide which semantic tools
   may be offered and invoked.
2. Operation policy — shell-cli. The normalized operation is allowed,
   denied, or previewed under an operator-supplied policy snapshot.
3. Execution isolation — runner. Host mode is a guard; container mode is a
   declared isolation boundary with a documented profile.
4. Outcome validation — Colleague. Tests, lint, integrity, acceptance, and
   handoff gates decide whether the work is acceptable.

For Colleague, the ordering must remain:

role gate → pre-tool hook/rewrite → operation policy → execution
          → evidence/result → post-tool hook → validation/handoff gates

Host honesty

HostRunner is a guard, not a sandbox. Structured filesystem primitives
are path-confined; a raw host shell command can escape the repository through
shell expansion, interpreters, absolute paths, network calls, or child
processes. Documentation and result metadata must say this plainly.

Container baseline

The default project container profile should include:

• non-root user mapped to appropriate host UID/GID
• no privileged mode and no Docker socket
• all capabilities dropped unless explicitly restored
• network disabled by default
• read-only container root filesystem
• only the selected work root mounted writable
• explicit dependency/cache volumes
• bounded CPU, memory, pids, output, and wall time
• explicit, redacted secret injection

Dependency preparation may be a separate network-enabled operation that
populates a cache/volume. It must not quietly enable network during the sealed
test or execution phase.

A linked Git worktree contains a .git pointer into the source repository's
common Git directory. Mounting only the worktree into a container therefore
does not preserve today's in-worktree Git behaviour. The container milestone
must explicitly choose between:

• project containers do not receive Git metadata; structured Git operations run
  through the trusted control plane; or
• the environment receives isolated Git metadata that cannot mutate unrelated
  host refs.

Do not solve this by broadly mounting the host repository's common .git
directory writable. That would give project code a path back into operator refs
and weaken the isolation claim.

Policy compatibility

The evaluator and policy data structures move to shell-cli. Location resolution
does not:

• shell core accepts explicit policy data/files and has no .colleague import
• the Colleague adapter preserves existing repo/user/model overlays and file
  format during migration
• shell-native policy can be versioned independently
• absent policy and malformed configured policy are distinct states; native
  policy should not silently turn a malformed declared gate into allow-all

8. Evidence is a product surface

Every operation produces a structured evidence record suitable for the model,
the operator, telemetry, and a validator such as Heimdall.

Minimum evidence:

• operation id, caller, task and tool
• requested and normalized operation
• preview/applied state
• policy verdict and matched rule
• environment id, workspace kind, runner, root and cwd
• mounts, network and resource profile
• start/end/duration
• exit code or structured error
• separately captured stdout/stderr with bounded rendering
• truncation markers plus hashes/byte counts of full captured output when known
• known filesystem/Git effects and whether that effect list is complete

Secrets are never recorded. Evidence failure must not turn an executed action
into an unrecorded success; the result must honestly mark degraded evidence.

Colleague maps neutral results into its existing ToolOutcome, Step, media
message, progress, statistics, and artifact shapes. shell-cli must not import
Colleague contracts.

9. Pure-stdlib core

The base package has zero third-party runtime dependencies.

• filesystem, policy, subprocess, JSON, hashes, dataclasses, and streaming use
  the Python standard library
• Git, Docker, and Podman are optional external executables discovered on PATH,
  not Python SDK dependencies
• optional protocol/rendering integrations live behind extras
• a zero-dependency/import-leak guard is required from the first implementation PR

The dependency direction is one-way:

Colleague → shell-cli
shell-cli ↛ Colleague

10. Compatibility invariants

The first consumer migration is successful only if Colleague loses no behaviour.

• The six existing OpenAI tool schemas remain byte-equivalent, including order
  and descriptions, until an intentional separately-reviewed schema change.
• Role curation and runtime refusal remain intact.
• Hook rewrite precedes command policy.
• Policy denial remains a non-success step with the same model-visible reason
  and telemetry meaning.
• write_file / edit_file still apply immediately through the adapter.
• run_command remains a fresh shell, rooted cwd, bounded timeout, and current
  output rendering during the parity milestone.
• line numbering, truncation, media size/type limits, and error messages remain
  compatible.
• changed-file aggregation, subagent changes, and bytes_written ROI accounting
  remain intact.
• Colleague's worktree/self-commit/continuation/merge/handoff behaviour remains intact.
• malformed arguments remain recoverable model-visible tool errors, never run aborts.

Characterization tests must compare the legacy and new execution paths against
the same fixtures before the legacy implementation is removed.

11. Target package shape

Illustrative, not a mandate on filenames:

shell/
├── operations.py       # Operation and dispatch
├── results.py          # neutral results/effects
├── environment.py      # source/work roots + profiles
├── policy.py           # evaluator and versioned policy data
├── evidence.py         # events, redaction, rendering
├── fs/                 # confined file/media operations
├── process/            # argv and raw-shell operations
├── git/                # generic Git/worktree primitives
├── runners/
│   ├── host.py
│   └── container.py
└── cli/

Avoid a giant Shell god object. Operation handlers should be small and
composable behind one lifecycle pipeline.

12. Delivery plan

This issue is the umbrella contract. Implement it in independently reviewable
vertical slices; do not ship one giant rewrite.

Milestone 0 — inventory and characterization

• inventory every process/workspace mutation path in Colleague and explicitly
  classify runtime-private bookkeeping as exempt or mediated
• classify it as project, control, observe, or not a shell operation
• snapshot the six tool schemas and observable behaviour
• establish cross-repo compatibility fixtures

Milestone 1 — operation core + parity provider

• implement Operation, OperationResult, Environment, policy, evidence,
  confined filesystem operations, and HostRunner
• expose the six compatibility schemas/provider
• keep pure-stdlib and CLI dry-run guarantees
• do not remove Colleague's implementation yet

Milestone 2 — Colleague delegates the six tools

• compose shell-cli into Colleague's existing router; do not subclass it
• preserve roles, hooks, policy ordering, result mapping and accounting
• run old/new characterization in parallel tests
• publish shell-cli, pin a tested floor in Colleague, then remove duplication

Milestone 3 — route all Colleague local operations

• project execution: run_tests, lint, affected tests, configured project hooks
• control execution: Git/worktrees/handoff, neighbour cloning, AgentCulture CLIs
• add a boundary test preventing new unclassified direct subprocess paths
• preserve Colleague's domain orchestration and worktree semantics

Milestone 4 — container runner

• Docker/Podman backend with the declared isolation profile
• project profile uses container execution when selected
• Colleague's existing worktree becomes the mounted work root
• dependency preparation and sealed execution are distinct operations
• host fallback is explicit and visible, never silent

Milestone 5 — ecosystem providers

• publish the stable capability/evidence contract for other harnesses
• integrate webglass-cli as a separate semantic provider
• let other AgentCulture CLIs reuse the control-operation invocation path

13. Test ownership

Tests move according to responsibility, not by filename.

shell-cli owns

• operation lifecycle and result states
• filesystem confinement and symlink escapes
• read/write/edit/list/media behaviour
• HostRunner and ContainerRunner
• policy parsing/evaluation
• preview/apply semantics
• evidence/redaction/truncation
• generic Git/worktree primitives
• zero-dependency/import cleanliness

Colleague retains

• role schema curation and runtime refusal
• hook ordering/rewrite/deny behaviour
• all-engine policy parity
• ToolOutcome and media-message adaptation
• changed/subagent/ROI aggregation
• worktree branch naming, continuation and handoff semantics
• loop recovery, telemetry, validation gates and artifact parity

14. Definition of done

• Every Colleague work-affecting local operation is inventoried and classified;
  runtime-private bookkeeping is explicitly accounted for.
• Every project-code execution path uses the selected shell environment.
• Every trusted control subprocess uses an explicit control profile.
• Colleague has no unclassified direct subprocess path.
• The six original tools migrate with observable parity.
• Existing worktree and handoff guarantees remain green.
• Host mode is documented as a guard, never a sandbox.
• Container mode's actual isolation profile is tested and recorded per operation.
• Structured evidence is available to Colleague, humans, telemetry, and validators.
• Base shell-cli remains pure-stdlib.
• The CLI and library use the same operation engine.
• Colleague imports shell-cli; shell-cli never imports Colleague.

15. Non-goals

• reasoning, planning, roles, or agent orchestration
• model APIs or prompt construction
• web search/navigation semantics (webglass-cli owns them)
• memory semantics (eidetic-cli owns them)
• Devague/Culture/Coherence domain logic
• PR policy, acceptance judgment, or handoff decisions
• claiming containers are perfect isolation or worktrees are sandboxes
• adding abstractions with no current Colleague or CLI consumer

16. Infographic corrections

The current first-draft infographic is visually useful, but the next version
should reflect this issue:

• title: “The Guarded Local Operations Plane for AI Agents”
• show workspace and runner as a 2×2 matrix, including worktree + host
• do not label checkout + host as Colleague's universal default
• say structured file operations are path-confined; raw host shell is not
• distinguish project execution from trusted control operations
• show policy → backend → evidence as the central lifecycle
• label the media result provider-neutral
• show Preview and Apply as distinct states, not an ambiguous toggle
• include evidence/effects as a first-class output

17. First implementation decision

Before large-scale work, reply with a concrete Milestone 0/1 plan that names:

1. the proposed operation/result/environment types;
2. the exact Colleague characterization tests;
3. how policy ordering and role refusal remain unchanged;
4. how state/accounting is mapped without importing Colleague;
5. which direct subprocess paths are parked for Milestone 3;
6. the smallest first PR that proves the seam without duplicating a framework.

Use Devague to challenge the plan for boundary leaks, false safety claims,
version skew, and operations that would bypass the selected environment.

• AgentCulture

[OriNachum]

Milestone 0/1 plan — the six things §17 asks for

This is the reply §17 gates implementation behind. It is derived from a
converged devague frame (102 coverage targets) and a confirmed 19-task plan,
both now committed: docs/specs/2026-07-18-guarded-local-operations-plane.md
and docs/plans/2026-07-18-guarded-local-operations-plane.md, with the
authoritative state under .devague/.

The plan was pressure-tested with /challenge and reviewed externally twice
(docs/external-review/). It is deliberately milestone-scoped: Security
lane + M0/M1 + the colleague M2 cutover. Later milestones are planned
separately, and 12 confirmed targets are recorded as deliberately uncovered
rather than given placeholder tasks.

---

1. The proposed operation / result / environment types

Provider-neutral, JSON-serializable, no colleague types in any signature.

operation = Operation(
    kind="process.exec",
    arguments={"argv": ["python", "-m", "pytest"]},
    profile="project",
    apply=True,
    caller={"agent": "colleague", "task_id": "...", "tool": "run_tests"},
)
result = operations.execute(operation, environment)

• Operation — stable id; kind and normalized arguments; intent (observe
  / mutate / execute / lifecycle); execution profile; caller provenance;
  explicit preview-vs-apply intent; timeout and resource request.
• OperationResult — status (previewed, denied, succeeded, failed,
  timed_out); structured output plus a bounded rendering; policy verdict and
  matched rule; known effects (changed paths, bytes written, git refs); evidence
  (backend, root, cwd, mounts, network, timing, exit code, truncation); and an
  honest completeness marker for effects that cannot be fully observed.
• Environment — two independent axes, not one overloaded mode. A
  workspace axis (source_root = trusted control context, work_root = what
  operations may change) and a runner axis (HostRunner now,
  ContainerRunner at M4). Plus read-only paths, network and mount policy,
  env/secret policy, user identity, resource limits, timeout defaults.

schema_version is on Operation, OperationResult and Environment from the
first PR, so the cross-repo contract can version without a flag day.

A preview is never reported as success — it is its own status.

2. The exact colleague characterization tests

Captured against a fixed colleague baseline, before any extraction begins,
so parity is measured against correct behaviour rather than enshrining a bug:

• Serialized-JSON snapshot of the six tool schemas. SCHEMAS[:6] is a
  contiguous slice; _PATH_DESC is interpolated into four of the six
  descriptions and must travel verbatim; list_dir uniquely has no required
  key; read_file's description embeds literal backslash escapes. Byte
  equivalence is the only honest guard.
• _read_file numbers lines then truncates — reversing renumbers, which
  is the recorded fix for colleague #240 where a served model cited a line ~240
  off.
• The recoverable-error wrapper. ToolExecutor.execute turns every
  non-ToolError exception into a model-visible recoverable error; without an
  equivalent, a handler crash aborts the drive instead of becoming a retryable
  step.
• bytes_written semantics — full content on write, replacement bytes only
  on edit.
• Media limits — a 5 MiB PNG refused, an audio file refused with the
  images-only message, asserted against both implementations.
• Mined from colleague's own suite: test_loop_run_command_policy.py,
  test_policy_carveout.py, test_policy_all_engines.py,
  test_write_apply_isolation.py, test_tools.py, test_view_media.py,
  test_tool_arg_errors.py.

A source-hash drift gate lands before extraction starts, so a colleague-side
change to a characterized handler fails loudly rather than silently invalidating
the fixtures.

3. How policy ordering and role refusal stay unchanged

The live ordering in loop.py:_run_tool_call is:

pre_tool hook (deny/rewrite) -> policy -> execute -> record -> post_tool

The single most security-relevant line in the extraction is loop.py:962,
which re-wraps as ToolCall(call.id, call.name, arguments) so the policy sees
the rewritten arguments. An extraction that passes the original call
silently reintroduces a rewrite-bypass: a hook could rewrite a denied command
into an allowed shape. Policy is therefore evaluated inside the operation
dispatch, on normalized post-rewrite arguments, so no caller can route around
the gate by calling a handler directly.

A correction to §7, offered for adjudication rather than assumed. §7
mandates preserving role gate -> pre-tool hook/rewrite -> operation policy -> execution. There is no role gate inside that sequence. Role restriction
lives in two places outside it: schema curation before the model ever sees a
tool (tools.py:570-591), and executor dispatch as the first line of execute
(tools.py:757-761) — which runs after the policy gate. We propose
preserving the ordering that exists rather than "restoring" one that does not.
Both role mechanisms stay in colleague; shell-cli has no concept of a role.

Also preserved: an absent policy section is ungated, not
empty-and-denying (presence, not emptiness, is the semantic); a malformed policy
file degrades to {} and never raises; an empty policy is byte-identical to no
policy. Absent and malformed-configured policy remain distinct states.

4. How state and accounting map without importing colleague

shell-cli emits neutral effects; colleague adapts them. The dependency arrow
points one way and is enforced by a test asserting shell-cli's import graph
contains no colleague module (and no webglass module).

• OperationResult.effects carries changed paths and bytes_written;
  colleague maps those into its own ToolOutcome, Step, media message,
  progress, statistics and artifact shapes.
• Policy resolution splits: the evaluator moves to shell-cli, location
  resolution stays in colleague. The seam passes pre-resolved candidate
  paths, so shell-cli never knows about config-dir layout and colleague keeps
  per-model overlay semantics unchanged.
• stdout/stderr are captured separately in the neutral result; the
  compatibility adapter concatenates them for run_command's current
  rendering. This satisfies both §8 and §10, and the divergence is intentional
  and dated from day one rather than discovered later.

5. Direct subprocess paths parked for Milestone 3

Derived mechanically, not transcribed. scripts/colleague_inventory.py is an
AST scanner pinned to colleague 28fee29 (1.51.0), and CI now runs --check on
every push against a clone of that exact commit, publishing debt_remaining to
the run summary.

At the pin: 21 spawn literals across 15 modules — 6 project, 15 control,
0 owned by observe — with exactly two shell=True sites (hooks.py:405,
tools.py:1022). Zero os.system, os.popen, os.exec*,
asyncio.create_subprocess_*, and zero docker/podman invocations; M0 closes
those explicitly as vacuously satisfied rather than silently.

13 modules are parked as known debt, due to reach zero by end of M3:

Profile	Modules
project	tools.py, affectedtests.py, lint.py, hooks.py, livecheck.py
control	worktrees.py, handoff.py, neighbours.py, culture.py, devague.py, memory.py, coherence.py, resident/steward.py

background.py and experiment.py are allow-listed permanently — domain
orchestration, not debt. A debt entry is a scheduled migration, never an
exemption; a new unclassified path fails CI immediately.

Three ambiguities we flag rather than assume: lint.py:100-102 runs
ruff check --fix / ruff format, so it mutates tracked source while
wearing a gate's clothing — its mutations must surface as changed-path effects.
The two shell=True sites have different trust stories (tools.py:1022 runs a
model-authored string; hooks.py:405 runs a repo-authored hook around every
tool call, including control-plane ones). And background.py:139 /
experiment.py:440 spawn detached, with background.py re-invoking colleague
itself — re-entering every bucket in a process the mediator no longer
supervises.

6. The smallest first PR that proves the seam

Not the six tools. The first implementation PR is the foundation slice:
Operation, OperationResult, Environment with schema_version, the
lifecycle pipeline, and a HostRunner skeleton — shipping with its three
guards in the same PR, not later:

1. the zero-dependency guard (asserts dependencies literally and snapshots
   sys.modules to catch import leaks);
2. the honesty gate, so no unguarded surface can land first;
3. the negative-import check (no colleague, no webglass).

It proves the seam because it is end-to-end — one real operation flows intent →
policy → runner → result → evidence — while duplicating no framework: no
registry, no plugin system, no god object. Handlers stay small behind one
lifecycle pipeline, and nothing is abstracted that lacks a current consumer.

colleague's implementation is not removed at that point. Removal happens
only after differential parity runs both implementations in one session over
identical fixtures.

---

Sequencing note

One colleague-side fix sequences ahead of all shell-cli extraction work. It is
being handled through a private security channel rather than a public issue, and
is explicitly exempt from this migration-proposal gate — holding it behind an
extraction proposal would trade a real exposure window for tidy sequencing. The
characterization fixtures in §2 are captured only after it ships, so parity is
measured against fixed behaviour.

What is deliberately not in this plan

12 confirmed targets are uncovered by design and recorded as out_of_scope
risks: worktree concurrency (M3), the standalone hook-policy change, container
work (M4), and the WebGlass seam (M5, and a separate repository besides).
devague's coverage gate cannot represent a milestone-scoped plan
(devague#85), so rather than
write tasks that mention a target without delivering it — which an external
reviewer caught in the first draft — the plan exports through a generated
projection that names every deferred target explicitly.

• shell-cli (Claude)

[OriNachum]

Correction to §5 of the plan above

An adversarial live test of scripts/colleague_inventory.py invalidates a claim
I made in §5. Retracting it here rather than editing the comment, so the
correction is visible.

What §5 said: "CI now runs --check on every push against a clone of that
exact commit" — framed, in t73 and in the surrounding text, as a gate where a
new unclassified path fails immediately.

What is actually true: the scanner is a drift detector against a pinned
baseline, not an enforcement boundary. The live test produced 30 executed
evasions at exit 0 and 6 false positives. Full inventory: #7.

The architectural one: ALLOWLIST is keyed per module, not per site.
Three brand-new spawns were added to tools.py — two of them shell=True,
running rm -rf and cat /etc/shadow — and --check returned exit 0 with no
signal. Since 15 modules are already allow-listed, a new unmediated path in any
existing file is invisible by design. Widening the detected-call set does not fix
that; per-site pinning would.

Also, subprocess.getoutput("cmd") defeats it in one line, and one level of
indirection (sp = subprocess; sp.run(...)) defeats the alias hardening.

What stands unchanged. The inventory numbers themselves are still correct and
still mechanically derived: 21 spawn literals across 15 modules, 6 project /
15 control, 13 debt modules, reproduced exactly at SHA 28fee29 with the
sha_matches guard asserting the tree. The parked-for-M3 module table in §5 is
accurate. What changed is the strength of the guarantee around those numbers, not
the numbers.

One figure needs a caveat rather than a retraction: shell=True detection
requires a literal ast.Constant, so "exactly two shell=True sites" is a
statement about how colleague spells its arguments at this commit, not a
measurement of how often it shells out. shell=SH or **{"shell": True} would
report nothing.

Everything else in the six-part plan stands. §1–§4 and §6 are unaffected, and the
sequencing note still holds.

This is exactly the class of overclaim this repo's honesty tests exist to
prevent, and they did not catch it — test_honesty.py guards the execution
guard's posture, and nothing guarded the tooling's. The descriptions in the
scanner docstring, the CI job, CLAUDE.md and the delivery summary have all been
corrected in #6.

• shell-cli (Claude)