theslopmachine 0.6.2 → 0.7.0

package/assets/slopmachine/scaffold-playbooks/web-default.md

@@ -0,0 +1,96 @@
+# Web Default Scaffold Playbook
+
+Use this playbook for web frontend, backend, or fullstack requests unless the prompt or existing repo clearly requires a different runtime model.
+
+## Goal
+
+Create a simple web baseline that:
+
+- uses the requested framework or safest default bootstrap path
+- runs through one honest primary runtime contract
+- exposes one portable broad test command
+- wires required baseline technologies without starting product-specific feature work
+
+## Runtime contract
+
+- required runtime command: `docker compose up --build`
+- required broad test command: `./run_tests.sh`
+- both commands must be real and working
+
+## Bootstrap rule
+
+- use the official or best-known bootstrap command for the requested web framework
+- if the prompt leaves the framework open, choose the safest maintained default for the requested surface
+- after bootstrap, adapt only enough to make the runtime, test path, config path, and README honest
+
+## Required scripts
+
+- `./run_tests.sh`
+- `./init_db.sh` when the project has database dependencies
+
+## Safe defaults
+
+- no `.env` files in the repo
+- no hardcoded secrets
+- Docker runtime is mandatory for web delivery
+- only app-facing services exposed to host by default
+- internal services kept off host ports unless genuinely needed
+- `COMPOSE_PROJECT_NAME` namespaced cleanly when Docker is used
+
+## Baseline structure
+
+- app/runtime entrypoints are real
+- test tooling is installed
+- config flow is explicit
+- logging/validation baseline exists where the stack obviously needs it
+- repo `README.md` is honest from day one
+
+## `./run_tests.sh`
+
+For the default Docker-first model, `./run_tests.sh` should own the portable broad path and remain runnable on a clean Linux machine with Docker and curl.
+
+Typical baseline coverage:
+
+- install/build health
+- lint or typecheck when applicable
+- one or more real baseline tests
+- app or API smoke-level verification
+
+## Minimal real test floor
+
+At scaffold, include at least:
+
+- one real unit or route/component test
+- one real smoke-level proof that the chosen framework wiring works
+- one real broad-path build/test invocation in `./run_tests.sh`
+
+Do not leave the broad path mostly empty.
+
+## README floor
+
+`README.md` must already state:
+
+- scaffold status versus implemented scope
+- required Docker command: `docker compose up --build`
+- broad test command
+- main repo layout
+- any mock/local-only or scaffold honesty boundaries
+
+## Common pitfalls
+
+- pretending a non-Docker web runtime is acceptable as the final baseline contract
+- checked-in `.env` files
+- hardcoded secret literals in Compose or startup scripts
+- exposing every service port to host by default
+- generating a giant scaffold with almost no real tests
+
+## Acceptance checklist
+
+Scaffold is acceptable when:
+
+- `docker compose up --build` works
+- `./run_tests.sh` works
+- required baseline technologies are wired
+- minimal real tests exist
+- README is honest
+- no `.env` or hardcoded secret residue exists

package/assets/slopmachine/templates/AGENTS.md

@@ -16,6 +16,28 @@ This file is the repo-local engineering rulebook for `slopmachine` projects.
 - Work in meaningful vertical slices.
 - Do not call work complete while it is still shaky.
 - 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.
+- When the product has meaningful workflow state, define or confirm the relevant state machine before treating the flow as implemented.
+- Keep a concrete out-of-scope boundary in mind so you do not overbuild speculative features.
+- Do not introduce convenience-based `v1` scope cuts, role simplifications, or workflow omissions unless they were explicitly authorized.
+- When backend or fullstack API endpoints are added or changed, prefer real HTTP tests for the exact `METHOD + PATH` over controller or service bypasses when practical.
+- If mocked HTTP tests or unit-only tests still exist for an API surface, do not overstate them as equivalent to true no-mock endpoint coverage.
+
+## Requirements Fidelity
+
+- 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 the feature depends on business rules, make those rules traceable in code, tests, and `README.md` rather than leaving them implicit.
+
+## Architecture Rules
+
+- For backend or fullstack projects, route configuration through a central config module instead of scattering direct environment reads through business logic.
+- Keep database operations, business logic, transport layers, and UI surfaces separated clearly enough for static review.
+- Use a shared logging path and shared validation/error-normalization path when the project is large enough for those concerns to matter.
+- When a third-party service is required but real integration is not explicitly demanded, prefer an internal stub or adaptor boundary over shipping brittle real credentials or uncontrolled external dependencies.
+- If a feature requires auth or privileged access, enforce it across route, controller or handler, and object scope where applicable.
 
 ## Runtime And Verification
 
@@ -26,8 +48,9 @@ This file is the repo-local engineering rulebook for `slopmachine` projects.
 - During ordinary development slices, do not run Docker runtime commands, browser E2E, Playwright, full test suites, or `./run_tests.sh`.
 - Use targeted local tests during ordinary development slices and leave browser E2E plus broad-gate commands for later comprehensive verification.
 - When API tests are material, make them hit real endpoints and print simple useful response evidence such as status codes and message/body summaries.
-- For web projects, default the runtime contract to `docker compose up --build` unless the prompt or existing repository clearly dictates another model.
-- When `docker compose up --build` is not the runtime contract, provide `./run_app.sh` as the single primary runtime wrapper.
+- For web projects, require the runtime contract to be `docker compose up --build`.
+- For Android, mobile, desktop, and iOS-targeted projects, also require a meaningful `docker compose up --build` command even when platform-specific runtime proof differs from web semantics.
+- For non-web projects, `./run_app.sh` may exist as a helper wrapper, but it does not replace the required Docker command.
 - If the project has database dependencies, keep `./init_db.sh` as the only project-standard database initialization path.
 
 ## Documentation Rules
@@ -35,17 +58,21 @@ This file is the repo-local engineering rulebook for `slopmachine` projects.
 - Keep `README.md` accurate.
 - The README must explain what the project is, what it does, how to run it, how to test it, the main repo contents, and any important information a new developer needs immediately.
 - The README must also explain the delivered architecture and major implementation structure clearly enough for review and handoff.
-- The README must clearly document whether the primary runtime command is `docker compose up --build` or `./run_app.sh`.
+- The README must include project type near the top, startup instructions, access method, verification method, and demo credentials for every role or the exact statement `No authentication required`.
+- The README must clearly document the required Docker command `docker compose up --build` and any additional helper runtime wrapper such as `./run_app.sh` when present.
 - The README must clearly document `./run_tests.sh` as the broad test command.
+- For backend, fullstack, and web projects, the README should also contain the exact legacy compatibility string `docker-compose up` somewhere in startup guidance without replacing the canonical runtime contract.
 - The README must stand on its own for basic codebase use.
 - Keep `README.md` as the only documentation file inside the repo unless the user explicitly asks for something else.
 - Treat `README.md` as the primary documentation surface inside the repo.
 - The repo should be statically reviewable by a fresh reviewer: entry points, routes, config, test commands, and major module boundaries should be traceable from repository artifacts.
+- The README should name the important actors, the main success paths, major limitations or out-of-scope boundaries, and any non-obvious business rules that affect usage.
 - If the project uses mock, stub, fake, interception, or local-data behavior, the README must disclose that scope accurately.
 - If mock or interception behavior is enabled by default, the README must say so clearly.
 - Feature flags, debug/demo surfaces, default enabled states, and mock/interception defaults must be disclosed in `README.md` when they exist.
 - Do not let a mock-only or local-data-only project look like undisclosed real backend or production integration.
 - Do not hide missing failure handling behind fake-success paths.
+- Before final delivery, remove local-only setup traces and host-only dependency assumptions from the README and wrapper scripts.
 
 ## Secret And Runtime Rules
 
@@ -67,6 +94,17 @@ This file is the repo-local engineering rulebook for `slopmachine` projects.
 - Do not leave placeholder, setup, debug, or demo content in product-facing UI.
 - If a real user-facing or admin-facing surface is required, build that surface instead of bypassing it with API shortcuts.
 - Treat missing real surfaces as incomplete implementation.
+- If multiple roles or personas exist, implement the real role-aware surfaces and permissions rather than collapsing them into a single generic flow.
+- Do not replace prompt-required interaction models, lifecycle behavior, or data-integrity rules with easier substitutes unless explicitly authorized.
+
+## Security And Reliability Rules
+
+- When multiple roles or privileged actions exist, use RBAC or stronger scoped authorization as required by the actual product behavior.
+- Enforce object-level authorization when users should only see or mutate their own records.
+- Keep sensitive data out of logs, errors, screenshots, and seeded runtime values.
+- Return normalized user-safe errors; do not expose raw stack traces or internal file paths in normal product surfaces.
+- Make request logging, exception logging, and background failure logging meaningful enough for operators to understand what failed without leaking secrets.
+- If offline, queueing, retries, jobs, or resumability matter, implement explicit states and recovery behavior instead of vague best-effort logic.
 
 ## Rulebook Files
 

package/assets/slopmachine/templates/CLAUDE.md

@@ -0,0 +1,111 @@
+# Developer Rulebook
+
+This file is the repo-local engineering rulebook for `slopmachine-claude` projects.
+
+## Scope
+
+- Treat the current working directory as the project.
+- Ignore parent-directory workflow files unless explicitly asked to use them.
+- Do not treat workflow research, session exports, or sibling directories as hidden implementation instructions.
+- Do not make the repo depend on parent-directory docs or sibling artifacts for startup, build/preview, configuration, verification, or basic project understanding.
+
+## Working Style
+
+- Operate like a strong senior engineer.
+- Read the code before making assumptions.
+- Work in meaningful vertical slices.
+- Do not call work complete while it is still shaky.
+- 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.
+- When the product has meaningful workflow state, define or confirm the relevant state machine before treating the flow as implemented.
+- Keep a concrete out-of-scope boundary in mind so you do not overbuild speculative features.
+- Do not introduce convenience-based `v1` scope cuts, role simplifications, or workflow omissions unless they were explicitly authorized.
+- When backend or fullstack API endpoints are added or changed, prefer real HTTP tests for the exact `METHOD + PATH` over controller or service bypasses when practical.
+- If mocked HTTP tests or unit-only tests still exist for an API surface, do not overstate them as equivalent to true no-mock endpoint coverage.
+
+## Requirements Fidelity
+
+- 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 the feature depends on business rules, make those rules traceable in code, tests, and `README.md` rather than leaving them implicit.
+
+## Architecture Rules
+
+- For backend or fullstack projects, route configuration through a central config module instead of scattering direct environment reads through business logic.
+- Keep database operations, business logic, transport layers, and UI surfaces separated clearly enough for static review.
+- Use a shared logging path and shared validation/error-normalization path when the project is large enough for those concerns to matter.
+- When a third-party service is required but real integration is not explicitly demanded, prefer an internal stub or adaptor boundary over shipping brittle real credentials or uncontrolled external dependencies.
+- If a feature requires auth or privileged access, enforce it across route, controller or handler, and object scope where applicable.
+
+## Runtime And Verification
+
+- Keep one primary documented runtime command and one primary broad test command: `./run_tests.sh`.
+- Follow the original prompt and existing repository first for the runtime stack.
+- Prefer the fastest meaningful local verification for the changed area during ordinary iteration.
+- Do not rerun broad runtime/test commands on every small change.
+- During ordinary development slices, do not run Docker runtime commands, browser E2E, Playwright, full test suites, or `./run_tests.sh`.
+- Use targeted local tests during ordinary development slices and leave browser E2E plus broad-gate commands for later comprehensive verification.
+- When API tests are material, make them hit real endpoints and print simple useful response evidence such as status codes and message/body summaries.
+- For web projects, require the runtime contract to be `docker compose up --build`.
+- For Android, mobile, desktop, and iOS-targeted projects, also require a meaningful `docker compose up --build` command even when platform-specific runtime proof differs from web semantics.
+- For non-web projects, `./run_app.sh` may exist as a helper wrapper, but it does not replace the required Docker command.
+- If the project has database dependencies, keep `./init_db.sh` as the only project-standard database initialization path.
+
+## Documentation Rules
+
+- Keep `README.md` accurate.
+- The README must explain what the project is, what it does, how to run it, how to test it, the main repo contents, and any important information a new developer needs immediately.
+- The README must also explain the delivered architecture and major implementation structure clearly enough for review and handoff.
+- The README must include project type near the top, startup instructions, access method, verification method, and demo credentials for every role or the exact statement `No authentication required`.
+- The README must clearly document the required Docker command `docker compose up --build` and any additional helper runtime wrapper such as `./run_app.sh` when present.
+- The README must clearly document `./run_tests.sh` as the broad test command.
+- For backend, fullstack, and web projects, the README should also contain the exact legacy compatibility string `docker-compose up` somewhere in startup guidance without replacing the canonical runtime contract.
+- The README must stand on its own for basic codebase use.
+- Keep `README.md` as the only documentation file inside the repo unless the user explicitly asks for something else.
+- Treat `README.md` as the primary documentation surface inside the repo.
+- The repo should be statically reviewable by a fresh reviewer: entry points, routes, config, test commands, and major module boundaries should be traceable from repository artifacts.
+- The README should name the important actors, the main success paths, major limitations or out-of-scope boundaries, and any non-obvious business rules that affect usage.
+- If the project uses mock, stub, fake, interception, or local-data behavior, the README must disclose that scope accurately.
+- If mock or interception behavior is enabled by default, the README must say so clearly.
+- Feature flags, debug/demo surfaces, default enabled states, and mock/interception defaults must be disclosed in `README.md` when they exist.
+- Do not let a mock-only or local-data-only project look like undisclosed real backend or production integration.
+- Do not hide missing failure handling behind fake-success paths.
+- Before final delivery, remove local-only setup traces and host-only dependency assumptions from the README and wrapper scripts.
+
+## Secret And Runtime Rules
+
+- Do not create or keep `.env` files anywhere in the repo.
+- Do not rely on `.env`, `.env.local`, `.env.example`, or similar files for project startup.
+- Do not hardcode secrets.
+- If runtime env-file format is required, generate it ephemerally and do not commit or package it.
+- Do not hardcode database connection values or database bootstrap values anywhere in the repo.
+- For Dockerized web projects, `docker compose up --build` should work without any manual `export ...` step.
+- For Dockerized web projects, prefer a dev-only runtime bootstrap script that is invoked automatically by the Docker startup path to generate or inject local-development runtime values.
+- That bootstrap path must not use checked-in `.env` files or hardcoded runtime values.
+- Do not pre-seed secret literals in Compose files, config files, Dockerfiles, or startup scripts even if they are labeled dev-only, test-only, or non-production.
+- `./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.
+
+## Product Integrity Rules
+
+- Do not leave placeholder, setup, debug, or demo content in product-facing UI.
+- If a real user-facing or admin-facing surface is required, build that surface instead of bypassing it with API shortcuts.
+- Treat missing real surfaces as incomplete implementation.
+- If multiple roles or personas exist, implement the real role-aware surfaces and permissions rather than collapsing them into a single generic flow.
+- Do not replace prompt-required interaction models, lifecycle behavior, or data-integrity rules with easier substitutes unless explicitly authorized.
+
+## Security And Reliability Rules
+
+- When multiple roles or privileged actions exist, use RBAC or stronger scoped authorization as required by the actual product behavior.
+- Enforce object-level authorization when users should only see or mutate their own records.
+- Keep sensitive data out of logs, errors, screenshots, and seeded runtime values.
+- Return normalized user-safe errors; do not expose raw stack traces or internal file paths in normal product surfaces.
+- Make request logging, exception logging, and background failure logging meaningful enough for operators to understand what failed without leaking secrets.
+- If offline, queueing, retries, jobs, or resumability matter, implement explicit states and recovery behavior instead of vague best-effort logic.
+
+## Rulebook Files
+
+- Do not edit `CLAUDE.md` or other workflow/rulebook files unless explicitly asked.

package/assets/slopmachine/utils/claude_create_session.mjs

@@ -22,6 +22,7 @@ try {
       ok: false,
       code: failure?.code || 'claude_create_failed',
       msg: failure?.msg || 'claude_create_failed',
+      detail: failure?.detail || null,
       sid: failure?.sid || null,
     }
     await writeJsonIfNeeded(argv['result-file'], resultPayload)

package/assets/slopmachine/utils/claude_live_channel.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+
+import http from 'node:http'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import { parseArgs, writeJsonIfNeeded } from './claude_worker_common.mjs'
+
+const argv = parseArgs(process.argv.slice(2))
+const port = Number.parseInt(argv.port, 10)
+const token = argv.token
+const stateFile = argv['state-file']
+const logFile = argv['log-file']
+const channelName = argv['channel-name'] || 'slopmachine-channel'
+const lane = argv.lane || 'lane'
+
+const instructions = 'Messages arrive as <channel source="slopmachine" ...>. Treat them as ordinary inbound work requests and respond normally in the current Claude session. Do not look for or use any reply tool for this channel.'
+
+let buffer = ''
+let readyForNotifications = false
+let negotiatedProtocolVersion = '2025-11-25'
+
+function writeMessage(message) {
+  process.stdout.write(`${JSON.stringify(message)}\n`)
+}
+
+async function appendLog(record) {
+  const line = `${JSON.stringify({ ts: new Date().toISOString(), ...record })}\n`
+  await fs.mkdir(path.dirname(logFile), { recursive: true })
+  await fs.appendFile(logFile, line, 'utf8')
+}
+
+async function updateState(patch) {
+  await writeJsonIfNeeded(stateFile, {
+    channel_name: channelName,
+    lane,
+    pid: process.pid,
+    port,
+    ready_for_notifications: readyForNotifications,
+    protocol_version: negotiatedProtocolVersion,
+    updated_at: new Date().toISOString(),
+    ...patch,
+  })
+}
+
+async function handleRpc(message) {
+  if (message.method === 'initialize' && Object.prototype.hasOwnProperty.call(message, 'id')) {
+    negotiatedProtocolVersion = message.params?.protocolVersion || negotiatedProtocolVersion
+    await updateState({ status: 'initialized' })
+    writeMessage({
+      jsonrpc: '2.0',
+      id: message.id,
+      result: {
+        protocolVersion: negotiatedProtocolVersion,
+        capabilities: {
+          experimental: {
+            'claude/channel': {},
+          },
+        },
+        serverInfo: {
+          name: channelName,
+          version: '0.1.0',
+        },
+        instructions,
+      },
+    })
+    await appendLog({ type: 'initialize', message })
+    return
+  }
+
+  if (message.method === 'notifications/initialized') {
+    readyForNotifications = true
+    await updateState({ status: 'ready' })
+    await appendLog({ type: 'initialized' })
+    return
+  }
+
+  if (message.method === 'ping' && Object.prototype.hasOwnProperty.call(message, 'id')) {
+    writeMessage({ jsonrpc: '2.0', id: message.id, result: {} })
+    return
+  }
+
+  if (Object.prototype.hasOwnProperty.call(message, 'id')) {
+    writeMessage({
+      jsonrpc: '2.0',
+      id: message.id,
+      error: {
+        code: -32601,
+        message: `Method not found: ${message.method}`,
+      },
+    })
+  }
+}
+
+process.stdin.setEncoding('utf8')
+process.stdin.on('data', async (chunk) => {
+  buffer += chunk
+  while (true) {
+    const newlineIndex = buffer.indexOf('\n')
+    if (newlineIndex === -1) {
+      break
+    }
+    const line = buffer.slice(0, newlineIndex).trim()
+    buffer = buffer.slice(newlineIndex + 1)
+    if (!line) {
+      continue
+    }
+    try {
+      const message = JSON.parse(line)
+      await handleRpc(message)
+    } catch (error) {
+      await updateState({ status: 'failed', last_error: error instanceof Error ? error.message : String(error) })
+      await appendLog({ type: 'rpc_error', error: error instanceof Error ? error.message : String(error) })
+    }
+  }
+})
+
+process.stdin.on('end', async () => {
+  await updateState({ status: 'closed' })
+  process.exit(0)
+})
+
+await updateState({ status: 'starting' })
+
+const server = http.createServer(async (request, response) => {
+  if (request.method !== 'POST') {
+    response.writeHead(404)
+    response.end('not found')
+    return
+  }
+
+  if (request.headers['x-bridge-token'] !== token) {
+    response.writeHead(403)
+    response.end('forbidden')
+    return
+  }
+
+  if (!readyForNotifications) {
+    response.writeHead(503)
+    response.end('channel_not_ready')
+    return
+  }
+
+  let body = ''
+  for await (const chunk of request) {
+    body += chunk.toString()
+  }
+
+  const turnId = String(request.headers['x-turn-id'] || '').trim()
+  const notification = {
+    jsonrpc: '2.0',
+    method: 'notifications/claude/channel',
+    params: {
+      content: body,
+      meta: {
+        lane,
+        turn_id: turnId,
+        method: request.method,
+      },
+    },
+  }
+
+  writeMessage(notification)
+  await updateState({ status: 'ready', last_message_at: new Date().toISOString(), last_turn_id: turnId || null })
+  await appendLog({ type: 'notification', turn_id: turnId || null, body })
+  response.writeHead(200)
+  response.end('ok')
+})
+
+server.listen(port, '127.0.0.1', async () => {
+  await updateState({ status: 'listening' })
+  await appendLog({ type: 'listening' })
+})
+
+async function shutdown(code) {
+  await updateState({ status: 'closed' })
+  server.close(() => {
+    process.exit(code)
+  })
+}
+
+process.on('SIGINT', () => {
+  void shutdown(0)
+})
+
+process.on('SIGTERM', () => {
+  void shutdown(0)
+})