bareloop 0.0.1 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,204 @@
+# Changelog
+
+All notable changes to bareloop are documented here. Format:
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning:
+[SemVer](https://semver.org/spec/v2.0.0.html). Pre-1.0: **minor** = a ladder rung or
+feature lands, **patch** = docs, fixes, scaffolding.
+
+## [0.2.0] — 2026-07-12
+
+### Added
+- **N1 — the job/close schema (rung 2 of the ladder).** `validateJob` (`src/job.js`):
+  the operator-owned `job-v1` spec — the arbiter's rulebook as pure declarative data
+  (close chain, budget, outer write fence, environment label, escalation), validated
+  reds-before-tokens with pinned `code:path` reds. The arbiter split is guarded from
+  both sides by inexpressibility (workflow config can't say `close`/`provider`; job spec
+  can't say `hooks`/`loop`/`memory`, minting claims, or the shell-owned retry cap).
+  Close-authoring hierarchy (PRD §7) enforced as a class menu keyed by close type —
+  verdict-class laundering (`rubric` claiming `hard`) is a named red `close-hierarchy`.
+  `jobSpecHash` + `checkApproval`: the pure half of human-signs-always (sha256 over
+  canonical JSON; an edited spec is unapproved by construction; the N2 runner enforces).
+  Design record: `docs/plans/2026-07-12-n1-job-close-schema-design.md`; POC verdict: F4.
+- **Two-layer write fence.** `validateConfig` accepts `jobWriteScope` (the job spec's
+  operator-owned outer fence); every workflow scope must fit inside it — path-boundary
+  aware (`src2` is not inside `src`) — or it reds `scope-escape`. Same containment law,
+  same code, both layers (the F9 lesson).
+- **Reserved spine vocabulary: `coordination-red`** (V7, PRD v1.7 #1) — documented in
+  `bareloop.context.md`; no machinery until job #1 surfaces one.
+
+### Changed
+- **`validateConfig` returns `{ ok, reds, config }`** — the parsed config on ok, `null`
+  on any red; kills the interpreter's double-parse (N2+ queue item absorbed). Additive
+  for callers reading `ok`/`reds`.
+
+### Fixed
+- **Review hardening (post-build /code-review, 8 findings fixed + 6 sub-cap cleanups;
+  all fixes negative-tested and mutation-checked, zero feature regressions):**
+  cadence/escalation red unknown keys (the last smuggling level in a signed spec is
+  closed); the `jobWriteScope` fence opt fails CLOSED — a malformed fence is its own
+  `fence-invalid` red, never silently skipped, and each escaping scope reds at its own
+  indexed path (`gate.writeScope.N`); scope normalization moved into the shared
+  `globToPrefix` (leading `./`, interior `/./`, `//`, trailing `/` collapse) so a
+  validateJob-green fence like `src/` no longer deadlocks contained workflow configs;
+  `canon()` follows JSON semantics (undefined-valued keys dropped) so approvals survive
+  a disk round-trip, and `checkApproval` never throws (non-JSON spec → `false`);
+  `SECRET_RE` gained a left boundary (`flask-sqlalchemy` no longer reds) and the sweep
+  is shared by BOTH validators — the agent-authored workflow config is now swept too;
+  `interpret` accepts `jobWriteScope` and enforces the fence at the choke point (entry
+  + revision candidates); revision candidates are judged and installed on their PARSED
+  form (a JSON-string candidate no longer false-reds arbiter-touch); exported arbiter
+  menus are frozen; `isObj`/`isNonEmptyString` single-copied in `validate.js`.
+- **Second-round review (self-review of the hardening commit found a regression IT
+  introduced — all fixes TDD'd, mutation-checked, zero feature regressions):**
+  **critical containment escape** — the fence-normalization added to `globToPrefix`
+  stripped a leading `./` before collapsing `//`, so `.//src/**` minted the ABSOLUTE
+  prefix `/src`, validated green, and resolved outside the run directory at enforcement
+  (design law #1); fixed by collapsing `//`+`/./` first (so `.//src/**` → `src`, safe),
+  a belt in `scopeContained` rejecting any normalized-absolute prefix, and an enforcement
+  belt in `interpret` that refuses to build a Gate whose resolved scope escapes the
+  workdir. `canon()` now honors `toJSON` (a `Date` no longer hashes as `{}`; distinct
+  values no longer collide) and `jobSpecHash` never throws (the minting path the runner
+  calls directly is now crash-free on `BigInt`/cycles). `SECRET_RE` left boundary extended
+  to `-`/`_` (`pipeline-sk-transform-utils-v2` no longer false-reds; real keys still red).
+  `jobWriteScope: null`/`undefined` are the legitimate no-fence spellings (no more deadlock
+  on every config); a malformed fence reds `fence-invalid` at path `jobWriteScope`, not the
+  innocent workflow field (no ledger misattribution), with the detail bounded. Shared
+  `legalScopeEntry` gives the scope-legality law one home across all three call sites.
+- **Secrets never enter the spine (hard line), enforced at the source.** `runClose`
+  (`src/ralph.js`) scrubs close-command output the moment it is captured, so a secret a
+  checked command echoes (a 401 dumping a `Bearer …`/`sk-…` header) never reaches the
+  append-only spine or the next worker prompt. The redactor is injected (the shell stays
+  stdlib-only); `interpret` wires bareguard's exported `redact`. A benign gap is returned
+  byte-identical — the failure still reaches the human, just without the token (design
+  law #7 / V4 intact: the redactor is a fixed shell primitive, not an emergent component).
+- `NOTICE` ships in the tarball (npm auto-includes LICENSE/README but not NOTICE; Apache-2.0
+  wants both) — found validating the installed 0.1.0 artifact.
+- **Release-gate review (fresh `/security` + `/diff-review` on the whole release diff;
+  every finding execution-verified, every fix TDD'd):** the spine redactor now scrubs
+  **every shape the validator reds** — bareguard's defaults cover only `Bearer`/`sk-`,
+  so a git close echoing a `ghp_`/`github_pat_`/`AKIA`/`xox` token passed unredacted
+  into the append-only spine (the most plausible leak for job #1, a GitHub PR workflow);
+  `SECRET_PATTERNS` is now the one shape inventory shared by detection and redaction.
+  `interpret` normalizes `workdir` once at entry — a trailing-slash or relative spelling
+  made the enforcement belt false-red every legal scope — and the belt now treats a scope
+  resolving to the run dir itself as escaped. `checkApproval` no longer routes through the
+  un-hashable sentinel (two distinct un-hashable specs cross-approved each other; now
+  un-hashable = unapproved). The secrets sweep tests object **keys**, not just values (a
+  token could ride a key in a `gold` `expected` onto the spine through a green spec). A
+  non-object `cadence` reds once at `cadence`, not twice at paths that don't exist.
+
+## [0.1.0] — 2026-07-11
+
+### Added
+- **PRD addendum v1.5: the upstream ledger.** Auto-detected upstream fixes + user-facing
+  workflow debugging, derived purely from the spines: 8 lib-incident classes (test reds
+  and budget halts excluded by design — workflow stories never pollute the upstream
+  queue), signature-deduped counts, append-only state-as-fold, human-appended fix
+  lifecycle (the tool drafts, never files). Two audiences, one file: panel workflow
+  health (N6) and the maintainer's pre-drafted UPSTREAM-ASKS queue. New admission
+  obligation ~N2/N3: per-job known-answer `primitive-smoke` before tokens — the only
+  detector for silently-degrading primitives (adaptlearn A3 class). Spec + reference
+  implementation upstream in adaptlearn (validated: re-derived the menu-probe session's
+  incidents, zero false positives from ~100 close reds).
+- **F2 + PRD addendum v1.4: the menu probes return (adaptlearn F21/F22).** The v1.1 §4
+  graduated-disclosure open question RESOLVED: the registry gate is met (menu axis
+  wired-in; admission chain proven end-to-end) — the request-red registry builds ~N3/N4.
+  Author selection is cargo-cult (zero need signal; picks are a superset of need); need
+  reads off the ledger (within-run request-red frequency + outcome contrast); curation is
+  evidence-driven, never appetite-driven. New doctrine: partial retrieval poisons gap
+  attribution. N2 requirements filed: artifact-red category, fence-robust extraction.
+- **N0 — the token-free rung (PRD §10).** The five spine modules, rewritten from the
+  adaptlearn originals (graduation-is-a-rewrite): `src/spine.js` (append-only JSONL
+  emitter; seq monotonic, ts last), `src/ralph.js` (the dumb shell: close exit code =
+  truth, cap-halt its own category, decision-ready escalations), `src/validate.js`
+  (schema v1 predicate — named reds before tokens; litectx-bound vocabulary; `diffPaths`
+  one-knob checker), `src/interpret.js` (the only config reader; composes Gate + LiteCtx +
+  Loop; mid-run revision seam with interpreter-owned acceptance; emits `config-final` —
+  the run-as-executed record, design law #2), `src/extract.js` (rules distiller: one
+  sealed shot, bounds enforced mechanically, rejected whole). 70 tests carried from
+  adaptlearn's reference semantics, all hermetic and token-free (scripted stub providers).
+  Rigging per LIBRARY_CONVENTIONS: tsconfig (checkJs + strictNullChecks), `typecheck` /
+  `build:types` / `prepublishOnly` scripts, `.github/workflows/ci.yml`
+  (typecheck → build:types → test, no lint). Deps: litectx ^0.28.0, bareguard ^0.12.0,
+  bare-agent ^0.26.2. Code-review hardening (two rounds, all guards watch-it-fail
+  validated): writeScope **containment reds** (no absolute/Windows paths, no ".."
+  segments, not the run dir itself — a scope can never reach the arbiter's inputs,
+  design law #1); **verb placement tightened** — each verb legal only in its one
+  effective slot (recall/compress → before-attempt, stash → after-red, remember →
+  on-green; an inert-but-listed op is a fake knob in the contrast evidence, law #3);
+  **prototype-safe lookups** (`Object.hasOwn`) in the validator's param check and the
+  shell's escalation decision map; **silent-red gap sentinel** (a close that exits
+  nonzero with no output must not kill feedback/stall detection); spine **reserved-key
+  guard** (type/seq/ts are the envelope's, by mechanism); shared **`globToPrefix`** and
+  **`stripFences`** (`src/text.js` — one copy each, F9-class drift guards);
+  `extractRules` **never throws** (provider transport errors degrade to a
+  `provider-error` red as data); halt-as-return guard in `ask()` (bare-agent returns
+  `{error: 'halt:…'}` rather than throwing — forward armor for N2's tool loops); honest
+  cost emit (`metrics.costUsd ?? cost` — unpriced stays null, never a silent zero);
+  **package entry point** — `src/index.js` + `main`/`types`/`exports` map per
+  LIBRARY_CONVENTIONS §2 (the shipped `.d.ts` were previously unreferenced and the
+  package unimportable); a `CategorizedError` typedef and a `RecallHit` typedef replace
+  every `any`-cast (CLAUDE.md library-shape rule).
+- **F1 in `docs/FINDINGS.md`:** first `npm install` as a suite consumer surfaced two
+  upstream gaps (stale bare-agent peer range; GateDecision/Decision null-reason type
+  drift) — both fixed upstream and consumed via bare-agent 0.26.2, per two-red routing.
+  No shims.
+- PRD **addendum v1.3** + CYBERNETICS.md O1–O5: the orchestration position — not a second
+  runtime modality (credit attribution, accumulation, the arbiter — grounded in F15–F20);
+  convergence path is orchestrate-first-encounter → crystallize via run-as-executed
+  inheritance; admission only by pre-registered probe.
+- PRD **addendum v1.2**: the menu-breadth (graduated-disclosure) probe is assigned to
+  adaptlearn (successor-POC track, F19/F20 style) and returns to bareloop as findings;
+  the registry-gating separation requirement is unchanged.
+- PRD locked at **v1** (2026-07-11) after the bloat audit: §6→§9 open-questions dedup,
+  §4 secrets-never-enter-the-spine invariant, §5 mobile-responsive mandate. Amendments
+  from here are dated addenda, never rewrites.
+- PRD **addendum v1.1** (post-lock interview + adaptlearn cross-check): panel layout and
+  web-CLI command bar; full five-package primitive disclosure with the **two-red routing
+  rule** (locked-but-exists → in-loop registry admission; missing/broken → fix baresuite
+  and consume, never a local shim); **graduated-disclosure** open question pre-registered
+  with M3 discipline (minimal-menu vs +1-extra contrast must separate before the
+  request-red registry is built) — verified never exercised in adaptlearn.
+- Panel spec — **PRD Appendix A** (provisional; briefly `PANEL.md`, folded into the PRD
+  same day — one product doc): two panes (left chat + command bar speaking the exact
+  headless-CLI verbs; right progress/cost/step over results cards); primitive menu
+  grouped under recall / compress / stash / remember (provisional); context-graph third
+  view reserved (consumes litectx `ContextGraph` + the spine); mobile stacks; headless
+  first.
+- `.github/workflows/publish.yml` — npm trusted publishing (OIDC, no token), manual
+  dispatch, idempotent, asserts registry end-state.
+- `bareloop.context.md` — adopter contract per LIBRARY_CONVENTIONS §3 (draft; API
+  sections fill in as rungs land). `LICENSE` + `NOTICE` (Apache-2.0, matching the suite;
+  corrects the 0.0.1 placeholder's MIT declaration).
+- README rewritten in the bareagent shape: banner, badges, agent-first quick start,
+  layers/verdict tables, science table, ladder roadmap, ecosystem section.
+
+### Changed
+- `docs/UPSTREAM-ASKS.md` repurposed: upstream-gap **fix queue** only (we own baresuite —
+  fix-and-consume, version bump; request-red admissions resolve in-loop and never land
+  here).
+- Repo hygiene per LIBRARY_CONVENTIONS §7: `.claude/`, `.litectx/`, `.idea/` ignored and
+  de-tracked; `CLAUDE.md` stays tracked as the agent-doctrine file.
+- `package.json` takes the library shape: `"type": "module"`, Node `>=20` (bareguard's
+  floor governs), `files` ships `src/` + `types/` + the doc set (paths land at N0);
+  repository/homepage links to GitHub.
+
+## [0.0.1] — 2026-07-11
+
+### Added
+- **Repo cut** from the adaptlearn seed per the close-out plan (adaptlearn archived and
+  closed at v0.11.1 — the science behind this product).
+- **Named `bareloop`** (working dir renamed from the `looped` placeholder; `looped` and
+  `reloop` verified squatted on npm). Name reserved: `bareloop@0.0.1` published to npm —
+  README + package.json only, no code.
+- Seed docs: PRD (named, v0.2 at the time), design record
+  `docs/plans/2026-07-10-agentic-automation-successor-design.md` with the naming
+  resolution annotated, adaptlearn FINDINGS F1–F20 + CYBERNETICS.md carried as closed
+  records in `docs/00-context/`.
+- Scaffold: `CLAUDE.md`, fresh `docs/FINDINGS.md` (numbering starts at F1),
+  `docs/UPSTREAM-ASKS.md`, guardrails pre-tool hook (local), `.gitignore`.
+- Public GitHub repo `hamr0/bareloop`, `main` branch.
+
+[0.2.0]: https://github.com/hamr0/bareloop/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/hamr0/bareloop/compare/v0.0.1...v0.1.0
+[0.0.1]: https://github.com/hamr0/bareloop/releases/tag/v0.0.1

package/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

package/NOTICE

@@ -0,0 +1,13 @@
+bareloop
+Copyright 2026 hamr0
+
+This product includes software developed by hamr0
+(https://github.com/hamr0/bareloop).
+
+Licensed under the Apache License, Version 2.0 (the "License").
+You may obtain a copy of the License at:
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+This NOTICE file is required by Section 4(d) of the License.
+Forks and derivative works MUST preserve this attribution.

package/README.md

@@ -1,17 +1,129 @@
-# bareloop
+```
+                    ╭──────────────────────────────────────╮
+                    │  ╔╗ ╔═╗╦═╗╔═╗╦  ╔═╗╔═╗╔═╗            │
+                    │  ╠╩╗╠═╣╠╦╝╠╣ ║  ║ ║║ ║╠═╝            │
+                    │  ╚═╝╩ ╩╩╚═╚═╝╩═╝╚═╝╚═╝╩              │
+                    │    run ──→ verdict ──→ inherit       │
+                    │     ↑                     │          │
+                    │     └─────────────────────┘          │
+                    ╰──╮───────────────────────────────────╯
+                       ╰── workflows that earn their own design
+```
 
-> **Name reserved — product in design.** First release will be the headless loop (N0–N2).
+<p align="center">
+  <img src="https://img.shields.io/github/package-json/v/hamr0/bareloop?label=version&color=2a4f8c" alt="version (auto from package.json)">
+  <img src="https://img.shields.io/badge/license-Apache%202.0-2a4f8c" alt="license: Apache 2.0">
+  <img src="https://img.shields.io/badge/status-pre--code%20%C2%B7%20PRD%20locked-8a6d1a" alt="status: pre-code, PRD locked">
+</p>
 
-**"Automate this job — I don't know the best workflow."**
-
-bareloop is a system for tasks that are **repeated, long, and verifiable**: you describe the
-job and its checkpoints; an agent authors the workflow scaffolding (a constrained, validated
-config — never freeform code); runs execute under an un-gameable outer gate; and the
-scaffolding *improves across runs* through verdict-gated, run-as-executed inheritance with
-ledger-counted attribution.
+**"Automate this job — I don't know the best workflow."** For tasks that are **repeated,
+long, and verifiable**: an agent authors the workflow scaffolding (a constrained,
+validated config — never freeform code); runs execute under an un-gameable outer gate;
+and the scaffolding *improves across runs* through verdict-gated, run-as-executed
+inheritance with ledger-counted attribution.
 
 The pitch in one line: **workflows that earn their own design, with receipts** — every
 inherited rule carries the green that minted it and the contrast that attributed it.
 
-Built on the bare suite (bareagent, bareguard, litectx, barebrowse, baremobile). The science
-behind it: the adaptlearn experiment (v0.11.1), findings F1–F20.
+> **Status: pre-code.** The name is reserved, the PRD is locked, and the build ladder is
+> in flight (roadmap below). The first usable release is the headless loop.
+
+## Quick start
+
+```bash
+npm install bareloop
+```
+
+**Give your AI assistant the integration guide**
+
+```
+Read bareloop.context.md from node_modules/bareloop/bareloop.context.md
+```
+
+That single file is the complete adopter contract — the boundary, the architecture, the
+refusals, the constraints — and it grows API sections as rungs land. (Suite-wide pattern:
+every bare package ships its `*.context.md`.)
+
+---
+
+## How it works
+
+Three layers; nothing inside negotiates with the layer above it.
+
+| Layer | What it is | Emergent? |
+|---|---|---|
+| **Outer shell** | Per-run budget cap (bareguard), retry cap, verdict collection, escalation routing. Stateless across runs | never — permanent, dumb, un-gameable |
+| **Emergent middle** | The authored workflow config: steps, per-step verdict class, memory binding, write scopes — schema-validated, config-red before tokens burn | yes — authored and improved by the agent |
+| **Floor** | Append-only JSONL spine (single source for every UI), litectx store per job, per-run ledger | never — the record |
+
+Every checkpoint in a workflow carries its own **verdict class**, and the class decides
+what the run's learning is worth:
+
+| Verdict | Truth source | Mints inheritance? |
+|---|---|---|
+| **Hard green** | predicate / exit-code (tests, build, lint) | automatically |
+| **Soft green** | rubric / assessment | only with HITL confirm or N consistent repeats |
+| **HITL green** | a human is the close (PR merge, "publish") | yes — and merge stays human, forever |
+
+The full bare-suite surface is *disclosed* to the authoring agent; only *admitted* verbs
+are callable per job. A request against a locked primitive is a structured red — real
+diagnostic signal, and the admission path when it's justified.
+
+## The science behind it
+
+bareloop is the productization of **[adaptlearn](https://github.com/hamr0/adaptlearn)**
+(archived at v0.11.1) — a closed experimental record, findings F1–F20. What it settled,
+bareloop consumes without re-proving:
+
+| Mechanism | Evidence |
+|---|---|
+| Agents author valid harness configs at hand-written parity | M4 (F10) |
+| Mid-run revision recovers stuck runs | M5 (F11: 3/3 vs 1/3) |
+| Verdict-gated inheritance beats ungated on pass/fail | F19: gated late 1.00 vs ungated 0.13 |
+| Run-as-executed inheritance transmits in-run learning | F20: 6/6 lineages, ~½ cost |
+| Which-knob attribution is countable from the ledger | V2: contrast bit 16/16 gens |
+| Where memory pays: regularities outside the worker's prior | F17/F18: ~8× under acquisition cost |
+
+Full PRD with design laws and open questions: [`docs/01-product/PRD.md`](docs/01-product/PRD.md).
+
+## Roadmap — the build ladder
+
+Each rung POCs its riskiest assumption; a rung that cannot meet its exit stops the
+ladder, and the stop is a result.
+
+| Rung | What lands |
+|---|---|
+| **N0** | Port + outer shell + spine (token-free) |
+| **N1** | Job/close schema + validator |
+| **N2** | Single-job headless loop — job #1 minimal (review→fix→PR, hard greens only) |
+| **N3** | Executed inheritance + contrast-bit extractor — **kill-switch: rules must transmit across non-identical runs** |
+| **N4** | Verdict classes complete (soft/HITL minting) |
+| **N5** | Scheduler + budget ops |
+| **N6** | The panel ([spec](docs/01-product/PRD.md#appendix-a--panel-spec-provisional): left chat + command bar, right progress over results, context-graph reserved) |
+
+## The bare ecosystem
+
+Local-first, composable agent infrastructure. Same API patterns throughout —
+mix and match, each module works standalone. bareloop is the suite's flagship consumer:
+it exercises every package and gaps get fixed upstream, never shimmed.
+
+**Core** — the brain, the gate, the memory.
+
+- **[bareagent](https://npmjs.com/package/bare-agent)** — the think→act→observe loop. *Goal in → coordinated actions out.* Replaces LangChain, CrewAI, AutoGen.
+- **[bareguard](https://npmjs.com/package/bareguard)** — the single gate every action passes through. *Action in → allow / deny / ask-a-human out.* Replaces hand-rolled allowlists and scattered policy code.
+- **[litectx](https://npmjs.com/package/litectx)** — tree-sitter code + memory graph with activation decay, plus lightweight context engineering (write · select · compress · isolate). *Query in → ranked context out.*
+
+**Optional reach** — give the agent hands.
+
+- **[barebrowse](https://npmjs.com/package/barebrowse)** — a real browser for agents. *URL in → pruned snapshot out.* Replaces Playwright, Selenium, Puppeteer.
+- **[baremobile](https://npmjs.com/package/baremobile)** — Android + iOS device control. *Screen in → pruned snapshot out.* Replaces Appium, Espresso, XCUITest.
+- **[beeperbox](https://github.com/hamr0/beeperbox)** — 50+ messaging networks via one MCP server. *Chat in → unified message stream out.* Replaces Twilio, per-platform bot APIs.
+
+**Why this exists:** most automation stacks make you design the workflow before you know
+what works. bareloop's bet — proven in adaptlearn — is that for repeated, verifiable
+jobs, selection under an honest gate designs a better workflow than you would, and shows
+its receipts.
+
+## License
+
+Apache License, Version 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).