bareloop 0.0.1 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,124 @@
+# 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.
+
+## [Unreleased]
+
+## [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.
+
+[Unreleased]: https://github.com/hamr0/bareloop/compare/v0.1.0...HEAD
+[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/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).

package/bareloop.context.md

@@ -0,0 +1,115 @@
+# bareloop — Integration Guide
+
+> **DRAFT — pre-code.** bareloop is at the name-reservation stage; the API sections below
+> fill in as build-ladder rungs land (PRD §10). What is already settled — the boundary,
+> the architecture, the refusals, the constraints — is settled for good and recorded now.
+> Per LIBRARY_CONVENTIONS §3 this file ships with the package and is the complete adopter
+> contract; the README is only the pitch.
+
+## What this is
+
+**"Automate this job — I don't know the best workflow."** bareloop runs 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; the scaffolding improves across runs through
+verdict-gated, run-as-executed inheritance with ledger-counted attribution. Every
+inherited rule carries the green that minted it and the contrast that attributed it.
+
+## What bareloop is and is not
+
+- **Is:** a place where repeated, verifiable jobs get better at themselves — job model,
+  authored-workflow lineages, verdict classes, inheritance with receipts, a panel to
+  operate it.
+- **Is not:** a general agent, a swarm, or an orchestrator framework. One-off or small
+  jobs are out of scope — that's a CLI session, not a bareloop job.
+
+## Minimal usage
+
+*TBD at N2 (first headless single-job loop). Will show: define a job (description,
+checkpoints + verdict classes, budget, cadence, provider) → run → watch the spine.*
+
+## All options
+
+*TBD at N1 (job/close schema + validator lands). The schema is the option surface;
+config-red before tokens burn.*
+
+## Public API
+
+*Landed through N0 (spine + shell + validator + interpreter + extractor). Still TBD:
+N1 (job/close schema), N2 (headless job loop), N3 (contrast-bit extractor), N4 (verdict
+classes), N5 (scheduler + budget ops), N6 (panel).*
+
+### `makeSpine(file)` → `emit(type, data?)` — `src/spine.js`
+
+Append-only JSONL event emitter bound to one file. `seq` monotonic per spine, `ts` stamped
+last. Consumers are pure listeners; nothing reads the file back. Returns each event as
+written.
+
+### `ralph({ middle, close, capRuns, emit })` → `'green' | 'escalated'` — `src/ralph.js`
+
+The dumb outer shell: `while close-red and under-cap: run the middle`. `close` is an argv
+whose exit code is truth (`runClose` is also exported); the red gap text feeds the next
+iteration. Escalations are decision-ready (category, options, spend); cap-halt is its own
+category, never merged with "wrong". A thrown middle is relayed by its `category`
+property (`cap-halt`, `gate-red`, …); an unnamed throw is `interpreter-red`.
+
+### `validateConfig(input, { shellCapUsd? })` → `{ ok, reds }` — `src/validate.js`
+
+Deterministic schema-v1 predicate; never throws. Every failure is a named red
+`{ code, path, detail? }` — reds before tokens burn. Verb vocabulary bound from litectx
+(`LOOP_SHAPES`, `SLOTS`, `VERBS` exported). `diffPaths(a, b)` returns changed JSON paths —
+the one-knob mutation checker.
+
+### `interpret(configRaw, opts)` → `'green' | 'escalated' | 'config-red'` — `src/interpret.js`
+
+The only code that reads a config. Composes bareguard `Gate` (write scopes, USD budget),
+litectx (recall/compress/stash/remember hook ops), and the bareagent `Loop` under `ralph`.
+The provider and the close arrive from the shell, never the config. Optional `revisor`
+seam fires once after `STALL_REDS` consecutive close reds; the interpreter owns acceptance
+(arbiter-touch / cap-touch / validation reds). Emits `config-final` — the run-as-executed
+config (design law #2) — on every run.
+
+### `extractRules({ config, provider, priorRules, revisionDiff? })` — `src/extract.js`
+
+One sealed LLM call distilling a lineage's rules from ledger facts after a green run.
+`MAX_RULES`/`MAX_RULE_CHARS` bounds enforced mechanically post-call, rejected whole.
+Malformed output is a red as data (`rules: null`) — the caller keeps prior rules.
+
+## Architecture
+
+Three layers. An **outer shell** (dumb, permanent): per-run budget cap via bareguard,
+retry cap, verdict collection, escalation routing — stateless across runs; nothing inside
+negotiates with it. An **emergent middle**: the authored workflow config — steps, per-step
+verdict class, memory binding, write scopes — schema-validated. A **floor**: append-only
+JSONL spine (single source for every UI), litectx store per job, per-run ledger. Built on
+the bare suite: bareagent, bareguard, litectx, barebrowse, baremobile — the full surface
+is disclosed to the authoring agent; only admitted verbs are callable per job.
+
+## What's NOT in bareloop, and why
+
+- **No agent-authored arbiters.** Closes, budgets, caps, merge/publish decisions live
+  outside the emergent part, permanently — the product's trust story depends on the gate
+  being un-gameable (adaptlearn's no-breach record is the evidence).
+- **No freeform code as scaffolding.** Configs are schema-validated; config-red before
+  tokens burn.
+- **No self-adjusted budgets — ever.** Hard cap per run, cap-not-estimate.
+- **No swarm / orchestrator frameworks; one process per run.** Fewer moving parts is the
+  point of the name.
+- **No local shims over baresuite gaps.** A missing/broken primitive is fixed upstream in
+  its own package and consumed by version bump.
+- **Merge stays human, forever.** For repo jobs the PR is the escalation artifact; a
+  human is the close.
+
+## Gotchas
+
+*TBD from real adopter friction; recorded here as they're found (repo-side friction goes
+to `docs/FINDINGS.md`).*
+
+## Constraints
+
+- **Node >= 20** (bareguard's floor governs the suite).
+- **Pure ESM + JSDoc**; generated `.d.ts` ship, never hand-written (LIBRARY_CONVENTIONS §2).
+- **Secrets load from the environment** and never enter the spine, configs, or ledger —
+  an append-only record that captures a key captures it forever.
+- **The spine is append-only** and the single source of truth; every UI (panel included)
+  is a pure observer of it.

package/package.json

@@ -1,10 +1,47 @@
 {
   "name": "bareloop",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Workflows that earn their own design, with receipts — agent-authored workflows for repeated, long, verifiable jobs that improve across runs under an un-gameable gate.",
-  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "license": "Apache-2.0",
   "author": "hamr0",
-  "files": [],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test",
+    "typecheck": "tsc --noEmit",
+    "build:types": "tsc",
+    "prepublishOnly": "npm run build:types"
+  },
+  "dependencies": {
+    "bare-agent": "^0.26.2",
+    "bareguard": "^0.12.0",
+    "litectx": "^0.28.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hamr0/bareloop.git"
+  },
+  "homepage": "https://github.com/hamr0/bareloop#readme",
+  "files": [
+    "src/",
+    "types/",
+    "bareloop.context.md",
+    "CHANGELOG.md"
+  ],
   "keywords": [
     "agent",
     "workflow",