@staix/agent-research 0.0.0-stage → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+## Unreleased
+
+## [0.2.1] - 2026-11-08
+
+- Fix release clean-install smoke to compare installed schema versions with the checkout's FORMAT_VERSIONS, including study v2; an offline regression runs in the ordinary check (#88).
+
+- v0.2.0 was tagged but never published because its release smoke failed. This patch ships the fix without moving that tag.
+
+## [0.2.0] - 2026-11-07
+
+N-1 compatibility against 0.1.0, the latest published patch of the 0.1 minor line, checked by the `n1` CI job (`bun scripts/n1-check.ts`) on this release commit:
+
+- N-1 CLI: every 0.1.0 command and usage (57 commands) remains, and each usage keeps every 0.1.0 word in order. Changes are additive only: new commands (`autonomy show|set`, `study export`), new optional options and wider enums (`init --autonomy auto|gates|copilot|step`, `accept:<artifact>` gates).
+- N-1 MCP tools: every 0.1.0 tool (52 tools) remains with the same `readOnly` value. New tools are `ares_autonomy_show`, `ares_autonomy_set` and `ares_study_export`.
+- N-1 study/ledger formats: 0.2.0 reads 0.1.0-written survey and experiment studies and ledgers (status, gate list, autonomy show, lit/attempt list) without rewriting their bytes, and plain `auto|gates` studies stay study v1. 0.1.0 refuses two records only newer features write, each without changing the file: study v2 (object, `copilot` or `step` autonomy policies), with its unsupported-schema-version error, and plans whose nodes declare `phase`, with an unknown-field error. Ledger events stay version 1; `studyBundle: 1` is a new export format, not a study record.
+
+- N-1 CI check (#85 T1): a networked `n1` CI job, required by `ci-ok`, resolves N-1 from npm (the latest stable patch of the minor line directly below the checkout's major.minor core, whether or not the checkout is published), installs it into a temp prefix and fails on any removed N-1 command or usage word, removed MCP tool or flipped `readOnly`, on the checkout rewriting an N-1 study or ledger while reading it, or on N-1 not refusing a checkout study version it does not advertise (or not reading one it does) with bytes unchanged. On the initial publication line, with no previous minor, it prints an explicit skip and exits 0; registry and parse errors still fail. `bun run check` stays offline.
+
+- Study export scan (#83): every rule (path, URL, key-like, env) now runs on decoded JSON/JSONL keys and string values, so a raw newline or tab before a path, URL, key or env assignment can no longer hide it; refusal messages are unchanged.
+
+- Study export (#78): `study export <dir> --bundle DIR [--list]` on CLI/MCP writes a content-free dataset bundle (`manifest.json` with `bundle: 1`, studyBundle format, hashed study id, protocol hash, seal binding, window and counts; reduced `ledger.jsonl`; `attempts.jsonl`; `results.json` reduced to numbers, booleans, hashes, closed tokens and metric identifiers; `reviews.jsonl` counts; hash-only `evidence.json`) from committed study files only, into a new or empty directory. Paths, mounts, container ids, argv, env, images (digests kept) and free text are dropped, protocol-declared metric names/units and the selection metric stay as identifiers the dataset needs, guarded by the scan; and a scan refuses the whole export on any path, URL, env value or key-like token. N-1 effect: additive command, tool and output format; no existing CLI, MCP or study/ledger format changes.
+
+- Copilot acceptance (#52 T3): three aggregate ordinary gates bind hypotheses Markdown + idea journal, manuscript source tree (excluding derived paper/build), and the complete review journal. Only each producing phase's copilot mode enables its downstream guards; other modes retain their behavior. Producers and diagnostics remain usable for their own drafts; changed content stales acceptance, while rebuilds do not stale accepted paper source. Approval records any explicit actor without person-only rules, and never occurs automatically. Protocol/attempt/closed-investigation/paper/review/archive paths share the interlocks; plan refusals retain the exact approval next step without starting backend preparation. Existing study v2 plus v1 gate/ledger envelopes are used, with bounded regular-file source hashing and no new draft store.
+
+- Step autonomy (#52 T2): controller admission keeps step effects exclusive even with spare parallel slots; all terminal effect outcomes (including reconciliation) and a `plan.paused` (`reason: step`) receipt share one commit when work remains; gate nodes never pause. With no remaining work, the plan finishes done/failed without another resume, and failed CLI run exits nonzero. Durable `pauseReason` survives restart; explicit CLI/MCP resume continues the existing CLI controller, while MCP starts no controller. Detached admission and unchanged polls do not consume completion. Manual gate polling checks for effective auto candidates before taking a study lock.
+
+- Autonomy policy (#52 T1): `autonomy show|set` on CLI/MCP, four stored modes and phase overrides; only effective `auto` grants pending gates. One gate-to-phase table covers scope/screen/design/final/review; plan gates use a unique explicitly declared downstream phase, otherwise the default (including undeclared or hub targets). Policy edits preserve past decisions and record actor/from/to/phase in one commit. The controller reloads policy before approval; verified starts do not force an obsolete auto policy.
+
+- Format and N-1 effect (#5/#52): study v2 is required for the object form and copilot/step. The new reader keeps v1 support, plain auto/gates writers keep the v1 JSON layout, and v2 is never silently downgraded. Pre-policy 0.1.x readers, including published 0.1.0, refuse v2 with their existing unsupported-version error and preserve its bytes. Optional plan-node `phase` stays in plan v1; phase-free plans are unchanged, while the older strict 0.1.0 plan reader refuses this new field without rewriting it. Existing CLI/MCP operations remain, with additive policy tools; N-1 execution of the new v2 or phase-annotated records is not claimed. The next minor release must validate and state CLI, MCP and legacy-format N-1 separately under AGENTS.md.
+
+- CI/release (#69): one fail-closed `ci-ok` aggregate, non-cancelling main checks, exact-main-commit CI admission before release staging, scripted release preparation and annotated tagging, rerun-safe GitHub Release notes/assets with bounded 429/5xx retry, and one pinned checkout version. Release reuses the full CI result while retaining Ubuntu/macOS clean-prefix artifact smoke checks.
+
+## [0.1.0] - 2026-11-05
+
+- Phase A6 setup/console/watch (#51): dry-run client and API-1 console registration with receipts, conditional undo and versioned roots; an explicit private study registry; read panels and event-timed inboxes; and eight decision-level console actions with preview/fingerprint confirmation, person attribution and stale-input refusal. Read-only console mode blocks writes. Saved literature watches run one finite, study-locked pass, retain ordinary scope/screen rules and never score rubrics or screen automatically; recurrence is person-managed agent-hub task proposals or user cron. Malformed watch versions are repairable; safe-integer future versions remain unchanged. CLI/MCP share watch and registry operations; MCP watch runs always return detached admission {started:true,configSha256} after locked config/scope/year preflight and finish in the same responsive MCP process. Outcomes arrive in watch.ran/watch show; every-source failure is recorded as ok:false. A second start while locked refuses. CLI watch run and watch.run plan steps remain synchronous (exit 1/failed node on all-source failure). Manifest lists studyRegistry/watchConfig v1 and watch ledger events. Tests use synthetic records/fake HTTP/runners and pinned console conformance, with no live deployment/amem/vault claim. No resident watcher is included.
+
+- Phase A5 memory/evolution (#44): project-scoped amem lesson reads and half-life ranking; preview/fingerprint-confirmed archive batches with partial-success receipts; pivot cause/retryWhen; and a bounded, actor-recorded skill proposal queue. CLI/MCP share commands; manifest lists skillProposal v1 and the three A5 ledger kinds. Every playbook phase starts with intent lessons and archive is the last study step. Survey supports lessons/archive/skills, with experiment-only sources still refused. Tests use synthetic records and fake runners, no network, real amem or vault writes; live interoperability is not claimed. Vault promotion stays in amem, and ares never opens/checks/merges proposal PRs.
+
+- Fix local macOS executor log collection with binary xattrs: content-only log archives now exclude xattrs and AppleDouble files while preserving original file attributes, strict parsing and capture limits (#30).
+
+- Phase A1 (#2): study ledger with approval gates, scope, literature search across OpenAlex, Semantic Scholar and arXiv with merging, screening, extraction cards, identifier verification at Crossref, DataCite and arXiv, BibTeX generation with stable citekeys, citation check for drafts, and a stdio MCP server with the same operations.
+- Phase A2 (#4): local/SSH Docker execution of frozen Git commits, a design gate binding protocol and evaluator task files, separate isolated non-root candidate/evaluator containers, evaluator-only finite metrics, attempt identity/retry/reconcile/cancel, wall-clock enforcement and budgets across every status. CLI and MCP include executor checks, paged attempt summaries and read-only host log retrieval. Study records hold ares-observed evidence and artifact metadata only; signed receipts remain deferred. Offline fixtures and separate dgx live proof cover isolation, commit selection, log truncation and archive containment.
+- Phase A3 plan DAG (#6): revisioned bounded step/hub/gate definitions, ledger-derived readiness and stale propagation, durable command-id controls, upstream-output plan gates and CLI-only `ares run`. The controller restores paused, fences ownership by pid/host/process start, reconciles interrupted work without implicit replay, admits parallel steps while preserving one active attempt, and backs off observations. Hub nodes only read campaign/unit task references, wait for activation/approval, retain task bindings across restarts and expose read errors plus the resolved board. MCP set/show/control never starts the controller loop.
+- Phase A3 investigate (#25): a sealed selection rule, ledger-only ideas with evidence-backed refine/pivot decisions and unique commit ownership, current-protocol counting after the selection cutoff, paired-seed delta ranking and named winner/no-winner outcomes. Read-only show and deterministic close retain all run statuses/exclusions; unchanged close writes nothing. CLI/MCP operations and the no-argument `investigate.close` plan step share the result, whose `{sha256, winner}` reference binds downstream gates. Tests are offline synthetic fixtures; no live hub or executor DAG proof is claimed. Automatic idea generation, significance tests and concurrent attempts remain out of scope; amem export is provided by A5.
+- Phase A3 ablate/final/posthoc (#32): unused reserved seeds join the design seal, declared ablations pair against fresh winner replications without ranking, and a content-bound final gate authorizes one-shot reserved-seed evaluation. First attempts remain decisive across retries and reapproval; changed winners cannot buy a second final. Deterministic final close records qualified/not_qualified with named reasons; posthoc requires historical final closure and keeps all metrics exploratory without changing final inputs. CLI/MCP, manifest formats and no-argument `ablate.close`/`final.close` plan steps expose committed result hashes and statuses for downstream gates. Acceptance uses offline fixtures; held-out evaluator data and significance tests remain deferred.
+- Phase A4 paper and review (#38): closed-result numeric placeholders, reviewer-visible literals/code numbers, positioned paper checks with citation verification and mandatory negative-result prose, deterministic Markdown/evidence builds, and build-bound review records with reasoned resolutions. The review gate needs a current clean build, two distinct self-reported model families and no open blocking finding; contradictions cannot be voted away. CLI/MCP and a no-argument `paper.build` plan step share the committed evidence hash; manifest lists paperEvidence v1. Survey papers use citation-only checks and refuse experiment refs. Offline fixtures only; claim-passage evidence awaits agent-hub#931, and automatic writing/reviewing plus LaTeX/PDF builds remain out of scope.
+- Compatibility (#5 AC2/AC3): read-only `ares manifest --json` and MCP `ares_manifest` publish the package, command and implemented shared-format versions. Additive study/ledger/attempt fields and unknown ledger kinds survive reads and subsequent writes; unsupported versions or execution semantics refuse without rewriting data. Unknown stage entries remain readable but block budget-gated starts until a compatible version can account for them. A6 adds `ares setup` and versioned-root registration. This is the initial publication, with no prior published minor line; no N-1 compatibility claim is made yet for CLI, MCP tools or study/ledger formats. N-1 CI checks begin with the next minor release, against the latest published patch of this minor line. Release compatibility instructions are in `AGENTS.md`.
+
+- Release readiness: tag/version and dated changelog validation, Ubuntu/macOS checks, staged tarball hash verification and clean-prefix CLI/manifest/MCP smoke checks. Publication is gated on `NPM_PUBLISH_ENABLED=true` and `npm-production` approval, using npm OIDC provenance for the validated Linux artifact. Actual tagging, trusted-publisher configuration and publication remain owner steps after merge.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 STAIx Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.