theslopmachine 0.7.2 → 0.7.5

package/assets/skills/hardening-gate/SKILL.md

@@ -60,6 +60,7 @@ Hardening should treat these as the main review buckets before final evaluation
 - enforce env-file discipline during hardening
 - run documentation verification against the real codebase and runtime behavior, not just document existence
 - if `README.md` declares containerized runtime or broad test commands, verify that the final delivered output really supports those exact commands and that the docs do not overpromise beyond what the repo actually does
+- verify that every dependency needed by the README-documented `docker compose up --build` and `./run_tests.sh` paths is declared in Dockerfiles or other repo-controlled container build definitions rather than relying on host-installed packages or runtimes
 - audit README compliance against the strict post-bugfix README review shape:
   - project type near the top
   - startup instructions

package/assets/skills/planning-guidance/SKILL.md

@@ -163,6 +163,7 @@ Selected-stack defaults:
 - `./run_tests.sh` must exist for every project as the platform-independent broad test wrapper
 - `./run_tests.sh` must be able to run on a clean Linux VM that only has Docker and curl available by default
 - do not require host package managers, host language runtimes, or host test tooling for the broad test path unless the stack absolutely forces it and the exception is explicitly justified
+- define all runtime and broad-test dependencies in Dockerfiles, image build stages, or other repo-controlled container build definitions; do not rely on hidden host packages even when the developer machine happens to have them
 - `./run_tests.sh` must prepare or install anything required inside its own controlled execution path when that setup is needed for a clean environment
 - for web projects, `./run_tests.sh` must run the full test path through Docker rather than a purely local test invocation
 - when host-level setup would otherwise be required, prefer a Dockerized `./run_tests.sh` path even outside traditional web stacks so the broad verification remains portable

package/assets/skills/scaffold-guidance/SKILL.md

@@ -90,6 +90,7 @@ At scaffold time, do not require:
 - create `./run_tests.sh` during scaffold for every project
 - create `./run_app.sh` during scaffold for non-web platforms when it helps expose the host-side or platform-specific local flow, but keep `docker compose up --build` and containerized `./run_tests.sh` as required baseline commands
 - if the project has database dependencies, create `./init_db.sh` during scaffold as the only project-standard database initialization path
+- define the runtime and broad-test dependency set in Dockerfiles or other repo-controlled container build definitions during scaffold; do not assume host package managers, host SDKs, or host language runtimes beyond Docker and documented baseline prerequisites
 - make the scaffold handoff compact and checklist-driven rather than a long narrative dump
 
 ## Minimal real test floor

package/assets/skills/submission-packaging/SKILL.md

@@ -17,7 +17,7 @@ Use this skill only during `P9 Submission Packaging`.
 - packaging is incomplete until every required final artifact path has been verified to exist
 - do not stop packaging for approval, status confirmation, or handoff once this phase has begun; continue until the package is complete
 - when a task or platform question id exists such as `TASK-123`, use that exact id as the final deliverable/archive name without adding an extra `ID-` prefix
-- normalize project-type metadata and packaging labels to the expected engineering categories such as `full_stack` or `fullstack`, `pure_backend`, `pure_frontend`, `cross_platform_app`, or `mobile_app`
+- normalize `metadata.json.project_type` to the exact allowed values `fullstack`, `backend`, `android`, `ios`, `desktop`, or `web`, and keep any packaging labels aligned with that same delivered project reality
 
 ## Required final structure
 
@@ -32,16 +32,16 @@ The final delivery layout in the parent project root must be:
   - `sessions/`
   - `sessions/<label>.json` for every tracked developer session, including `develop-N.json` and `bugfix-N.json` when present
 - for Claude-backed developer sessions:
-  - `claude-sessions.zip` in the parent root containing the whole Claude project session folder once
+  - `claude-sessions.zip` in the parent root containing only the tracked relevant Claude session artifacts once
   - no `sessions/` directory is required when all tracked developer sessions are Claude-backed
 - `metadata.json`
 - `.tmp/`
   - `audit_report-<N>.md` only for bugfix-triggering `partial pass` audits
-  - `audit_report-<N>-fix_check-<M>.md` when present
+  - `audit_report-<N>-fix_check.md` when present
   - `test_coverage_and_readme_audit_report.md`
 - `repo/`
 
-In the clean two-bugfix path, `.tmp/` should end with at least 5 required markdown reports once the final coverage/README audit is included: 2 kept partial-pass audit reports, at least 2 corresponding fix-check reports, and the final coverage/README audit report. Extra fix checks may legitimately increase that count.
+In the clean two-bugfix path, `.tmp/` should end with at least 5 required markdown reports once the final coverage/README audit is included: 2 kept partial-pass audit reports, 2 corresponding single fix-check reports, and the final coverage/README audit report.
 
 Inside the delivered `repo/`, the repository must remain self-sufficient:
 
@@ -56,7 +56,7 @@ No screenshots are required as packaging artifacts.
 ## Required packaging actions
 
 - verify the parent-root package structure matches the blueprint exactly
-- make sure parent-root `../metadata.json` is complete and reflects the delivered project truthfully
+- make sure parent-root `../metadata.json` is complete, reflects the delivered project truthfully, and contains only these keys: `prompt`, `project_type`, `frontend_language`, `backend_language`, `database`, `frontend_framework`, `backend_framework`
 - verify parent-root `../docs/design.md` exists and reflects the final delivered design when applicable
 - verify parent-root `../docs/api-spec.md` exists and reflects the final delivered interfaces when applicable
 - verify parent-root `../docs/test-coverage.md` exists and reflects the final delivered verification coverage
@@ -74,7 +74,7 @@ No screenshots are required as packaging artifacts.
 - verify parent-root `../.tmp/` exists and contains the required audit and fix-check reports
 - verify parent-root `../.tmp/test_coverage_and_readme_audit_report.md` exists from the final post-bugfix coverage/README audit
 - export all tracked developer sessions before closing packaging
-- when packaging succeeds, update workflow metadata to mark `packaging_completed` as true
+- when packaging succeeds and any tracked live Claude tmux lanes have been stopped, update workflow metadata to mark `packaging_completed` as true
 
 ## Session export sequence
 
@@ -85,18 +85,20 @@ Export tracked developer sessions from metadata using the tracked lane labels, f
 
 For session export:
 
-1. if at least one tracked developer session backend is `claude` or `claude-live`, run `node ~/slopmachine/utils/package_claude_session.mjs --cwd "$PWD" --session-id <any-claude-session-id> --label claude-sessions --output ../claude-sessions.zip`
+1. if at least one tracked developer session backend is `claude` or `claude-live`, gather the tracked Claude `session_id` values from metadata and run `node ~/slopmachine/utils/package_claude_session.mjs --cwd "$PWD" --session-ids <tracked-claude-session-id-1,tracked-claude-session-id-2,...> --label claude-sessions --output ../claude-sessions.zip`
 2. if `<backend>` is neither `claude` nor `claude-live`, run `opencode export <session-id> > ../session-export-<label>.raw`
 3. if `<backend>` is neither `claude` nor `claude-live`, run `python3 ~/slopmachine/utils/strip_session_parent.py ../session-export-<label>.raw --output ../sessions/<label>.json`
 
 Where `<backend>` comes from the tracked developer session record in metadata.
 Use `opencode` when no explicit backend field exists or when the backend is not Claude-backed.
-For Claude-backed sessions, the package helper resolves the Claude project folder under `~/.claude/projects/` from a tracked `session_id` plus the current project `cwd`, normalizes the copied JSONL session files by flattening channel-originated user turns, and packages that folder once.
+For Claude-backed sessions, the package helper resolves the tracked Claude session artifacts under `~/.claude/projects/` from the tracked `session_id` values plus the current project `cwd`, copies only those tracked `session_id.jsonl` files and matching `session_id/` companion directories when present, normalizes the copied JSONL session files by flattening channel-originated user turns, and packages only that tracked set once. Do not sweep unrelated random Claude sessions into the archive just because they share the same Claude project directory.
 
 After those steps:
 
 - verify every non-Claude developer session has been exported into `../sessions/<label>.json`
-- verify Claude-backed sessions have been packaged once into `../claude-sessions.zip`
+- verify Claude-backed sessions have been packaged once into `../claude-sessions.zip` using the tracked relevant Claude session ids rather than the whole local Claude project directory
+- after Claude-backed session packaging succeeds, stop each tracked live Claude runtime with `node ~/slopmachine/utils/claude_live_stop.mjs --runtime-dir <runtime_dir>` before marking packaging complete
+- verify each stopped Claude runtime no longer has a live tmux session before closing packaging
 - treat only the raw `../session-export-<label>.raw` files as temporary packaging intermediates
 - remove the raw `../session-export-<label>.raw` files before closing packaging
 - if the required utilities, metadata session ids, or output files are missing, packaging is not ready to continue
@@ -127,13 +129,14 @@ After those steps:
 - confirm the cleanup helper has been run and that no known recursive cleanup targets remain in the delivered repo tree
 - confirm no environment-dependent dependency directories, editor-state folders, runtime caches, or workflow utility scripts are packaged into the delivered product
 - confirm parent-root `../.tmp/` exists and contains the required kept `audit_report-<N>.md` files for partial-pass audits only
-- confirm every bugfix-triggering audit number has its matching `audit_report-<N>-fix_check-<M>.md` files when fix checks were required
+- confirm every bugfix-triggering audit number has its matching `audit_report-<N>-fix_check.md` file when fix checks were required
 - confirm parent-root `../.tmp/test_coverage_and_readme_audit_report.md` exists and is the final replaced copy rather than a numbered variant
 - confirm parent-root `../docs/test-coverage.md` explains the tested flows, mapped tests, and coverage boundaries
 - confirm every non-Claude developer session exists under parent-root `../sessions/` using the tracked `<label>.json` names
 - confirm Claude-backed developer sessions exist in the parent root as `claude-sessions.zip`
+- confirm no tracked Claude live tmux session is still running after packaging finishes
 - confirm parent-root `../docs/` remains consistent as an external reference set when workflow policy still requires it, but the delivered repo does not depend on it
-- confirm parent-root metadata fields are populated correctly
+- confirm parent-root metadata fields are populated correctly and no extra keys exist in `../metadata.json`
 - confirm workflow metadata marks `packaging_completed` as true
 - confirm no `submission/` directory or other obsolete packaging artifact structure remains
 

package/assets/skills/verification-gates/SKILL.md

@@ -12,8 +12,8 @@ Use this skill after development begins whenever you are reviewing work, decidin
 - load this skill before review, acceptance, rejection, runtime gate interpretation, hardening readiness decisions, or broad-gate decisions
 - treat it as owner-side review and gate guidance, not developer-visible text
 - use this skill as the source of truth for owner-side verification, review pressure, and gate interpretation
-- outside the final human decision, do not pause execution for human approval while using this skill; continue reviewing, rejecting, fixing, and rerunning until the work qualifies
-- outside the clarification-complete gate and `P8 Final Human Decision`, do not pause execution just to summarize progress or ask the user whether to continue; keep driving the workflow until the current gate or phase objective is actually satisfied
+- do not pause execution for human approval while using this skill; continue reviewing, rejecting, fixing, and rerunning until the work qualifies
+- clarification completion and `P8 Final Readiness Decision` are internal workflow transitions, not user-stop gates; do not pause execution just to summarize progress or ask the user whether to continue
 
 ## Documentation and repo hygiene
 
@@ -48,6 +48,7 @@ Use this skill after development begins whenever you are reviewing work, decidin
 - for Android, mobile, desktop, and iOS-targeted projects, allow `./run_app.sh` as an additional platform helper but not as a replacement for the required Docker command
 - require `./run_tests.sh` to be self-sufficient enough to run from a clean Linux VM that only has Docker and curl available by default
 - do not accept a broad test path that depends on host package managers or preinstalled host language runtimes when Docker can provide the execution environment instead
+- do not accept Docker runtime/test paths that rely on undeclared host packages, SDKs, compilers, CLIs, or language runtimes; all such dependencies must be defined in Dockerfiles or other repo-controlled container build definitions
 - for web projects, require `./run_tests.sh` to be the Dockerized broad test path used only for the limited broad verification moments rather than as the ordinary development verification path
 - when host-level setup would otherwise be required, prefer a Dockerized `./run_tests.sh` path even outside traditional web stacks so the broad verification remains portable
 - for non-web projects, require `./run_tests.sh` to remain containerized and usable as the platform-equivalent broad test path used for final broad verification
@@ -162,7 +163,7 @@ Any earlier extra Docker run needs a concrete blocker-based justification.
 
 Use evidence such as internal metadata files, structured Beads comments, verification command results, and file/project-state checks.
 
-- clarification requires the `clarification-gate` conditions plus explicit approval record
+- clarification requires the `clarification-gate` conditions plus an internally accepted clarification record that is ready to roll directly into planning
 - planning requires the `developer-session-lifecycle` and planning-gate conditions plus a fresh planning-oriented start and the required documentation and repo hygiene state when relevant
 - planning exit also requires explicit owner review that the accepted planning artifacts cover the section-addressable contract deeply enough for later implementation: in-scope and out-of-scope, actors and success paths, modules, business rules, state machines, permissions, validation, verification strategy, checkpoints, and definition of done when applicable
 - planning exit does not pass if those sections exist only nominally or remain too vague to drive implementation without broad reinvention
@@ -213,7 +214,7 @@ Use evidence such as internal metadata files, structured Beads comments, verific
 - before `P7`, for `fullstack` and `web` projects, require an explicit frontend unit-test verdict backed by direct file-level evidence; if frontend unit tests are missing or insufficient, treat that as a critical gap
 - before `P7`, require repo-local build/preview/config traceability plus disclosure in `README.md` of feature flags, debug/demo surfaces, and mock defaults when those surfaces exist
 - before `P7`, require logging and validation contracts to be statically traceable enough that the owner can review them from the repo plus external references when needed
-- final evaluation readiness requires the audit-numbered `P7` model under `../.tmp/`; only `partial pass` fresh evaluations leave persisted `audit_report-<N>.md` files, `fail` audits route back to the latest `develop-N` session and discard their working report after triage, `pass` audits discard their working report and rerun fresh evaluation, `partial pass` audits open scoped `bugfix-N` sessions whose fix checks are stored as `audit_report-<N>-fix_check-<M>.md`, and the last subphase of `P7` runs `test_coverage_and_readme_audit_report.md` with up to 3 remediation attempts before carrying the latest report forward
+- final evaluation readiness requires the audit-numbered `P7` model under `../.tmp/`; only `partial pass` fresh evaluations leave persisted `audit_report-<N>.md` files, `fail` audits route back to the latest `develop-N` session and discard their working report after triage, `pass` audits discard their working report and rerun fresh evaluation, `partial pass` audits open scoped `bugfix-N` sessions whose fix checks are stored in a single replace-in-place `audit_report-<N>-fix_check.md`, and the last subphase of `P7` runs `test_coverage_and_readme_audit_report.md` with up to 3 remediation attempts before carrying the latest report forward
 - before leaving `P7`, if `README.md` documents `docker compose up --build` and/or `./run_tests.sh` as part of the delivered external contract, run those exact commands on the final state and require them to pass before moving to `P8`
 - if the `P7` issue-fix loop materially reopens the integrated verification boundary, route it back through integrated verification before continuing with follow-up fix verification
 - before leaving `P7`, require the parent-root `../.tmp/test_coverage_and_readme_audit_report.md` to exist from the last `P7` subphase; if it finds issues, route the fixes to the currently active recoverable developer session, replace the report, and rerun the audit, but stop after 3 remediation attempts and keep the latest report as the final carried-forward evidence

package/assets/slopmachine/scaffold-playbooks/docker-shared-contract.md

@@ -49,6 +49,7 @@ That proof differs by family, but it must always be **meaningful**:
 At minimum, `docker compose up --build` must prove all of the following:
 
 - images build from source in the repo
+- all system packages, language runtimes, CLIs, compilers, and SDKs required by the runtime path are declared in Dockerfiles or image build stages rather than assumed from the host
 - declared runtime or support services start without hidden host setup
 - readiness can be observed through healthchecks, predictable logs, or explicit successful artifact production
 - the stack reaches a meaningful healthy state without manual container surgery
@@ -71,6 +72,9 @@ It must prove that the scaffold can be verified from a clean-enough developer or
 - run smoke checks against the actual baseline contract
 - clean up one-off test containers and temporary runtime state
 
+`docker compose up --build` and `./run_tests.sh` must never depend on host-installed language runtimes, package managers, CLIs, compilers, SDKs, or other local system packages beyond Docker and the documented baseline host prerequisites.
+If a dependency is needed for runtime or broad verification, define it in Dockerfiles, image build stages, or other repo-controlled container build definitions.
+
 `./run_tests.sh` must not be a fake wrapper that only prints TODOs, only runs lint when runtime proof is expected, or silently skips the meaningful part of verification.
 
 Minimum proof by family:

package/assets/slopmachine/templates/AGENTS.md

@@ -15,6 +15,7 @@ This file is the repo-local engineering rulebook for `slopmachine` projects.
 - Read the code before making assumptions.
 - Work in meaningful vertical slices.
 - Do not call work complete while it is still shaky.
+- Once given a bounded objective, keep going autonomously until it is complete or genuinely blocked; do not stop for reassurance or permission when a prompt-faithful default lets you proceed.
 - Reuse and extend shared cross-cutting patterns instead of inventing incompatible local ones.
 - Before coding, identify the actors or personas touched by the change and the concrete path to success for each one.
 - Make important business rules explicit before coding: defaults, limits, allowed transitions, uniqueness, conflicts, reversals, retries, and ownership rules when they matter.
@@ -28,7 +29,7 @@ This file is the repo-local engineering rulebook for `slopmachine` projects.
 
 - Preserve the full prompt intent, including implied business constraints.
 - Do not weaken required actor models, operator flows, security controls, or lifecycle behavior for implementation convenience.
-- If a requirement is ambiguous, choose the safest prompt-faithful behavior or surface the ambiguity instead of guessing lazily.
+- If a requirement is ambiguous, choose the safest prompt-faithful behavior and keep moving when a defensible default exists; surface the ambiguity only when it is genuinely blocking or materially changes the product contract.
 - If the feature depends on business rules, make those rules traceable in code, tests, and `README.md` rather than leaving them implicit.
 
 ## Architecture Rules
@@ -88,6 +89,7 @@ This file is the repo-local engineering rulebook for `slopmachine` projects.
 - `./run_tests.sh` should use the same startup-value model as `docker compose up --build` rather than a separate pre-seeded test-secret path.
 - If local-development runtime values must persist across restarts, keep them only in Docker-managed runtime state rather than committed repo files.
 - If such a bootstrap script exists, document in the script and in `README.md` that it is for local development bootstrap only and is not the production secret-management path.
+- Do not let `docker compose up --build` or `./run_tests.sh` depend on host-installed packages, SDKs, language runtimes, CLIs, or toolchains beyond Docker and the documented baseline host prerequisites; define those dependencies in Dockerfiles or other repo-controlled container build definitions.
 
 ## Product Integrity Rules
 

package/assets/slopmachine/templates/CLAUDE.md

@@ -15,6 +15,7 @@ This file is the repo-local engineering rulebook for `slopmachine-claude` projec
 - Read the code before making assumptions.
 - Work in meaningful vertical slices.
 - Do not call work complete while it is still shaky.
+- Once given a bounded objective, keep going autonomously until it is complete or genuinely blocked; do not stop for reassurance or permission when a prompt-faithful default lets you proceed.
 - Reuse and extend shared cross-cutting patterns instead of inventing incompatible local ones.
 - Before coding, identify the actors or personas touched by the change and the concrete path to success for each one.
 - Make important business rules explicit before coding: defaults, limits, allowed transitions, uniqueness, conflicts, reversals, retries, and ownership rules when they matter.
@@ -28,7 +29,7 @@ This file is the repo-local engineering rulebook for `slopmachine-claude` projec
 
 - Preserve the full prompt intent, including implied business constraints.
 - Do not weaken required actor models, operator flows, security controls, or lifecycle behavior for implementation convenience.
-- If a requirement is ambiguous, choose the safest prompt-faithful behavior or surface the ambiguity instead of guessing lazily.
+- If a requirement is ambiguous, choose the safest prompt-faithful behavior and keep moving when a defensible default exists; surface the ambiguity only when it is genuinely blocking or materially changes the product contract.
 - If the feature depends on business rules, make those rules traceable in code, tests, and `README.md` rather than leaving them implicit.
 
 ## Architecture Rules
@@ -88,6 +89,7 @@ This file is the repo-local engineering rulebook for `slopmachine-claude` projec
 - `./run_tests.sh` should use the same startup-value model as `docker compose up --build` rather than a separate pre-seeded test-secret path.
 - If local-development runtime values must persist across restarts, keep them only in Docker-managed runtime state rather than committed repo files.
 - If such a bootstrap script exists, document in the script and in `README.md` that it is for local development bootstrap only and is not the production secret-management path.
+- Do not let `docker compose up --build` or `./run_tests.sh` depend on host-installed packages, SDKs, language runtimes, CLIs, or toolchains beyond Docker and the documented baseline host prerequisites; define those dependencies in Dockerfiles or other repo-controlled container build definitions.
 
 ## Product Integrity Rules
 

package/assets/slopmachine/utils/claude_live_launch.mjs

@@ -36,8 +36,8 @@ const cwd = argv.cwd ? path.resolve(argv.cwd) : null
 const lane = argv.lane
 const agentName = argv.agent || 'developer'
 const claudeCommand = argv['claude-command'] || 'claude'
-const laneModel = argv.model || 'sonnet'
-const laneEffort = argv.effort || null
+const laneModel = argv.model || 'opus'
+const laneEffort = argv.effort || 'medium'
 const subagentModel = argv['subagent-model'] || 'sonnet'
 const launchTimeoutMs = Number.parseInt(argv['timeout-ms'] || String(DEFAULT_LAUNCH_TIMEOUT_MS), 10)
 const replace = argv.replace === '1'

package/assets/slopmachine/utils/normalize_claude_session.py

@@ -7,7 +7,7 @@ import json
 import re
 import sys
 from pathlib import Path
-from typing import Any
+from typing import Any, Iterable
 
 
 CHANNEL_MESSAGE_RE = re.compile(
@@ -15,6 +15,10 @@ CHANNEL_MESSAGE_RE = re.compile(
     re.DOTALL,
 )
 
+CHANNEL_INSTRUCTION_RE = re.compile(r"slopmachine-[^\s\"]+", re.IGNORECASE)
+CHANNEL_TAG_RE = re.compile(r"</?channel\b[^>]*>", re.IGNORECASE)
+WEBHOOK_TERM_RE = re.compile(r"\b(?:webhook|UserPromptSubmit|StopFailure)\b", re.IGNORECASE)
+
 
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(
@@ -37,6 +41,11 @@ def parse_args() -> argparse.Namespace:
         action="store_true",
         help="Keep channel origin metadata fields instead of stripping them",
     )
+    parser.add_argument(
+        "--recursive",
+        action="store_true",
+        help="If input is a directory, recursively normalize all .jsonl files into the output directory.",
+    )
     return parser.parse_args()
 
 
@@ -49,55 +58,137 @@ def maybe_flatten_channel_content(content: str) -> tuple[str, bool]:
     return body, True
 
 
+def scrub_string(value: str) -> str:
+    flattened, _ = maybe_flatten_channel_content(value.strip())
+    normalized = flattened
+    normalized = CHANNEL_TAG_RE.sub("", normalized)
+    normalized = CHANNEL_INSTRUCTION_RE.sub("normalized-channel", normalized)
+    normalized = WEBHOOK_TERM_RE.sub("", normalized)
+    normalized = normalized.replace(
+        'Messages arrive as ordinary inbound work requests. ...',
+        'Messages arrive as ordinary inbound work requests.',
+    )
+    return normalized
+
+
+def scrub_value(value: Any) -> Any:
+    if isinstance(value, str):
+        return scrub_string(value)
+    if isinstance(value, list):
+        return [scrub_value(item) for item in value]
+    if isinstance(value, dict):
+        return {key: scrub_value(item) for key, item in value.items()}
+    return value
+
+
+def strip_channel_instruction_attachment(attachment: dict[str, Any]) -> tuple[dict[str, Any] | None, bool]:
+    if attachment.get("type") != "mcp_instructions_delta":
+        return attachment, False
+
+    changed = False
+    normalized = dict(attachment)
+
+    added_names = normalized.get("addedNames")
+    if isinstance(added_names, list):
+        filtered_names = [name for name in added_names if not (isinstance(name, str) and name.startswith("slopmachine-"))]
+        if filtered_names != added_names:
+            normalized["addedNames"] = filtered_names
+            changed = True
+
+    added_blocks = normalized.get("addedBlocks")
+    if isinstance(added_blocks, list):
+        filtered_blocks = []
+        for block in added_blocks:
+            if not isinstance(block, str):
+                filtered_blocks.append(block)
+                continue
+            if "<channel source=" in block or "Messages arrive as <channel source=" in block or CHANNEL_INSTRUCTION_RE.search(block):
+                changed = True
+                continue
+            filtered_blocks.append(block)
+        if filtered_blocks != added_blocks:
+            normalized["addedBlocks"] = filtered_blocks
+
+    removed_names = normalized.get("removedNames")
+    if isinstance(removed_names, list) and not normalized.get("addedNames") and not normalized.get("addedBlocks") and not removed_names:
+        return None, True
+
+    if not normalized.get("addedNames") and not normalized.get("addedBlocks") and not normalized.get("removedNames"):
+        return None, True
+
+    return scrub_value(normalized), changed
+
+
+def strip_transport_metadata(record: dict[str, Any], *, keep_channel_origin: bool) -> dict[str, Any]:
+    normalized = dict(record)
+    normalized.pop("isMeta", None)
+    if not keep_channel_origin:
+        normalized.pop("origin", None)
+    return scrub_value(normalized)
+
+
 def normalize_record(record: dict[str, Any], *, keep_channel_origin: bool) -> dict[str, Any] | None:
     if record.get("type") == "queue-operation":
         return None
 
+    if record.get("type") == "attachment":
+        attachment = record.get("attachment")
+        if isinstance(attachment, dict):
+            cleaned_attachment, _ = strip_channel_instruction_attachment(attachment)
+            if cleaned_attachment is None:
+                return None
+            normalized = strip_transport_metadata(record, keep_channel_origin=keep_channel_origin)
+            normalized["attachment"] = cleaned_attachment
+            return normalized
+        return strip_transport_metadata(record, keep_channel_origin=keep_channel_origin)
+
     if record.get("type") != "user":
-        return record
+        return strip_transport_metadata(record, keep_channel_origin=keep_channel_origin)
 
     message = record.get("message")
     if not isinstance(message, dict):
-        return record
+        return strip_transport_metadata(record, keep_channel_origin=keep_channel_origin)
 
     if message.get("role") != "user":
-        return record
+        return strip_transport_metadata(record, keep_channel_origin=keep_channel_origin)
 
     content = message.get("content")
     if not isinstance(content, str):
-        return record
+        return strip_transport_metadata(record, keep_channel_origin=keep_channel_origin)
 
     flattened, changed = maybe_flatten_channel_content(content)
+    normalized = strip_transport_metadata(record, keep_channel_origin=keep_channel_origin)
     if not changed:
-        return record
+        return normalized
 
-    normalized = dict(record)
     normalized_message = dict(message)
     normalized_message["content"] = flattened
     normalized["message"] = normalized_message
-    normalized.pop("isMeta", None)
-
-    if not keep_channel_origin:
-      normalized.pop("origin", None)
 
     return normalized
 
 
-def main() -> int:
-    args = parse_args()
-    input_path = Path(args.input)
-    output_path = Path(args.output)
+def iter_input_files(input_path: Path, recursive: bool) -> Iterable[Path]:
+    if input_path.is_file():
+        yield input_path
+        return
 
-    if not input_path.exists():
-        print(f"Input file not found: {input_path}", file=sys.stderr)
-        return 1
+    if not input_path.is_dir():
+        raise ValueError(f"Input path must be a file or directory: {input_path}")
 
-    output_path.parent.mkdir(parents=True, exist_ok=True)
+    pattern = "**/*.jsonl" if recursive else "*.jsonl"
+    for candidate in sorted(input_path.glob(pattern)):
+        if candidate.is_file():
+            yield candidate
 
+
+def normalize_file(input_path: Path, output_path: Path, *, keep_channel_origin: bool, keep_queue_operations: bool) -> dict[str, Any]:
     total = 0
     queue_dropped = 0
     channel_flattened = 0
 
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
     with input_path.open("r", encoding="utf-8") as src, output_path.open("w", encoding="utf-8") as dst:
         for line_no, line in enumerate(src, start=1):
             stripped = line.strip()
@@ -108,17 +199,15 @@ def main() -> int:
             try:
                 record = json.loads(stripped)
             except json.JSONDecodeError as exc:
-                print(f"Invalid JSON at line {line_no}: {exc}", file=sys.stderr)
-                return 1
+                raise ValueError(f"Invalid JSON at line {line_no} in {input_path}: {exc}") from exc
 
             if not isinstance(record, dict):
-                print(f"Expected object at line {line_no}", file=sys.stderr)
-                return 1
+                raise ValueError(f"Expected object at line {line_no} in {input_path}")
 
-            normalized = normalize_record(record, keep_channel_origin=args.keep_channel_origin)
+            normalized = normalize_record(record, keep_channel_origin=keep_channel_origin)
 
             if normalized is None:
-                if record.get("type") == "queue-operation" and not args.keep_queue_operations:
+                if record.get("type") == "queue-operation" and not keep_queue_operations:
                     queue_dropped += 1
                 continue
 
@@ -137,14 +226,60 @@ def main() -> int:
 
             dst.write(json.dumps(normalized, ensure_ascii=False) + "\n")
 
-    summary = {
-        "ok": True,
+    return {
         "input": str(input_path),
         "output": str(output_path),
         "records_seen": total,
         "queue_operations_dropped": queue_dropped,
         "channel_messages_flattened": channel_flattened,
     }
+
+
+def main() -> int:
+    args = parse_args()
+    input_path = Path(args.input)
+    output_path = Path(args.output)
+
+    if not input_path.exists():
+        print(f"Input file not found: {input_path}", file=sys.stderr)
+        return 1
+
+    try:
+        files = list(iter_input_files(input_path, recursive=args.recursive))
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    summaries = []
+    for source in files:
+        if input_path.is_dir():
+            rel = source.relative_to(input_path)
+            dest = output_path / rel
+        else:
+            dest = output_path
+        try:
+            summaries.append(
+                normalize_file(
+                    source,
+                    dest,
+                    keep_channel_origin=args.keep_channel_origin,
+                    keep_queue_operations=args.keep_queue_operations,
+                )
+            )
+        except ValueError as exc:
+            print(str(exc), file=sys.stderr)
+            return 1
+
+    summary = {
+        "ok": True,
+        "input": str(input_path),
+        "output": str(output_path),
+        "files_processed": len(summaries),
+        "records_seen": sum(item["records_seen"] for item in summaries),
+        "queue_operations_dropped": sum(item["queue_operations_dropped"] for item in summaries),
+        "channel_messages_flattened": sum(item["channel_messages_flattened"] for item in summaries),
+        "per_file": summaries,
+    }
     print(json.dumps(summary))
     return 0