{"_id":"@antlegion/ant","_rev":"6-ef2834bb0026ec7fa5dbd75bfbd4eb7c","name":"@antlegion/ant","dist-tags":{"latest":"0.5.0"},"versions":{"0.0.1":{"name":"@antlegion/ant","version":"0.0.1","keywords":["agents","multi-agent","ai-agents","autonomous-agents","coordination","fact-bus","blackboard","stigmergy","worker","daemon","antlegion"],"author":{"name":"Carter.Yang"},"license":"MIT","_id":"@antlegion/ant@0.0.1","maintainers":[{"name":"yang9295","email":"929588562@qq.com"}],"homepage":"https://github.com/YangKGcsdms/antlegion-platform#readme","bugs":{"url":"https://github.com/YangKGcsdms/antlegion-platform/issues"},"bin":{"ant":"cli.js"},"dist":{"shasum":"d57f71564a0b3ac74c5cdc3c0114b84adee02a8e","tarball":"https://registry.npmjs.org/@antlegion/ant/-/ant-0.0.1.tgz","fileCount":4,"integrity":"sha512-hodEqDwBztGI9ebXJjY0GANfGlGj6glHV3DpTElVv84H/HL8isejNrdeiRG4Fs5QASwgA4ZTppnMUaXD0U+L4Q==","signatures":[{"sig":"MEYCIQCzi4edislMzIfTdOGx/cx0iCOUnbWKVLsed0QRgYuUjwIhAP9Sm+CBQns7tdDq7MJ3e9QZOlgV2sMwL6QoKkYhxKEB","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":4378},"type":"module","engines":{"node":">=20"},"gitHead":"cc4a71cdde749ba86da626ff8782603bf0b6cdba","_npmUser":{"name":"yang9295","email":"929588562@qq.com"},"repository":{"url":"git+https://github.com/YangKGcsdms/antlegion-platform.git","type":"git","directory":"ant"},"_npmVersion":"10.9.4","description":"Autonomous worker ants (DCUs) for the AntLegion fact bus — install one, tell it what facts to watch, and it wakes up and works. Pre-release name reservation; the runtime lands here next.","directories":{},"_nodeVersion":"22.22.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/ant_0.0.1_1786504839676_0.4768198048801877","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"@antlegion/ant","version":"0.1.0","keywords":["agents","multi-agent","ai-agents","autonomous-agents","coordination","fact-bus","blackboard","stigmergy","dcu","worker","daemon","antlegion"],"author":{"name":"Carter.Yang"},"license":"MIT","_id":"@antlegion/ant@0.1.0","maintainers":[{"name":"yang9295","email":"929588562@qq.com"}],"homepage":"https://github.com/YangKGcsdms/antlegion-platform#readme","bugs":{"url":"https://github.com/YangKGcsdms/antlegion-platform/issues"},"bin":{"ant":"dist/main.js"},"dist":{"shasum":"18a1d7a011bbeddd3c62ebd74f5b73bb08dbc748","tarball":"https://registry.npmjs.org/@antlegion/ant/-/ant-0.1.0.tgz","fileCount":49,"integrity":"sha512-nXotDcSQ0yS2fSZM/asIKybfeGu8IqaacQA5ilCcz0ozrMl5lKh2A12wrMiUbLdxEcdGMkCX2AvPqI/as4/7SA==","signatures":[{"sig":"MEUCIHMXFDeHXEVOc9QHCe1A/6YecmUryEkzDLdP431+DhsmAiEAqHOhknX/NUmap7C+NHyzwzvXgp0eRGkXLWTTO1istBA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":225498},"main":"dist/main.js","type":"module","types":"./dist/main.d.ts","engines":{"node":">=20"},"gitHead":"8d6aa8aad9ce07ab39e5b4baef242b2a96ffb644","scripts":{"req":"tsx src/main.ts req","test":"vitest run","board":"tsx src/main.ts board","build":"tsc -p tsconfig.build.json","chain":"tsx src/main.ts chain","ingestor":"tsx src/main.ts ingestor","typecheck":"tsc --noEmit","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"yang9295","email":"929588562@qq.com"},"repository":{"url":"git+https://github.com/YangKGcsdms/antlegion-platform.git","type":"git","directory":"ant"},"_npmVersion":"10.9.4","description":"Autonomous DCUs (Domain Control Units) on the AntLegion fact bus — a fleet of resident work units that poll the totally-ordered fact stream, claim work exactly-once, act, and resolve with evidence. Ships the dev-chain demo fleet + supervision board.","directories":{},"_nodeVersion":"22.22.0","dependencies":{"@antlegion/bus":"^0.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","vitest":"^3.1.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/ant_0.1.0_1786506513368_0.4707837548826219","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@antlegion/ant","version":"0.2.0","keywords":["agents","multi-agent","ai-agents","autonomous-agents","coordination","fact-bus","blackboard","stigmergy","dcu","worker","daemon","antlegion"],"author":{"name":"Carter.Yang"},"license":"MIT","_id":"@antlegion/ant@0.2.0","maintainers":[{"name":"yang9295","email":"929588562@qq.com"}],"homepage":"https://github.com/YangKGcsdms/antlegion-platform#readme","bugs":{"url":"https://github.com/YangKGcsdms/antlegion-platform/issues"},"bin":{"ant":"dist/main.js"},"dist":{"shasum":"278abf14df204b388a011bb4cf96f272c69b46ad","tarball":"https://registry.npmjs.org/@antlegion/ant/-/ant-0.2.0.tgz","fileCount":65,"integrity":"sha512-xJ5Ap+o5/EJrpeVW9Bs+mMrgzqVKRgrDhc2E71bt8wwUUwp9WHDkgomj031M+SuKNgwuuk8ftN81y/907zmvnQ==","signatures":[{"sig":"MEUCIGS/2p1sBqlV6T8hXT8H/GTl0omwV5W3JM44ND2uur4zAiEAwyEAMVyM0u8yQpC71DM8TEUqh5shF5s6KbSxeWWLTPQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":271108},"main":"dist/main.js","type":"module","types":"./dist/main.d.ts","engines":{"node":">=20"},"gitHead":"98ad25e0c1e5687525cb3d8f577bd16a6a02cd66","scripts":{"req":"tsx src/main.ts req","test":"vitest run","board":"tsx src/main.ts board","build":"tsc -p tsconfig.build.json","chain":"tsx src/main.ts chain","ingestor":"tsx src/main.ts ingestor","typecheck":"tsc --noEmit","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"yang9295","email":"929588562@qq.com"},"repository":{"url":"git+https://github.com/YangKGcsdms/antlegion-platform.git","type":"git","directory":"ant"},"_npmVersion":"10.9.4","description":"Autonomous DCUs (Domain Control Units) on the AntLegion fact bus — a fleet of resident work units that poll the totally-ordered fact stream, claim work exactly-once, act, and resolve with evidence. Ships the dev-chain demo fleet + supervision board.","directories":{},"_nodeVersion":"22.22.0","dependencies":{"@antlegion/bus":"^0.1.0","@mariozechner/pi-ai":"^0.73.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","vitest":"^3.1.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/ant_0.2.0_1786514506653_0.4124788658612326","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@antlegion/ant","version":"0.3.0","keywords":["agents","multi-agent","ai-agents","autonomous-agents","coordination","fact-bus","blackboard","stigmergy","dcu","worker","daemon","antlegion"],"author":{"name":"Carter.Yang"},"license":"MIT","_id":"@antlegion/ant@0.3.0","maintainers":[{"name":"yang9295","email":"929588562@qq.com"}],"homepage":"https://github.com/YangKGcsdms/antlegion-platform#readme","bugs":{"url":"https://github.com/YangKGcsdms/antlegion-platform/issues"},"bin":{"ant":"dist/main.js"},"dist":{"shasum":"e1a915efc3c79f4035d5836ac9909f04ecc98b3e","tarball":"https://registry.npmjs.org/@antlegion/ant/-/ant-0.3.0.tgz","fileCount":69,"integrity":"sha512-PxB7YGeSuksMcq4j1bN++1UYt12Lstd7PEZFN+wMw9Wd4kXsZYnUGj+1pskMfbM8mgq3XVesyCL9NDl8JMQIOQ==","signatures":[{"sig":"MEUCIQD4AORM06Y8WkWCY9vldvHXxfPQv70yxJEMYvh/U/EX8gIgVDU5rqgOu+bOZvgysnhLX1LGH8CY8DmWZacFmLA6IOo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":290989},"main":"dist/main.js","type":"module","types":"./dist/main.d.ts","engines":{"node":">=20"},"gitHead":"476f6b7dc24d010ff374f4c17def11fa7c984e52","scripts":{"req":"tsx src/main.ts req","test":"vitest run","board":"tsx src/main.ts board","build":"tsc -p tsconfig.build.json","chain":"tsx src/main.ts chain","ingestor":"tsx src/main.ts ingestor","typecheck":"tsc --noEmit","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"yang9295","email":"929588562@qq.com"},"repository":{"url":"git+https://github.com/YangKGcsdms/antlegion-platform.git","type":"git","directory":"ant"},"_npmVersion":"10.9.4","description":"Autonomous DCUs (Domain Control Units) on the AntLegion fact bus — a fleet of resident work units that poll the totally-ordered fact stream, claim work exactly-once, act, and resolve with evidence. Ships the dev-chain demo fleet + supervision board.","directories":{},"_nodeVersion":"22.22.0","dependencies":{"@antlegion/bus":"^0.1.0","@mariozechner/pi-ai":"^0.73.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","vitest":"^3.1.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/ant_0.3.0_1786520902399_0.5571213775634505","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@antlegion/ant","version":"0.4.0","keywords":["agents","multi-agent","ai-agents","autonomous-agents","coordination","fact-bus","blackboard","stigmergy","dcu","worker","daemon","antlegion"],"author":{"name":"Carter.Yang"},"license":"MIT","_id":"@antlegion/ant@0.4.0","maintainers":[{"name":"yang9295","email":"929588562@qq.com"}],"homepage":"https://antlegion.dev","bugs":{"url":"https://github.com/YangKGcsdms/antlegion-platform/issues"},"bin":{"ant":"dist/main.js"},"dist":{"shasum":"01ce5e7b40d43d8ebc07821f31c376c492b65b8c","tarball":"https://registry.npmjs.org/@antlegion/ant/-/ant-0.4.0.tgz","fileCount":69,"integrity":"sha512-MzagEC6PtUEEdroHKZSGRPgiY6OS+ZgbjC6CbGouOL1laJxW+Gd4nYjgeG2AKHZpIovjUCNxvZ78OnIETntrSQ==","signatures":[{"sig":"MEUCICCdr+Lt8zAigwCzP9w8gltSQ2yyZQFmKH7Q+wy4/a3dAiEAup0GjqvhTTjpOkW0tw2jJ0iL5IYTtcNAyswk3XVPhts=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":298000},"main":"dist/main.js","type":"module","types":"./dist/main.d.ts","engines":{"node":">=20"},"gitHead":"a0447586ad96f17d0488798172b8200ed767fda9","scripts":{"req":"tsx src/main.ts req","test":"vitest run","board":"tsx src/main.ts board","build":"tsc -p tsconfig.build.json","chain":"tsx src/main.ts chain","ingestor":"tsx src/main.ts ingestor","typecheck":"tsc --noEmit","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"yang9295","email":"929588562@qq.com"},"repository":{"url":"git+https://github.com/YangKGcsdms/antlegion-platform.git","type":"git","directory":"ant"},"_npmVersion":"10.9.4","description":"Autonomous DCUs (Domain Control Units) on the AntLegion fact bus — a fleet of resident work units that poll the totally-ordered fact stream, claim work exactly-once, act, and resolve with evidence. Ships the dev-chain demo fleet + supervision board.","directories":{},"_nodeVersion":"22.22.0","dependencies":{"@antlegion/bus":"^0.4.0","@mariozechner/pi-ai":"^0.73.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","vitest":"^3.1.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/ant_0.4.0_1786585938200_0.11468166488475728","host":"s3://npm-registry-packages-npm-production"}},"0.5.0":{"name":"@antlegion/ant","version":"0.5.0","description":"Resident agents (DCUs — Domain Control Units) on the AntLegion shared world-state log: each mirrors the totally-ordered fact stream, re-folds its view of the world, wakes on the facts it cares about, and deposits what it did. Ships a dev-chain as a workfl","type":"module","main":"dist/main.js","bin":{"ant":"dist/main.js"},"scripts":{"build":"tsc -p tsconfig.build.json","typecheck":"tsc --noEmit","test":"vitest run","chain":"tsx src/main.ts chain","ingestor":"tsx src/main.ts ingestor","board":"tsx src/main.ts board","req":"tsx src/main.ts req","prepublishOnly":"npm run build && npm test"},"keywords":["agents","multi-agent","ai-agents","autonomous-agents","coordination","fact-bus","blackboard","stigmergy","dcu","worker","daemon","antlegion"],"repository":{"type":"git","url":"git+https://github.com/YangKGcsdms/antlegion-platform.git","directory":"ant"},"homepage":"https://antlegion.dev","bugs":{"url":"https://github.com/YangKGcsdms/antlegion-platform/issues"},"engines":{"node":">=20"},"publishConfig":{"access":"public"},"author":{"name":"Carter.Yang"},"license":"MIT","dependencies":{"@antlegion/bus":"^0.5.0","@mariozechner/pi-ai":"^0.73.1"},"devDependencies":{"@types/node":"^22.0.0","tsx":"^4.19.0","typescript":"^5.7.0","vitest":"^3.1.0"},"_id":"@antlegion/ant@0.5.0","gitHead":"a20670eb7345b4f17a71a5754bc1db99b611871d","types":"./dist/main.d.ts","_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-xNyYZL0G0b2wR0EywVdVxbouS4aEr1yi2SyjfSW40KMgw+VIBcrrVV/9pREIPo3u4oe+JEXjNqNRq5P6W62GXA==","shasum":"0a87a93a0e3dbdf002add78a5a9afa1f8eb561e1","tarball":"https://registry.npmjs.org/@antlegion/ant/-/ant-0.5.0.tgz","fileCount":85,"unpackedSize":389323,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICjBXUjxRCsUZLv8CQnpxMkBpItIhr97Eviv+NDxUvivAiBdmrlJi/+6i/mlno14Y9xP42QuhApquB+ZNEEvTHAs4Q=="}]},"_npmUser":{"name":"yang9295","email":"929588562@qq.com"},"directories":{},"maintainers":[{"name":"yang9295","email":"929588562@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ant_0.5.0_1787555950976_0.7734922679253169"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-12T03:20:39.513Z","modified":"2026-08-24T07:19:11.369Z","0.0.1":"2026-08-12T03:20:39.828Z","0.1.0":"2026-08-12T03:48:33.512Z","0.2.0":"2026-08-12T06:01:46.796Z","0.3.0":"2026-08-12T07:48:22.555Z","0.4.0":"2026-08-13T01:52:18.569Z","0.5.0":"2026-08-24T07:19:11.143Z"},"bugs":{"url":"https://github.com/YangKGcsdms/antlegion-platform/issues"},"author":{"name":"Carter.Yang"},"license":"MIT","homepage":"https://antlegion.dev","keywords":["agents","multi-agent","ai-agents","autonomous-agents","coordination","fact-bus","blackboard","stigmergy","dcu","worker","daemon","antlegion"],"repository":{"type":"git","url":"git+https://github.com/YangKGcsdms/antlegion-platform.git","directory":"ant"},"description":"Resident agents (DCUs — Domain Control Units) on the AntLegion shared world-state log: each mirrors the totally-ordered fact stream, re-folds its view of the world, wakes on the facts it cares about, and deposits what it did. Ships a dev-chain as a workfl","maintainers":[{"name":"yang9295","email":"929588562@qq.com"}],"readme":"# @antlegion/ant — resident agents on the shared world-state log\n\nAn **ant** here is a resident agent that lives on an [AntLegion log](https://www.npmjs.com/package/@antlegion/bus):\nit mirrors the totally-ordered fact stream, **re-folds its own view of the\nworld** on every batch, wakes when the facts it cares about appear, and\ndeposits what it did back as facts. Nothing addresses it and it addresses\nnothing — like an ant reading pheromone on the ground.\n\n**DCU** = *Domain Control Unit* is the older, technical name for the same\nthing, borrowed from a car's electronic architecture: on a CAN bus no central\ncomputer gives orders — each control unit listens for the message IDs it cares\nabout and acts when its local condition holds. A DCU is a thin, deterministic\nloop over the log. No orchestrator, no DCU addressing another. If several DCUs\nend up forming a pipeline, that pipeline is a shape readers fold out of the\nstream *afterwards*, never a state any component holds.\n\n> **What this package is, and isn't.** The runtime (`runtime.ts`: mirror →\n> fold → act), colony identity, residency (`ant init` / `ant start`), the\n> read-only `ingestor-req` that mirrors a filesystem's truth onto the log, and\n> the identity/liveness folds are the product: they keep an isolated agent's\n> view of the world current. The **dev-chain** shipped alongside is a\n> *workflow client example* — one way to build a staged process on top of a\n> shared world — not what the log or this package is for. AntLegion is not a\n> multi-agent collaboration framework; see the [root README](../README.md).\n\n```\npoll(since cursor) → rebuild shared fold → evaluate trigger → act → advance\n```\n\n## Quick start\n\n```bash\nnpx @antlegion/bus                    # terminal 1 — a fact bus on :28090\nnpx @antlegion/ant chain              # terminal 2 — the dev-chain DCU fleet\nnpx @antlegion/ant req new \"试点需求\" -s pilot    # terminal 3 — feed it work\nnpx @antlegion/ant board              # supervision board → http://localhost:28091/devchain.html\n```\n\nWithin ~2s of `req new`, `dcu-plan` claims the requirement (exactly-once, by\nlowest seq), produces `plan.ready`, the adjudicator checks its evidence shape,\nand the chain parks at the H1 human gate — approve it on the board and\ndev → unittest → e2e run themselves to ✔ CHAIN DONE. `ant --help` lists all\ncommands; an optional `./ant.config.json` configures the bus URL and watch\nroots (`ANTLEGION_BUS_URL` overrides).\n\n> `ant init` (guided setup) and `ant start` (resident daemon) land in 0.2.\n\n### LLM acts + the unattended MVP run\n\nThe act step can route through an LLM (pi-ai → DeepSeek) while every bit of\ncoordination — the loop, folds, claims, evidence shapes — stays deterministic\ncode. The LLM produces content; it cannot choose what to listen to or claim:\n\n```bash\nexport DEEPSEEK_API_KEY=sk-…             # never committed\nANT_WORKER=llm ant chain                  # fleet with LLM acts\nANT_AUTO_GATE=1 ANT_WORKER=llm ant chain  # + auto-approved gates (unattended)\n\nANT_WORKER=llm ant mvp --reqs 25          # throughput run: feeds 25 requirements\n# → 100 stage cycles (trigger → claim → llm act → resolve), 100 adjudications,\n#   25 gate approvals; prints a scoreboard with LLM token usage at the end\n```\n\n`ANT_LLM_MODEL` (default `deepseek-v4-flash`) and `ANT_LLM_BASE_URL`\n(default `https://api.deepseek.com`) select the model; any OpenAI-compatible\nendpoint works. A malformed completion degrades to a valid deterministic\nfallback — the chain never stalls on a bad generation.\n\nThis package ships three layers, built up in steps:\n\n- **Step 0–2** — the bus lifecycle + the `ingestor-req` DCU that mirrors\n  requirement workspaces onto the bus, plus a live requirement board.\n- **Step 3** — the **dev-chain**: six DCUs that run Carter's\n  `requirement-dev-flow` skill pipeline as autonomous, fact-coordinated units,\n  plus a supervision board.\n\n`ingestor-req` is documented inline below. The dev-chain is documented first\nonly because it is the longest worked example — read it as *one client of a\nshared world*, not as the shape every ant must take.\n\n---\n\n## The dev-chain: six DCUs\n\nCarter's 11-step delivery flow (`requirement-dev-flow`) collapses onto the bus\nas **four stage DCUs + one adjudicator + one watchdog**. Each stage DCU knows\nexactly one sentence: *\"when the shared fold says my stage is `open` for some\nrequirement and nobody holds the claim, I claim it.\"* It wins the claim\n(exactly-once by lowest `seq`), does the work, and resolves the input fact with\nits artifact as a causal child (`refs.parent`). Losers back off; a crashed\nwinner's claim expires and a survivor re-runs. S9–S11 stay human.\n\n| DCU | listens | gate | produces | evidence shape (missing → rejected) | ≈ skill |\n|---|---|---|---|---|---|\n| `dcu-plan` | `req.registered` | — | `plan.ready` | `scope` / `out_of_scope` / `acceptance` | requirement-breakdown · codebase-research · cross-system-solution |\n| `dcu-dev` | `plan.ready` | **H1** | `dev.done` | `branch` / `changed_files` / `consumers_checked` | parallel-requirement-workspace · dev-flow S3–S4 |\n| `dcu-unittest` | `dev.done` | — | `test.unit.report` | `passed` / `failed` / **`not_covered`** | springboot-jdk8-cli · dev-flow S5 |\n| `dcu-e2e` | `test.unit.report` | — | `e2e.report` | `api_assertions` / **`page_checked`** / `deviations` · `defects` · `gaps` | integration-debugging · dev-flow S6–S8 |\n| `dcu-adjudicator` | *all artifacts* | — | `evidence.accepted` / `evidence.rejected` | — (it judges the others) | — |\n| `dcu-watchdog` | *everything (`*`)* | — | `chain.starved` / `escalate.human` | — (it detects exceptions) | — |\n\nThe stage table is a **predicate**, not a runtime limit. A DCU mirrors the\nwhole stream; \"listens\" is just its filter. The adjudicator and watchdog are\nalready multi-listen / multi-produce — nothing stops a stage from doing the\nsame. See [Multi-listen, multi-produce](#multi-listen-multi-produce).\n\n### Evidence shapes: 做完了 ≠ 验证过了 as structure\n\nThe most valuable thing in Carter's flow is the discipline *\"done ≠ verified.\"*\nThe dev-chain makes it structural: **resolving is not a declaration, it is\nsubmitting evidence.** The adjudicator checks each artifact's payload against\nthe shape its producer registered; a wrong shape publishes `evidence.rejected`\nand the chain **halts at that stage** until reworked. Concretely:\n\n| naïve conclusion | the flow's counter-discipline | machine-checkable shape |\n|---|---|---|\n| compiled = correct | grep every consumer before changing an invariant | `dev.done` must carry `consumers_checked[]` |\n| unit tests pass = behaviour correct | the report must enumerate what it *didn't* cover | `test.unit.report` without `not_covered` = invalid |\n| API green = page correct | 27/27 endpoints green, page still shows `-` | `e2e.report` needs `page_checked: true` + assertions |\n| a pass-rate = a report | the report must have deviations / defects / gaps | all three sections present or it isn't `accepted` |\n\nAn artifact that skips its evidence is, on the bus, equivalent to work never\ndone — a survivor reclaims and redoes it.\n\n### The two cross-cutting DCUs\n\n- **`dcu-adjudicator`** — listens to all four artifact types, validates the\n  evidence shape from the registry, publishes one verdict per artifact\n  (`refs.verdict_of`). It is the single writer of trust in the chain;\n  downstream stages fold on its verdict, never on the raw artifact.\n- **`dcu-watchdog`** — listens to everything, produces *only exceptions*, never\n  claims and never advances the chain. Three conditions, each keyed on a fact\n  id for idempotency:\n  - `chain.starved` — a stage is `open` past a threshold with no claim (dead\n    domain / wrong predicate). Anchored on the *latest prerequisite's* `recv`\n    (input verdict / gate approval), not the requirement's birth.\n  - `escalate.human` on **claim churn** — one input burned ≥ N claims with no\n    resolve (crash-looping worker: a poison pill).\n  - `escalate.human` on **rejected evidence** — an artifact the adjudicator\n    shot down (including stray artifacts not on any chain).\n\n---\n\n## The supervision board\n\n`devchain.html` (served at `:28091`) is the supervisor's whole interface. It\nfolds everything client-side from `GET /facts` — same semantics as\n`src/folds/`. Four sections, top to bottom:\n\n1. **例外收件箱 (exception inbox)** — *the only place a human looks.* Gated\n   approvals (with a **批准 H1** button), escalations, and starvation. Items\n   self-clear when their condition no longer holds in the fold. **Empty inbox =\n   autonomous operation.** The H1 button is the only write the board makes: it\n   publishes `gate.approved` as `carter@board`.\n2. **DCU nodes** — one card per DCU, each answering four questions:\n   - **职责 (duty)** — what it reacts to → gate → claims → produces, plus its\n     evidence shape spelled out.\n   - **来历 (origin)** — the `sys.registry` fact that *is* its registration\n     (registration = the act of publishing; no central registrar) + which\n     skills it compresses.\n   - **现在 (now)** — its current claim (`● working: slug · stage`) or idle.\n   - **履历 (footprint)** — cumulative counts + its recent authored facts, in\n     plain language (`#23 produced plan.ready ✓adjudicated`).\n3. **dev chain** — the per-requirement pipeline, one stage chip each, gates and\n   verdicts inline.\n4. **fact stream** — the tail of the total order.\n\nThe roster is not hard-coded — it is folded from `sys.registry` facts, so a new\nDCU appears the moment it registers.\n\n---\n\n## Run\n\nInstalled (`npm i -g @antlegion/ant`) or via `npx @antlegion/ant`:\n\n```bash\nant chain                # the dev-chain fleet in the foreground\n                         # (each DCU its own identity + loop, one process)\nant board                # supervision board (:28091)\n# open http://localhost:28091/devchain.html?bus=http://localhost:28090\n# (the requirement board is still at board.html)\n```\n\nDrive a requirement end to end:\n\n```bash\nant req new \"你的需求名\" -s your-slug   # publishes req.registered\n# → dcu-plan claims it within ~2s, produces plan.ready, adjudicator accepts,\n#   the chain parks at H1. Click 批准 H1 on the board (or POST gate.approved);\n#   dev → unittest → e2e then run themselves to ✔ CHAIN DONE.\n```\n\nWorking from the repo instead, `ant/scripts/up.sh` brings up bus + ingestor +\nfleet + board idempotently and `ant/scripts/down.sh` stops everything.\n\nWorkers are **simulated** in Step 3 (deterministic payloads + a short sleep):\nthis validates the *mechanics* — claim, gate, adjudicate, chain, escalate —\nbefore wiring real work. Swapping a simulated worker for a headless-agent spawn\n(`claude -p \"<work packet>\" --cwd <worktree>`, `codex exec …`) changes only the\nworker body in `src/dcus/devchain-dcus.ts`; **the bus contract is identical.**\nThat is the intended Step 4.\n\n---\n\n## Multi-listen, multi-produce\n\nA DCU is not limited to one input or one output — the loop already hands\n`onBatch` the full mirror, so \"listens\" is only a predicate you write:\n\n- **Multi-listen** is a predicate union — free. `dcu-adjudicator` already\n  listens to four types; `dcu-watchdog` to all.\n- **Multi-produce** is already supported: `client.resolve(F, children[])`\n  takes an array, and every child is stamped with `refs.parent: F` (causation)\n  automatically. One resolve can emit several artifacts.\n- **Discipline:** the claim unit is still *one fact* (exactly-once is a theorem\n  at that grain). Multi-produce is for **cross-cutting domains** (a doc-sync\n  DCU listening to `dev.done` + `e2e.report`; a real headless agent that edits\n  code + writes tests + updates docs in one run) — *not* for collapsing the\n  vertical chain into one omni-DCU, which would delete the orchestrator from\n  the architecture and grow it back inside a node (you'd lose per-stage claim\n  takeover, per-artifact adjudication, and stage-level observability).\n- **Caveat:** meaning lives in the reader. If a DCU emits a new artifact shape,\n  the domain's fold must be re-legislated to understand it — which is exactly\n  what the `sys.registry` + shared-fold design is for.\n\n---\n\n## Facts\n\n| type | payload | refs |\n|---|---|---|\n| `req.registered` | `{slug,name,created,origin,slot,branch,projects,ports}` | `subject:<slug>` |\n| `doc.updated` | `{reqSlug,doc,status,mtime,path,origin}` | `subject:<slug>/<doc>` |\n| `sys.registry` | `{domain,dcu,role?,worker,stage?,listens,produces,evidence_required?,skills?}` | — |\n| `plan.ready` · `dev.done` · `test.unit.report` · `e2e.report` | stage evidence (see table) | `parent:<input>`, `subject:<slug>` |\n| `gate.approved` | `{gate,reqSlug,note}` | `gate_of:<artifact>` |\n| `evidence.accepted` / `evidence.rejected` | `{stage,checked?/missing?}` | `verdict_of:<artifact>` |\n| `chain.starved` | `{reqSlug,stage,openForS}` | `starves:<input>` |\n| `escalate.human` | `{reqSlug,stage,reason,detail}` | `escalates:<input/artifact>` |\n\n`sys.registry` facts are published with `ts:0` and a stable nonce, so a\nrestart re-publishes byte-identical content and the bus dedups — registration\nis idempotent and needs no coordination.\n\n---\n\n## Layout\n\n```\nsrc/runtime.ts            the DCU loop primitive (runDCU / DCUSpec / DCUContext)\nsrc/folds/chain.ts        requirement-chain fold (ingestor board)\nsrc/folds/devchain.ts     dev-chain registry + evidence rules + fold\nsrc/folds/watchdog.ts     starvation / escalation detection (pure)\nsrc/dcus/ingestor-req.ts  the ingestor DCU (READ-ONLY on watched roots)\nsrc/dcus/devchain-dcus.ts the four stage DCUs + adjudicator (+ fleet factory)\nsrc/dcus/watchdog-dcu.ts  the watchdog DCU\nsrc/main.ts               the `ant` CLI: chain | ingestor | board | req new \"<名称>\" [-s slug]\ndevchain.html             supervision board (inbox + DCU nodes + chain)\nboard.html                requirement-chain board (Step 1)\nscripts/up.sh|down.sh     lifecycle (idempotent, no orphans)\n```\n\n## Test\n\n```bash\ncd ant\nnpm install\nnpx tsc --noEmit\nnpx vitest run        # 71 tests: folds (chain / devchain / watchdog),\n                      # evidence rules, env + status-header parsers,\n                      # ingestor backfill, req-new manifest/nonce, config\n```\n\nThe dev-chain and watchdog fold tests pin the shared worldview: every DCU and\nthe board fold the same stream into the same state, the evidence rules encode\n`做完了 ≠ 验证过了`, and a rejected artifact provably halts the chain. Tests use\nin-memory fact streams and tmpdirs — they never touch the live bus or the real\nworkspace.\n\n---\n\n## `ingestor-req` (Step 1–2)\n\nThe first DCU: it mirrors requirement workspaces onto the bus, **read-only**.\nIt watches every configured root (`ant.config.json` → `watchRoots`, each tagged\nwith an `origin`) via `fs.watch` + a 5s rescan fallback, and publishes\n`req.registered` per requirement dir and `doc.updated` per doc write. Published\n`ts` values derive from the filesystem (never the wall clock), so re-ingesting\nan unchanged workspace yields `deduped:true` and no new facts.\n\nNative requirements are created by the DCU system itself:\n\n```bash\nant req new \"<名称>\" -s <slug>\n# creates dcu-workspace/<yyyymmddHHMM>-<slug>/{dcu.env, docs/, logs/}\n# and publishes req.registered (nonce req:dcu:<dirname>, origin dcu)\n```\n\n`req new` and the ingestor's backfill plan byte-identical facts for the same\ndir (shared nonce), so whoever publishes second dedups — no double-publish.\nThe default watch root is the native `dcu-workspace/`; the OA mirror is off by\ndefault (see `src/config.ts`).\n```\n","readmeFilename":"README.md"}