@dna113p/machines 0.3.3 → 0.3.5

package/docs/integrations.md

@@ -209,14 +209,27 @@ directory is created by the first write, as `0700`, and each file is `0600`:
 `status` is `running`, `waiting`, `completed`, or `failed`. `state` is the current
 state as a string (JSON for a nested state). `agent` is present while an Agent
 state has reported its identity, and `error` after a failure. `owner` is
-`MACHINES_RUN_OWNER` when set, otherwise `CLAUDE_CODE_SESSION_ID`, otherwise
-absent. `stateSince` is when the current state was entered. `label` is the first
+`MACHINES_RUN_OWNER` when set, otherwise the session id the coding agent gives
+the commands it starts (`CLAUDE_CODE_SESSION_ID`, then `CODEX_THREAD_ID`, then
+`PI_SESSION_ID`), otherwise absent; see
+[how a host names its session](#drawing-your-own-widgets). `stateSince` is when
+the current state was entered. `label` is the first
 line of `MACHINES_RUN_LABEL` (at most 160 characters) when a launcher sets it to
 say what the run is for, such as a ticket id and title; it is the launcher's
 choice to publish that text. `machine run` exports its run id as
 `MACHINES_RUN_PARENT`, so a Machine started by one of its Operations or Agents
 records that id as `parent`; the status line shows only top-level runs.
 
+`graph` is the Machine's states and transitions, published once when the run
+starts: `initial`, `states` (each with an `id`, a `kind` of `agent`, `human`,
+`operation`, `final`, `group`, or `state`, an Agent's `role`, and the `parent`
+group of a nested state), and `edges` (`from`, `to`, and the `event` taken). Ids
+are state paths joined by dots, so a nested state is `review.round`. A Machine
+with more than 300 states or 1000 transitions publishes no graph. `trail` is the
+states the run entered, oldest first, each with the time it was entered, as the
+same dotted paths; it keeps the latest 200. Both are additions to version 2:
+a reader that does not know them ignores them.
+
 A run hosted through `startMachineHost` from `@dna113p/machines/host` publishes
 the same record when its host asks with `publishRunStatus: true` and
 publication is on in the hosting process, as a daemon that runs tickets does. A
@@ -279,8 +292,17 @@ taken a response from its inbox, its record lists that delivery's id in
 id stays listed for at least a minute, however many responses the run takes
 after it, and never contains the response.
 
-Machine input, Machine output, and Human responses are never recorded. A Human
-prompt and its choices are written to the `0600` file while the request is
+When a run finishes, `machine run`, the MCP server, and a host that asks for
+publication all three publish the optional `note` field if the final output
+is an object with a non-empty string `summary`. It is trimmed and limited to
+2000 characters, including a trailing `…` when shortened
+at a word boundary (a single word longer than the limit is cut to fit).
+Empty or whitespace-only summaries leave the field absent. The whole note,
+including its line breaks, is available in JSON. This optional field keeps
+`schemaVersion` at 2; readers should accept records with or without it.
+
+Machine input, output fields other than that summary, and Human responses are
+never recorded. A Human prompt and its choices are written to the `0600` file while the request is
 waiting. The standard directory is private to you; one you name instead should
 be a directory only you can read and write.
 
@@ -326,10 +348,13 @@ waiting run its prompt, request id, and choices (tab-separated when its
 output is not a terminal). A run's label follows as a fifth column when it has
 one, and a sixth says `watched` for a run this session
 [watches](#watching-other-runs). It lists the running and waiting runs of every
-session and project. `--all`, with or without `--json`, lists every published
+session and project; `--for` narrows it to
+[what one viewer shows](#drawing-your-own-widgets). `--all`, with or without `--json`, lists every published
 run: also the ones whose records remain after they finished, as `completed` or
 `failed`, or after their process disappeared, as `lost` (in JSON such a record
-keeps the status it last published). A run answered through its host shows
+keeps the status it last published). For a completed or failed run, the first
+non-empty line of its note is printed beneath the row; `--json` includes the
+whole note. A run answered through its host shows
 `answered through its host` in place of a request id:
 
 ```text
@@ -440,13 +465,43 @@ for the same time, so the status line must run where it can see that process.
 Set `NO_COLOR` (to any value, even an empty one) for plain text and `COLUMNS`
 to change the 120-column truncation.
 
+### Watching runs in a browser
+
+```bash
+machine ui [--port <port>] [--project <dir>]
+```
+
+serves a live page on `127.0.0.1` (port 4777, or the next free one) of every
+published run: what is waiting on you, what is running, and what finished, with
+each run's Machine drawn as a graph, its current state marked, the states and
+transitions it has taken counted, and the path it took so far. A waiting run
+that takes outside responses is answered from the page, as `machine respond`
+answers it; a run answered through its host, such as a daemon's, names where to
+answer it instead. The page loads nothing from outside, accepts requests only
+under its own host name, and answers a run only with a token it was served.
+
+A project adds its own panels beside the runs, such as its tickets or pull
+requests, in `.machines/ui.json` in the project (the nearest directory above the
+current one that has a `.machines` directory, or `--project`):
+
+```json
+{ "panels": [{ "title": "Tickets", "command": ["node", "scripts/ui-panels.mjs", "tickets"], "refreshSeconds": 10 }] }
+```
+
+Each command runs in the project directory every `refreshSeconds` (10 by
+default) and prints one JSON object: `{ "summary"?, "items": [{ "text",
+"detail"?, "status"?, "href"?, "at"? }] }`, where `status` is `ok`, `warn`,
+`bad`, `active`, or `idle`, `href` is a web link, and `at` a time. Commands are
+project code, trusted as `.machines/` Machines are; a command that fails or
+prints something else shows its error in its panel.
+
 ### Watching other runs
 
 A session can pull in runs it did not start: a ticket that a daemon runs, or a
 run started by another session or under another project. Nothing is configured.
 The session is identified as a run's `owner` is, by `MACHINES_RUN_OWNER` and
-otherwise `CLAUDE_CODE_SESSION_ID`, so an agent inside Claude Code only runs the
-command.
+otherwise by the session id its coding agent gives it, so an agent inside Claude
+Code, Codex, or Pi only runs the command.
 
 ```bash
 machine runs                   # running and waiting runs, with their labels
@@ -455,6 +510,7 @@ machine watch org-9            # runs whose id or label starts with org-9
 machine watch --dir ../other   # runs working in that directory or below it
 machine watch                  # what this session watches, and the published runs each entry matches now
 machine unwatch org-9          # also: unwatch --dir <path>, unwatch --all
+machine watch --for <session> org-9   # the same commands for another session's list
 ```
 
 - `machine watch <text>` names every top-level run whose id starts with the
@@ -467,7 +523,12 @@ machine unwatch org-9          # also: unwatch --dir <path>, unwatch --all
 - An entry keeps matching runs that start later, so a ticket can be watched
   before its run exists. `machine watch` lists a matched run for as long as its
   record remains, with the status `machine runs --all` gives it, so it also
-  says how a watched run ended.
+  says how a watched run ended, with the first non-empty line of its note
+  beneath the row when present.
+- `--for <session>`, first, makes `machine watch` and `machine unwatch` read
+  and change the list of the session it names instead of this process's own.
+  A program that draws [its own widgets](#drawing-your-own-widgets) for a
+  viewer manages that viewer's list this way, without setting a variable.
 
 A watched run is shown even when another session owns it or it works outside
 the project. Everything else is as for any run: sub-runs stay hidden, a run is
@@ -486,7 +547,122 @@ session id that is not safe as a file name is refused. Removing the last entry
 removes the file, and writing a list or starting a run removes other sessions'
 lists that have not changed for 30 days. A missing, unreadable, or malformed list watches
 nothing; it is never an error on the status line. The commands fail with a
-message when publication is off or when no variable names the session.
+message when publication is off or when nothing names the session.
+
+### Drawing your own widgets
+
+Any application can show Machine runs in its own way from what is already
+published: an extension for Codex or Pi, a web app, an editor panel. The Claude
+Code status line above is one such consumer. Nothing is configured and nothing
+new runs; there are three ways to read the same directory:
+
+| Read with | You get |
+| --- | --- |
+| `machine runs --for <session> --json` | The runs one viewer shows, each ready to draw |
+| `@dna113p/machines/run-status` | The same rule and the readers, in your own process |
+| The files | The [records](#run-status-for-host-status-lines) and [watch lists](#watching-other-runs) themselves; the rule is then yours to apply |
+
+A viewer is one surface that shows runs: a session of a coding agent, a browser
+tab, a status line. It is named by a session id and may have a project
+directory. The rule that decides what it shows is the status line's:
+
+- only top-level runs: a run started from inside another Machine is never shown;
+- the runs its session owns, unowned runs working in its project directory or
+  below it, and the runs its session [watches](#watching-other-runs), whoever
+  owns them;
+- a run recorded as running or waiting whose process is gone is `lost`;
+- a finished or lost run stays for 30 seconds and then drops out;
+- each run once, the ones that can still change first, then the most recently
+  updated. Runs updated in the same millisecond keep the order they were read
+  in from the directory, for the command, the library, and the status line
+  alike.
+
+Both ways below take a snapshot. Read again to refresh, as the status line does
+every few seconds, and read where the runs' processes can be seen, or every run
+looks `lost`.
+
+```bash
+machine runs --for "$SESSION" --project "$PWD" --json   # what that viewer shows
+machine runs --for --json                               # for this process's own session
+machine runs --for "$SESSION" --all                     # as text, and with older finished and lost runs
+machine watch --for "$SESSION" org-9                    # change what that viewer watches
+```
+
+`--for` takes the viewer's session id; with no id after it, the viewer is this
+process's own session, and the command fails when nothing names one.
+`--project` is the viewer's project directory, compared as an absolute path;
+without it only owned and watched runs are selected. `--all` also keeps the
+finished and lost runs that the 30 seconds would have dropped, for as long as
+their records remain. Without `--json` the runs are printed in the columns of
+`machine runs`. Without `--for`, `machine runs` is unchanged: every session's
+running and waiting runs, as plain records.
+
+Each item is the published record with three additions:
+
+```json
+{
+  "schemaVersion": 2, "id": "1a2b3c4d-…", "pid": 4242, "owner": "<session id>",
+  "machine": "release", "path": "/work/.machines/release.ts", "cwd": "/work",
+  "status": "waiting", "state": "approve",
+  "human": { "prompt": "Publish version 0.4.0?", "requestId": "9f8e7d6c-…", "choices": ["publish", "hold"] },
+  "startedAt": "2026-03-04T05:06:07.000Z", "updatedAt": "2026-03-04T05:08:12.000Z",
+  "shown": "owned",
+  "answer": { "via": "respond", "runId": "1a2b3c4d-…", "requestId": "9f8e7d6c-…" }
+}
+```
+
+- `status` is the effective one: what the record says, or `lost`.
+- `shown` says why the viewer shows the run: `owned`, `project`, or `watched`,
+  the first of them that holds.
+- `answer` is present while the run waits on a Human request that something
+  can answer. `"via": "respond"` carries the two ids for
+  `machine respond <runId> <requestId> <response>`; `"via": "host"` means only
+  the program hosting the run can answer it, so a widget shows the prompt and
+  offers no input. `human` still has the prompt, choices, and suggestions.
+
+Nothing is added for presentation: no colour, layout, or shortening, and no
+limit on how many runs are returned. Recorded text is the run's own, so escape
+it for your surface as the status line strips control characters.
+
+The library gives the same answer without starting a process:
+
+```ts
+import {
+  readRunStatuses, readRunWatches, runStatusDirectory, runsForViewer,
+} from "@dna113p/machines/run-status";
+
+const directory = runStatusDirectory(); // undefined while publication is off
+const runs = directory === undefined ? [] : runsForViewer(readRunStatuses(directory), {
+  sessionId,
+  projectDir: "/work/project",
+  watches: readRunWatches(directory, sessionId),
+});
+for (const run of runs) draw(run.label ?? run.id, run.status, run.shown, run.answer);
+```
+
+`runsForViewer(records, viewer, options)` is pure apart from probing whether
+each process is alive; `options` takes `now`, `all`, and an `isAlive` of your
+own. The module also exports `runSessionId`, the types of a record, a watch, a
+viewer, and an item, and `settledRunVisibleMilliseconds`. It only reads:
+publishing stays with the runtime, and a viewer's watch list is changed with
+`machine watch --for`.
+
+**Naming the session.** A viewer shows the runs whose `owner` is its session
+id, so the host and the runs it starts must agree on that id. Any host can set
+`MACHINES_RUN_OWNER` in the environment of the commands it starts and pass the
+same value to `--for`; the id may use letters, digits, `.`, `_`, and `-`. Where
+it is not set, the id is the one the coding agent already gives its commands:
+
+| Host | Variable | Given to |
+| --- | --- | --- |
+| Any | `MACHINES_RUN_OWNER` | Whatever the host starts with it set; takes precedence |
+| Claude Code | `CLAUDE_CODE_SESSION_ID` | The commands a session runs; also the `session_id` its status line receives |
+| Codex | `CODEX_THREAD_ID` | The commands a thread runs |
+| Pi | `PI_SESSION_ID` | The commands its `bash` and `powershell` tools run, not `!` commands typed by the user |
+
+The first one that is set names the session, in that order. A run started from
+inside one of these agents is therefore owned by that session: it is shown
+there, and in another session only when that session watches it.
 
 ## Troubleshooting
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dna113p/machines",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Reusable workflows coordinating agents, local operations, and human decisions.",
   "license": "MIT",
   "repository": {
@@ -20,29 +20,96 @@
   },
   "types": "./dist/src/index.d.ts",
   "exports": {
-    ".": { "types": "./dist/src/index.d.ts", "import": "./dist/src/index.js" },
-    "./acp": { "types": "./dist/src/acp.d.ts", "import": "./dist/src/acp.js" },
-    "./agy": { "types": "./dist/src/agy.d.ts", "import": "./dist/src/agy.js" },
-    "./chatgpt-web": { "types": "./dist/src/chatgpt-web.d.ts", "import": "./dist/src/chatgpt-web.js" },
-    "./claude": { "types": "./dist/src/claude.d.ts", "import": "./dist/src/claude.js" },
-    "./conversation": { "types": "./dist/src/conversation.d.ts", "import": "./dist/src/conversation.js" },
-    "./codex": { "types": "./dist/src/codex.d.ts", "import": "./dist/src/codex.js" },
-    "./deepseek": { "types": "./dist/src/deepseek.d.ts", "import": "./dist/src/deepseek.js" },
-    "./decision": { "types": "./dist/src/decision.d.ts", "import": "./dist/src/decision.js" },
-    "./jev": { "types": "./dist/src/jev.d.ts", "import": "./dist/src/jev.js" },
-    "./openrouter": { "types": "./dist/src/openrouter.d.ts", "import": "./dist/src/openrouter.js" },
-    "./laya": { "types": "./dist/src/laya.d.ts", "import": "./dist/src/laya.js" },
-    "./von": { "types": "./dist/src/von.d.ts", "import": "./dist/src/von.js" },
-    "./host": { "types": "./dist/src/host.d.ts", "import": "./dist/src/host.js" },
-    "./launcher": { "types": "./dist/src/launcher.d.ts", "import": "./dist/src/launcher.js" },
-    "./mcp": { "types": "./dist/mcp/server.d.ts", "import": "./dist/mcp/server.js" },
-    "./pi-extension": { "types": "./dist/pi-extension/index.d.ts", "import": "./dist/pi-extension/index.js" }
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    },
+    "./acp": {
+      "types": "./dist/src/acp.d.ts",
+      "import": "./dist/src/acp.js"
+    },
+    "./agy": {
+      "types": "./dist/src/agy.d.ts",
+      "import": "./dist/src/agy.js"
+    },
+    "./chatgpt-web": {
+      "types": "./dist/src/chatgpt-web.d.ts",
+      "import": "./dist/src/chatgpt-web.js"
+    },
+    "./claude": {
+      "types": "./dist/src/claude.d.ts",
+      "import": "./dist/src/claude.js"
+    },
+    "./conversation": {
+      "types": "./dist/src/conversation.d.ts",
+      "import": "./dist/src/conversation.js"
+    },
+    "./codex": {
+      "types": "./dist/src/codex.d.ts",
+      "import": "./dist/src/codex.js"
+    },
+    "./deepseek": {
+      "types": "./dist/src/deepseek.d.ts",
+      "import": "./dist/src/deepseek.js"
+    },
+    "./decision": {
+      "types": "./dist/src/decision.d.ts",
+      "import": "./dist/src/decision.js"
+    },
+    "./jev": {
+      "types": "./dist/src/jev.d.ts",
+      "import": "./dist/src/jev.js"
+    },
+    "./openrouter": {
+      "types": "./dist/src/openrouter.d.ts",
+      "import": "./dist/src/openrouter.js"
+    },
+    "./laya": {
+      "types": "./dist/src/laya.d.ts",
+      "import": "./dist/src/laya.js"
+    },
+    "./von": {
+      "types": "./dist/src/von.d.ts",
+      "import": "./dist/src/von.js"
+    },
+    "./host": {
+      "types": "./dist/src/host.d.ts",
+      "import": "./dist/src/host.js"
+    },
+    "./launcher": {
+      "types": "./dist/src/launcher.d.ts",
+      "import": "./dist/src/launcher.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/server.d.ts",
+      "import": "./dist/mcp/server.js"
+    },
+    "./pi-extension": {
+      "types": "./dist/pi-extension/index.d.ts",
+      "import": "./dist/pi-extension/index.js"
+    },
+    "./run-status": {
+      "types": "./dist/src/run-viewer.d.ts",
+      "import": "./dist/src/run-viewer.js"
+    }
   },
-  "files": ["dist", "claude/statusline.mjs", "docs/architecture.md", "docs/authoring.md", "docs/integrations.md", "docs/local-decisions.md", "services/laya/server.py", "skills", "LICENSE", "README.md"],
+  "files": [
+    "dist",
+    "claude/statusline.mjs",
+    "docs/architecture.md",
+    "docs/authoring.md",
+    "docs/integrations.md",
+    "docs/local-decisions.md",
+    "services/laya/server.py",
+    "skills",
+    "LICENSE",
+    "README.md"
+  ],
   "scripts": {
     "build": "node scripts/build.mjs",
     "build:plugin": "npm run build && node scripts/build-plugin.mjs",
-    "check": "npm run typecheck && npm test",
+    "check": "npm run lint && npm run typecheck && npm test",
+    "lint": "oxlint --deny-warnings",
     "example": "node examples/operation.ts",
     "example:agents": "node examples/named-agents.ts",
     "example:agy": "node examples/agy.ts",
@@ -72,6 +139,7 @@
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
+    "oxlint": "^1.87.0",
     "typescript": "^7.0.2"
   }
 }

package/skills/machine-builder/SKILL.md

@@ -31,6 +31,11 @@ needs. Existing Machines and examples are starting points, not a fixed menu.
 Make consequential checks and decisions explicit in states when they need to
 control progress. Choose the complexity needed to complete the task reliably.
 
+Machine Shop is an optional starter library of common software-task Machines,
+kept in its own repository at `https://github.com/dna113p/machine-shop`. Nothing
+here requires it; clone it to try a default or adapt one, as
+[machine-project-setup](../machine-project-setup/SKILL.md) describes.
+
 Look for common task sequences and recurring manual workflows while doing the
 work. Convert them into Machines when explicit steps would improve repeatability
 or code quality. Parameterize assignment details so the workflow can serve the
@@ -82,3 +87,29 @@ Agent runners or injected Human input where possible. A successful run reaches
 the intended final state and produces the requested artifact or effect. Run real
 external work only within the user's authorized scope. Report what was verified
 and any branch that still requires a configured harness or human interaction.
+
+## Checks the Machine owns
+
+Design the workflow so these checks control progress and leave evidence for the
+next repair round or person taking over:
+
+- Run every gate, not only up to the first failure, so one repair round sees
+  all failures.
+- Keep the project's gate list in one place that every route reads.
+- For new behaviour, write tests first; have an Operation see them fail before
+  implementation, then pass after implementation.
+- After each editing Agent, run an Operation that compares the changed paths
+  against the paths the assignment allows.
+- Ask for a structured review: each acceptance criterion met or not, findings
+  tagged by severity. Let an Operation, not the reviewer's verdict word, decide
+  what happens next.
+- Match a reviewer's findings across rounds by their place in the conversation,
+  never by their wording.
+- End stuck unattended runs with work kept and a written note of what a person
+  must decide, instead of waiting in a Human state. Every stop keeps both so a later
+  run or a person can continue from them.
+- Before implementation, have a read-only Agent try to show the assignment is
+  wrong, already done, or underspecified; require options and a recommended answer
+  for each question it raises.
+- Tell editing Agents that checks they cannot run in their environment are the
+  workflow's to run, so a sandboxed Agent returns its work instead of `blocked`.

package/skills/machine-delegation/SKILL.md

@@ -62,6 +62,16 @@ Workers do not inherit this conversation. Supply the context needed to act:
 - Applicable constraints, permitted effects, and what should produce a blocked outcome.
 - A result location readable by the coordinator, and what evidence it must contain.
 
+State these five fields for each assignment:
+
+1. Its goal.
+2. The paths it may change.
+3. Its acceptance criteria.
+4. How it will be verified.
+5. What is forbidden.
+
+A field that cannot be filled means the unit is not scoped yet.
+
 Follow the selected Machine's input contract. MCP/Pi accept JSON-serializable
 input; CLI positional input is text, while `--input-file <file|->` accepts JSON.
 Keep task details in input rather than hardcoding each assignment into a new
@@ -103,6 +113,15 @@ polling continuously. Interpret the current snapshot:
 Preserve existing user authorization when answering Human requests, and surface a
 new decision when the request requires one. A desire to finish is not an answer.
 
+A `blocked` or parked run is a completed run to read, not a failure to retry blindly.
+Design stuck unattended runs to end with work kept and a written note of what a
+person must decide, instead of waiting in a Human state; every stop keeps both.
+Read the note, answer it or take it to the user, then start a fresh run from the
+kept work and note when resolved, or let a person continue from them.
+
+Tell an editing Agent that checks it cannot run in its environment are the
+workflow's to run, so a sandboxed Agent returns its work instead of `blocked`.
+
 To follow a run this session did not start, such as a ticket a daemon runs, use
 `machine watch <ticket-or-run-id>` where run status is published (`machine runs`
 lists what can be watched; `--all` adds runs that already ended). Watching only
@@ -126,3 +145,7 @@ verified. Read the report and inspect relevant changes or checks, then integrate
 the result into the user's task. If evidence is missing, treat that as incomplete
 work even if the run says `completed`. Report the useful result, any blocker, and
 artifact paths; a run ID alone is not the delegated deliverable.
+
+Read the reviewer's structured report: each acceptance criterion met or not,
+findings tagged by severity. Let an Operation, not the reviewer's verdict word,
+decide what happens next.

package/skills/machine-project-setup/SKILL.md

@@ -29,6 +29,19 @@ types, quality gates, recurring failure modes, and decisions needing a Human.
 Include domain-specific work, not just generic coding stages. Use only relevant,
 available project context; distinguish observed needs from speculative ones.
 
+Inventory the project's deterministic checks before designing any workflow, by
+class: lint, types, tests, build, and a live check that drives the real artifact
+(a packaging smoke, an install test, a CLI or service run against a scratch
+directory). Take them from the project's own scripts and CI, not from a fixed
+list, and run each once to learn its duration and that it leaves the checkout
+clean. Record the inventory in the map, naming the classes the project has no
+command for; a missing class is a finding for the owner, not something to
+invent. Put the resulting gate list in one project-owned place that every
+route reads (a configuration file the launchers load, not a copy in each
+launcher), so an Agent is held to the same gates a person runs. Where the
+project's checks stop at the first failure, prefer running every gate and
+reporting all failures at once: one repair round then sees them all.
+
 Inspect the existing orchestrator instructions and any `.machines/README.md`.
 Run `machine list` and `machine agents` in the actual work directories, or use
 `machine_list` / `machine_agents` with the correct workspace. Read candidate
@@ -95,11 +108,16 @@ instead of presenting same-model review as independent.
 
 ## Build the smallest useful set
 
-When the Machine Shop starter library is available, inspect its `docs/catalog.md`
-and candidate `defaults/` sources before rebuilding a common software process.
-Select or adapt relevant entries with the project-local installer; do not install
-the entire catalog by default. Its check commands, Agent bindings, and task inputs
-remain project-specific. Do not assume that library is globally installed.
+Machine Shop is an optional starter library of common software-task Machines:
+implementation, bug fixing, review, investigation, and model-free verification
+among them. Nothing here requires it, but it is a good set of defaults to try
+before rebuilding a common software process. It is a separate repository,
+`https://github.com/dna113p/machine-shop`, and is not installed with the runtime;
+when no checkout is present, tell the user about it or clone it to try it out.
+Read its `docs/catalog.md` and the candidate `defaults/` sources, then run one
+from source or copy selected entries with its project-local installer; do not
+install the entire catalog by default. Its check commands, Agent bindings, and
+task inputs remain project-specific.
 
 Map the major work to existing or missing workflows. Favor frequent delegation,
 important quality gates, and costly recurring mistakes. Reuse good definitions;

package/skills/machine-project-setup/references/project-workflows.md

@@ -19,6 +19,10 @@ For each major task type, record:
 - Expected final state, checks, result retrieval, and verification command.
 - Allowed effects, Human decisions, retry limits, and untested prerequisites.
 
+Record the gate inventory once, by class (lint, types, tests, build, live
+check): the command for each, where the one list that every route reads lives,
+and the classes the project has no command for.
+
 Mark deliberately direct, deferred, or blocked work with its reason. An existing
 setup may need no new Machine. Do not generate placeholders to fill categories.
 Include copyable invocations only for routes that exist. CLI positional input is