@pavel.sommer/agiter 0.14.1-alpha.0 → 0.40.0-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,165 @@
+# Changelog
+
+What changed for users of agiter, newest first. The versions published to npm are the
+headings; the internal steps between them are listed under the release that brought them.
+The reasoning behind each change is in `docs/design-recap.md`, section 19 ("Added in …").
+The format follows [Keep a Changelog](https://keepachangelog.com/); the package is alpha,
+so any minor version may change behaviour.
+
+## [Unreleased]
+
+### Breaking
+
+- 0.32.0: the models are per task, not per role. The author of a task uses
+  `agiter/config/.models.<task>.json`, its reviewer `.models.<task>.review.json`, else
+  `.models.review.json`, else `.models.json`. The old role files (`.models.architect.json`, …)
+  still count until a run copies each to the files of its tasks; then delete them
+  (`agiter models --list` says which). `agiter roles --list` is gone: use
+  `agiter models --list`; the API's `roles` and `listRoles` became `models` and `listModels`.
+
+### Added
+
+- 0.39.0: a spec's section "Scope" (`- write:`, `- tests:`, `- protected:`): a work may change
+  only its write paths (and the tests while no earlier step wrote them), never protected ones;
+  tests written by an earlier create-tests are frozen for the work. A spec without it works as before.
+- 0.38.0: `agiter accept` lists what it could not check (a run not done, a work without review
+  or checks) and records it as waived.
+- 0.37.0: `cost` is what was paid and `apiCost` the API price: on a subscription (an agent's
+  `"subscription": true`, or claude's own login by subscription) the cost is 0 and the API
+  price is kept; documents, your input file and `status` show both (`$0 (API $1.70)`).
+- 0.37.0: claude streams (`--output-format stream-json --verbose`): its text and tools show as
+  they come, and each call records the subscription's five-hour and weekly limits and what it
+  added; the run shows the state at its end (an estimate: your own use at the time counts too).
+- 0.36.0: `agiter accept <file>`: your input (an initiative, an epic) and every document made
+  from it, down the chain, get status `Accepted`; nothing runs from them any more.
+- 0.36.0: `--profile` on `run` and `continue`, and `agiter profile [<run>]`: a model analyses
+  the run (time, cost, reviews, decisions, work, the harness) into `docs/<run>.profile.md`.
+  Its models: `agiter/config/.models.create-profile.json`.
+- 0.36.0: a work without a review stops on a contradiction or an impossible criterion (its
+  "Open questions") instead of changing the criterion: the run is `blocked`, its changes are
+  kept aside, the question is in the decisions report; answered there, `continue` runs it again.
+- 0.32.0: `agiter models --list`: the file, agent and models of each task's author and reviewer.
+- 0.31.0: the task `create-validation` (named `validate` until 0.33.0): it reads any input
+  and says what a working prototype still needs (Missing, Unclear, Contradictions, a
+  verdict), without writing any of it. Alone (`--pipeline create-validation`) or first
+  (`create-validation,create-epics`: the next step takes the same input); the result is
+  published as `docs/<run>.validation.md`. Give it a cheap model in
+  `agiter/config/.models.create-validation.json`.
+- 0.31.0: task definitions can carry `instructions`, `decides: false` and `passes`; an
+  artifact `publish: true` publishes a record.
+- 0.30.0: `agiter new <type> [--name <name>]` writes a new document of yours (initiative,
+  epic) into the docs folder from a template; a project's `agiter/config/templates/<type>.md`
+  overrides the package's. Only "Goal" is required; the hints are HTML comments.
+- 0.30.0: a section "Already decided" in your input: every step follows those decisions and
+  does not ask again, also in the runs on the epics made from it.
+- 0.28.0: the decisions made earlier (the input's, and the earlier steps') reach every
+  author and reviewer; a silent contradiction is a blocking finding.
+- 0.28.0: the owner's file shows the model and cost of the whole tree that grows from it
+  (the runs on its epics included).
+
+### Changed
+
+- 0.36.0: a run whose last review is Block ends `blocked`, not `done`.
+- 0.36.0: `select: "cheapest"` is refused as not supported; `effort` is passed only to an agent
+  whose definition says how, and is recorded as not applied otherwise.
+- 0.34.0: the task `create-epics` is `create-epic`, like every other task and type; the
+  overview's files are `<run>.create-epic.<round>.md`, the models `.models.create-epic.json`.
+  The old name still works as an alias in pipelines, older runs and documents.
+- 0.33.0: the task `validate` is `create-validation`, like every task that writes something;
+  its result is `docs/<run>.validation.md` (named by what the task gives), its models
+  `.models.create-validation.json`.
+- 0.29.0: decisions inherited from the input (an epic's) are listed under "Inherited",
+  without an Answer, with a link to the parent run's report, where they are answered.
+- 0.29.0: a default for autonomous decisions. The effort goes into the functional core of
+  the request; the look the input does not define (colours, sizes, spacing, fonts, focus and
+  hover styles, animation) is the author's. A project tightens or loosens this in
+  `agiter/config/project.md`.
+- 0.29.0: a change of an earlier decision has the level of the decision it changes.
+
+### Fixed
+
+- 0.40.0: a published document a reviewer or the profiler changed is put back (it was only
+  reported); the next model of a profile starts from the files as they were, agiter/config too.
+- 0.40.0: a spec's Scope that is there but not understood stops the work instead of leaving it
+  the task's whole scope; a new spec with one is an invalid output.
+- 0.40.0: each try of a check keeps its own log.
+- 0.40.0: `agiter accept` counts only checks that passed after the work was written.
+- 0.38.0: a reviewer or the profiler that changes files fails, and the files are put back,
+  also when its call fails and also in agiter/config and agiter/docs; the profiler had no guard.
+- 0.38.0: a work stopped on several open questions runs again only when all are answered.
+- 0.38.0: checks keep their output in a log and are killed with every process they started
+  when they run past their timeout.
+- 0.36.0: a profile's next model starts from the files as they were before the failed one.
+- 0.36.0: a reviewer that changes files fails its call; the files are put back.
+- 0.36.0: a call past its timeout is killed with every process it started (a dev server, a
+  browser), on Windows too.
+- 0.35.0: in a worktree run the agent CLI works in the worktree (it worked in the main
+  checkout, and the prompt's paths pointed there).
+- 0.35.0: a model the profile tries after a failed one starts without the failed try's output.
+- 0.35.0: a finding with an unknown severity ("critical", none) is blocking, never passed.
+- 0.35.0: the criteria of draft, initiative and spec no longer ask the reviewer to treat every
+  decision the author made as a finding.
+
+## [0.27.0-alpha.0] - 2026-11-13
+
+### Added
+
+- 0.15.0: methodical results are published to `docs/` (`<run>.<name>.md`, epics as
+  `<run>.epic.E1.md`), never over an existing file; agents never change published files.
+- 0.16.0: autonomous decisions. The author decides where the input is silent and records
+  each decision as `[owner]` or `[author]`; the harness collects them into a decisions
+  report for the owner to answer.
+- 0.17.0: the cost of a run, from the agents' structured output (opencode `--format json`,
+  claude `--output-format json`), per call and per run; `status` and `run --list` show it.
+- 0.20.0: Tolaria relationships (`belongs_to`, `related_to`) in the run's notes.
+- 0.21.0: `model` and `cost` in the frontmatter of every document a model call writes.
+- 0.23.0: the owner's input file gets `has` (what runs made from it); 0.25.0 adds `model`
+  and `cost`. The edits are surgical and do not count as changes of his.
+- 0.23.0: a new dependency is always the owner's decision.
+- 0.26.0: the decisions report and the last report of each step are published to `docs/`.
+- 0.27.0: the owner's answers in a decisions report reach the next run made from that
+  run's output by themselves (`agiter/runs/<run>/answers.md`, "The owner's answers").
+
+### Changed
+
+- 0.15.0: frontmatter types are TitleCase and singular; since 0.18.0 every task record is
+  `type: Pipeline`, told apart by `task`. Old names stay readable as aliases.
+- 0.15.0: versions of methodical artifacts and the input's copy are dot files; since 0.26.0
+  every chain report too.
+- 0.22.0: an owner's input with a frontmatter `type` runs only with `status: Active`.
+- 0.24.0: links in the body are wikilinks (`[[name]]`) instead of Markdown links (Tolaria
+  drops local Markdown links).
+- 0.25.1: a decision is written as `<decision> Why: <reason>`; the report shows it as a
+  table with Decided, Because and Answer.
+- 0.25.2: the author checks its result for unrecorded decisions before it finishes.
+
+## [0.14.1-alpha.0] - 2026-11-12
+
+### Added
+
+- 0.11.0: isolation modes, `run --isolation <branch|worktree>`; the default works in the
+  current checkout with snapshot commits and makes no commits of its own.
+- 0.12.0: the output language, `run --lang <tag>`.
+- 0.13.0: `create-epics` breaks an initiative down into functional areas and epics, one
+  file per epic.
+- 0.14.0: the owner's documents keep their own structure, types and statuses; run ids and
+  file names follow `<stamp>-<name>` and `<run>.<type>.<round>.md`.
+
+## [0.8.0-alpha.0] - 2026-11-11
+
+The first usable release.
+
+### Added
+
+- 0.3.0: inputs, artifacts, tasks and pipelines; rounds with versions and cumulative
+  reports; `continue`; a scripted fake executor for tests.
+- 0.4.0: model profiles per role, agents in `agiter/config/.agents.json`, prompts and logs
+  per call, resuming the same scenario, `--new`.
+- 0.5.0: the run's audit (`--audit`, `agiter audit`).
+- 0.6.0: live output of a run (events, streaming call logs; `--quiet`, `--json`).
+- 0.7.0: git isolation on a run branch with a commit per call; `agiter finish [--merge]`.
+
+[Unreleased]: https://www.npmjs.com/package/@pavel.sommer/agiter
+[0.27.0-alpha.0]: https://www.npmjs.com/package/@pavel.sommer/agiter/v/0.27.0-alpha.0
+[0.14.1-alpha.0]: https://www.npmjs.com/package/@pavel.sommer/agiter/v/0.14.1-alpha.0
+[0.8.0-alpha.0]: https://www.npmjs.com/package/@pavel.sommer/agiter/v/0.8.0-alpha.0

package/README.md

@@ -1,82 +1,167 @@
-# agiter
-
-A client-agnostic harness for spec-driven agentic development. The design is in
-[docs/design-recap.md](docs/design-recap.md).
-
-A run's pipeline is always given explicitly: a comma list of tokens, or a pipeline file
-(`*.json`, `{ "steps": [...] }`). A token is `task` (one round, no review) or `task:N` (at most
-N rounds; each round is a version and its review report).
-
-The project's tech stack lives in `agiter/config/.stack.json` (blocks and presets, `agiter
-stack --help`); the harness puts into each model's prompt only what its role needs from it, then the owner's
-`agiter/config/project.md` (structure, naming, scaffolding, rules) for every role. `--includeFile
-<file>` (repeatable) gives any file to every model call of a run. `create-epics` breaks an initiative down into its functional areas and writes one epic file per
-epic (`<run>.create-epics.<round>.E1.md`, …) next to an overview. `--lang <tag>` (an ISO tag: `cs`, `en`,
-`cs-CZ`, `en-US`, …) sets the language of the output; without it the models write in the language
-of the input. The headings the harness reads stay in English, and so do established technical
-terms and common anglicisms.
-
-Status: step 1 (inputs, artifacts, tasks, pipelines, the run engine, simulation) and a first
-real executor: `agiter run` calls the agent CLI of each role's model profile
-(`agiter/config/.models.<role>.json`, `agiter/config/.models.json`, and the agents in `agiter/config/.agents.json`, all copied from the package's defaults by `agiter init` or the first run). In a git repository
-a run works in the current checkout by default (no harness commits; the owner reviews and
-commits the changes), with `--isolation branch` on its own branch `agiter/<run>` with a commit
-per call, or with `--isolation worktree` in `agiter/.worktrees/<run>` on that branch with the
-project's `node_modules` linked in. The scope of a step is checked against what git sees, and
-`agiter finish [--merge]` ends a branch or worktree run.
-
-## Layout
-
-| Path | Content |
-| --- | --- |
-| `index.mjs` | the public API |
-| `bin/agiter.mjs` | the CLI on commander (`agiter --help`, `agiter <command> --help`) |
-| `sidecar.mjs` | JSON-RPC over stdio for long-lived clients (Far Manager) |
-| `src/` | the modules: definitions, pipelines, artifacts, engine, tools, log |
-| `defs/` | the package's artifact types, tasks, stack blocks and presets, default config |
-| `test/` | `npm test` (node:test, no dependencies) |
-
-The owner's documents stay his: any file a run did not write is an input in the owner's own form;
-the pipeline decides what it is (`create-epics`: an initiative), and its frontmatter, status and
-structure are not checked. A run is named after the input file without its leading timestamp and
-stamped in local time (`yyMMddHHmmss`); the titles of the outputs are the models' own.
-
-A project keeps everything in `agiter/`: `docs/<run>/` (the chain of each run), `runs/`,
-`logs/`, its own definitions (`artifacts/`, `tasks/`, merged over the package's) and
-`checks.json` (the required checks).
-
-## A run's files
-
-```text
-agiter/docs/<run>/<run>.md                    the input, copied as it is (never changed)
-agiter/docs/<run>/<run>.draft.1.md            round 1 of create-draft:3
-agiter/docs/<run>/<run>.draft.1.report.md     its review: Block or Done, cumulative
-agiter/docs/<run>/<run>.draft.2.md            round 2: input + draft.1 + its report
-...
-```
-
-A version is Active when another step follows and it has no review or its report is Done;
-otherwise Draft. A step takes only prose or an Active artifact whose latest report is not
-Block. The state of a run is its files: `agiter continue` walks the steps again and repeats
-nothing done.
-
-## Try it
-
-```text
-agiter list tasks
-agiter plan --pipeline "create-draft:3,create-spec:2,create-work,checks" --text "Add a login form"
-agiter simulate --pipeline "create-draft:3,create-spec:2,create-work" --text "Add a login form" --script script.json
-agiter continue --root <project printed by simulate>
-```
-
-A simulation script says what the fake model returns, per task, role and attempt:
-
-```json
-{
-	"steps": {
-		"create-draft#1/review": { "findings": [{ "text": "Problem unclear" }] },
-		"create-draft#2": { "responses": { "F-1": "fixed: Problem rewritten" } },
-		"create-work": { "changes": ["src/login.js"] }
-	}
-}
-```
+# agiter
+
+A client-agnostic harness for spec-driven agentic development. The design is in
+[docs/design-recap.md](docs/design-recap.md).
+
+## The key idea: diverse points of view
+
+Every step of a run is done by separate agents, each starting with a fresh context: the author
+writes, the reviewer judges what was written against the input and the criteria, without the
+author's reasoning in view, so it has nothing to anchor on and no decision of its own to
+defend. A next round's author gets its version and the review, not its earlier train of
+thought. One long prompting session cannot give this: there a model judges its own work with
+the whole path to it still in context, like a person proofreading what he wrote a minute ago.
+
+Context diversity works with the same model too. Model diversity adds a second layer: a
+model's blind spots come from its training, and a fresh context does not remove them, a
+different model does. That is why every task has its own model files, one for its author
+and one for its reviewer (`agiter/config/.models.<task>.json`, `.models.<task>.review.json`,
+else `.models.review.json` for every reviewer, else `.models.json`): a cheap author and a
+stronger reviewer of another family make a good pair. `agiter models --list` shows which file
+each task's author and reviewer get.
+
+## How it works
+
+A run's pipeline is always given explicitly: a comma list of tokens, or a pipeline file
+(`*.json`, `{ "steps": [...] }`). A token is `task` (one round, no review) or `task:N` (at most
+N rounds; each round is a version and its review report).
+
+The project's tech stack lives in `agiter/config/.stack.json` (blocks and presets, `agiter
+stack --help`); the harness puts into each model's prompt only what its task needs from it, then the owner's
+`agiter/config/project.md` (structure, naming, scaffolding, rules) for every task. What the models may decide on their own follows a default (the effort goes into the functional
+core of the request; the owner decides what the user gets and how it behaves, and every new
+dependency; the look the input does not define is the author's); a section "Autonomous decisions" in `project.md`
+tightens or loosens it for the project. `agiter new initiative --name <name>` (or `epic`) starts
+a document of yours from a template (`agiter/config/templates/<type>.md` overrides the
+package's); its section "Already decided" lists what you decided already, and no step asks
+about it again. `agiter run --input <file> --pipeline create-validation` asks a model (give it a cheap one
+in `.models.create-validation.json`) what a working prototype still needs from the input
+(`docs/<run>.validation.md`),
+before the expensive steps; `create-validation,create-epic` does both, the second on the same input. `--includeFile
+<file>` (repeatable) gives any file to every model call of a run. `create-epic` breaks an initiative down into its functional areas and writes one epic file per
+epic (`<run>.create-epic.<round>.E1.md`, …) next to an overview. `--lang <tag>` (an ISO tag: `cs`, `en`,
+`cs-CZ`, `en-US`, …) sets the language of the output; without it the models write in the language
+of the input. The headings the harness reads stay in English, and so do established technical
+terms and common anglicisms.
+
+Status: step 1 (inputs, artifacts, tasks, pipelines, the run engine, simulation) and a first
+real executor: `agiter run` calls the agent CLI of each task's model profile
+(`agiter/config/.models.<task>.json`, `.models.review.json`, `agiter/config/.models.json`, and the agents in `agiter/config/.agents.json`, all copied from the package's defaults by `agiter init` or the first run). In a git repository
+a run works in the current checkout by default (no harness commits; the owner reviews and
+commits the changes), with `--isolation branch` on its own branch `agiter/<run>` with a commit
+per call, or with `--isolation worktree` in `agiter/.worktrees/<run>` on that branch with the
+project's `node_modules` linked in. The scope of a step is checked against what git sees, and
+`agiter finish [--merge]` ends a branch or worktree run.
+
+A run that went through is `done`; one whose last review blocked, or whose work stopped on an
+open question, is `blocked`. A worker without a review decides what the input leaves open, but
+where the input contradicts itself or a criterion cannot be met as written it does not change
+the criterion: it names the contradiction under "Open questions", the run stops, its changes go
+aside as a patch, and the question waits in the decisions report; answered there, `agiter
+continue` runs the work again with the answer. Give a work its review where you can
+(`create-work:1`): a work without one is done, not checked. A spec's section "Scope" (`- write:`,
+`- tests:`, `- protected:` paths) narrows what the work may change; tests an earlier `create-tests`
+wrote are protected from the work (`create-tests,create-work:1,checks` for test-first). A reviewer that changes a file
+fails its call (the file is put back); a profile's next model starts from the state before the
+failed one; a call past its timeout is killed with every process it started.
+
+Done is not accepted: `agiter accept <file>` is your word that a document (your initiative, an
+epic) and everything made from it are what you want. It and every document of the runs on it,
+down the chain, get status `Accepted`, and nothing runs from them any more. `--profile` (on
+`run` and `continue`) has a model analyse the run when it ends, as an owner reviewing it would:
+where the time and the money went, what the reviews found, which decisions are really yours,
+what the work did beyond its spec, what the run shows about the harness; it is written to
+`docs/<run>.profile.md` (`agiter profile [<run>]` does it for a run after the fact; its models
+are `.models.create-profile.json`).
+
+`cost` is what a call was paid, `apiCost` its price by the API list: on a subscription (an
+agent's `"subscription": true` in `.agents.json`, or claude's own login by subscription) the
+cost is 0 and the API price is kept for comparing. claude streams its output, and each call
+records how much of the subscription's five-hour and weekly limits is used and what it added;
+`status` shows the state at the end of the run.
+
+## Layout
+
+| Path | Content |
+| --- | --- |
+| `index.mjs` | the public API |
+| `bin/agiter.mjs` | the CLI on commander (`agiter --help`, `agiter <command> --help`) |
+| `sidecar.mjs` | JSON-RPC over stdio for long-lived clients (Far Manager) |
+| `src/` | the modules: definitions, pipelines, artifacts, engine, tools, log |
+| `defs/` | the package's artifact types, tasks, stack blocks and presets, default config |
+| `test/` | `npm test` (node:test, no dependencies) |
+
+The owner's documents stay his: any file a run did not write is an input in the owner's own form
+(with a frontmatter `type` it runs only with status `Active`; without one it runs as it is);
+the pipeline decides what it is (`create-epic`: an initiative), and its frontmatter, status and
+structure are not checked. A run is named after the input file without its leading timestamp and
+stamped in local time (`yyMMddHHmmss`); the titles of the outputs are the models' own.
+
+A project keeps everything in `agiter/`: `docs/<run>/` (the chain of each run), `runs/`,
+`logs/`, its own definitions (`artifacts/`, `tasks/`, merged over the package's) and
+`checks.json` (the required checks).
+
+## A run's files
+
+```text
+agiter/docs/<run>/.<run>.md                   the input, copied as it is (never changed; a dot file)
+agiter/docs/<run>/.<run>.draft.1.md           round 1 of create-draft:3 (a dot file)
+agiter/docs/<run>/.<run>.draft.1.report.md    its review: Block or Done, cumulative (a dot file)
+agiter/docs/<run>/.<run>.draft.2.md           round 2: input + draft.1 + its report
+agiter/docs/<run>/<run>.create-work.1.md      the record of create-work
+docs/<run>.draft.md                           the result of a step, published
+docs/<run>.draft.report.md                    the step's last report, published
+docs/<run>.decisions.md                       the decisions report, for the owner to answer
+docs/<run>.epic.E1.md                         an epic of create-epic, published
+...
+```
+
+Two kinds of output. Methodical artifacts (initiative, epic, draft, spec) are the documents a
+next run builds on: the result of each step (no review, or its report Done) is published to
+`docs/` (`agiter/config/.settings.json` `{ "docs": "<folder>" }` changes it), never over a
+file there, and agents never change them. Task records (`create-epic`, `create-work`,
+`create-tests`, `checks`) and the reports stay in `agiter/docs/<run>/` with every round; the versions of methodical
+artifacts there are dot files, so a client like Tolaria shows each document once (in `docs/`).
+Where the input does not say something, the models decide on their own and record it under
+"Decisions" (`[owner]` or `[author]`); at the end of a run the harness collects them into
+`docs/<run>.decisions.md` (beside the owner's documents), the owner's first, each with an `Answer:` line, so the
+answered file can be the input of a next run.
+A run on a document an earlier run wrote (an epic, a spec) gets that run's answered decisions in
+its prompt by itself: they override the document where they differ.
+Each document's frontmatter has the `model` that wrote it and the `cost` of that call.
+Every model call's cost and tokens come from the agent's JSON output (opencode `--format json`,
+claude `--output-format json`): `status` shows them per call and for the run, `run --list` per run.
+At the end of a run the file names in its documents become wikilinks (`[[name]]`, as Tolaria
+resolves them), to the notes in view: a version of the chain links to its published document.
+Their frontmatter gets Tolaria's relationships too: `belongs_to` and `related_to` as wikilinks.
+The owner's input file gets `has` (wikilinks to what runs made from it and keep), `model` (the
+models they used) and `cost` (their total, over the whole tree that grows from it: the epics' runs too).
+Every step gets the decisions made before it (the input's, the run's earlier steps') and keeps them.
+Frontmatter types are TitleCase and singular (`Spec`, `Epic`, `Report`, `Decision`); every task's
+record is `Pipeline`, its `task` (`create-epic`, `create-work`, …) tells which.
+
+A version is Active when another step follows and it has no review or its report is Done;
+otherwise Draft. A step takes only prose or an Active artifact whose latest report is not
+Block. The state of a run is its files: `agiter continue` walks the steps again and repeats
+nothing done.
+
+## Try it
+
+```text
+agiter list tasks
+agiter plan --pipeline "create-draft:3,create-spec:2,create-work:1,checks" --text "Add a login form"
+agiter simulate --pipeline "create-draft:3,create-spec:2,create-work" --text "Add a login form" --script script.json
+agiter continue --root <project printed by simulate>
+```
+
+A simulation script says what the fake model returns, per task, role and attempt:
+
+```json
+{
+	"steps": {
+		"create-draft#1/review": { "findings": [{ "text": "Problem unclear" }] },
+		"create-draft#2": { "responses": { "F-1": "fixed: Problem rewritten" } },
+		"create-work": { "changes": ["src/login.js"] }
+	}
+}
+```