Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@
# Agent instructions

**Implementing anything in this repository? Read `NEXT_IMPLEMENTATION_PLAN.md` first.**
It is the canonical "what to build next" document: pick the highest-priority unblocked task from
its Progress Ledger (§7), follow its operating rules (§2), and update the ledger row when you
finish. Do not start new workstreams that are not in that plan without a decider note.
**Implementing anything in this repository? Start from an explicitly scoped issue, PR, or decider
request.** For release-specific work, read the current `docs/v<version>-release-prep.md` before
writing code. Do not infer a new public surface or workstream from historical planning records.

Other authoritative context, in reading order:

1. `NEXT_IMPLEMENTATION_PLAN.md` — active plan, task ledger, guardrails.
1. The scoped issue, PR, or decider request; for a release train, its
`docs/v<version>-release-prep.md`.
2. `docs/execution-status.md` — current release state and explicit blockers.
3. `README.md` + `docs/public-boundary-claims.json` — approved public wording; never edit claim
strings without the approval lane.
4. `SPEC.md`, `docs/determinism-contract.md`, `docs/decisions/` (ADRs) — contracts and decisions.
5. `IMPLEMENTATION_PLAN.md`, `docs/roadmap.md` — historical milestone plan and closeout record.
5. `docs/roadmap.md`, `IMPLEMENTATION_PLAN.md` — public direction and historical milestones.

Hard rules that apply to every change: determinism is a contract (byte-identical output under a
pinned profile — add double-run tests for new artifacts); fail closed on missing capability;
Expand Down
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@

## Unreleased

- boundary-exception: retire the completed temporary next-implementation ledger and kickoff
prompt, move v0.4.0 publication tracking wholly into the accepted release-prep/closeout lane,
and remove active-plan wording from the validation index and accepted PDFium install record
while preserving their historical evidence IDs and conclusions.
- release: begin v0.4.0 post-merge finalization, reconcile the dropped MCP and deliberately
skipped Windows publication boundaries, and record approved bounded release-note wording
without changing currently approved public install claims.
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ no CLA). CI checks everything else automatically and tells you what to fix.

Good entry points: fixture contributions (`fixtures/README.md`), issues labeled
`good-first-issue`, framework adapters (`adapters/`), and docs fixes. If you're an AI agent,
read `NEXT_IMPLEMENTATION_PLAN.md` and pick a ledger task.
read `AGENTS.md` and work only from the explicitly scoped issue, PR, or decider request.

## Ideas and design changes

Expand Down
515 changes: 0 additions & 515 deletions NEXT_IMPLEMENTATION_PLAN.md

This file was deleted.

Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Implementation Plan: Citation Emission Spec v1 and Verification Attestation v1

Status: Part A implemented by NIP-4.1 on 2026-07-19; Part B remains a proposal. Follows the
Status: Part A implemented on 2026-07-19; Part B remains a proposal. Follows the
milestone-d contract pattern.
Companion to `docs/derived-value-v1-and-normalization-v2-implementation-plan.md`; neither
part here depends on that plan, and the two parts here are independent of each other.
Expand Down Expand Up @@ -407,7 +407,8 @@ Open questions to resolve before implementation, not silently:
1. Report `schema_version` discipline for the additive `attestation` field — align with
the derived-value plan's identical question against `docs/v0-2-x-compatibility-policy.md`.
2. Keep or drop the constant `replay` string field (§B.2) — pure taste, decide in review.
3. Resolved by NIP-4.1: source IDs are bounded non-blank strings in the model-facing schema;
3. Resolved by the implemented citation-emission contract: source IDs are bounded non-blank
strings in the model-facing schema;
hydration applies the selected `GroundingSource` namespace. DocuShell's concrete
OpenDataLoader integration showed that a native-only schema would require contract forks and
violate the parser-agnostic-first rule.
Expand Down
4 changes: 2 additions & 2 deletions docs/decisions/ADR-0015-opt-in-bundled-pdfium-artifacts.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
## Context

The base crates, wheel, npm package, and current CLI archives keep PDFium caller-provided under
ADR-0013. NIP-5.1 reduced setup to a pinned fetch command, but a user must still install PDFium,
ADR-0013. The pinned fetch command reduced setup friction, but a user must still install PDFium,
export its path, and retain the runtime beside Ethos. That remains an obstacle between a fresh
install and a first parse.

Expand Down Expand Up @@ -71,7 +71,7 @@ runtime path, or an archive/runtime hash mismatch are fatal.

## Evidence and Size

NIP-5.2 feasibility evidence is recorded in
Feasibility evidence is recorded in
`docs/validation/nip-5-2-ethos-full-build-evidence-2026-07-20.md`. Using the published `0.3.0`
CLI binaries as packaging fixtures and the pinned Phase 1 runtimes produced:

Expand Down
19 changes: 10 additions & 9 deletions docs/execution-status.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,35 +16,36 @@ inside them describe their recorded point in time and are not the current releas
generated block explicitly repeats them. Candidate source metadata is currently `0.4.0`, while the
published public baseline remains `0.3.0`.

The NIP-1 DocuShell first-consumer integration closeout is accepted in
The DocuShell first-consumer integration closeout is accepted in
`docs/validation/nip-1-docushell-integration-closeout-2026-07-20.md`. The worker-only public CLI,
foreign-grounding verification, answer-release, and crop-inspection lanes passed focused and real
born-digital PDF acceptance. This clears the current DocuShell integration blocker without making
DocuShell adoption, production, parser-quality, or semantic-truth claims.

NIP-3.2 internal judge evidence is durably retained in the sibling `ethos-bench` repository at
Internal judge evidence is durably retained in the sibling `ethos-bench` repository at
merge `a733411`, with the exact live result hash, coverage, internal-only state, and credential
field audit guarded by its local suite. Per the active plan's v1.5 decider clarification,
field audit guarded by its local suite. Per the 2026-07-20 decider clarification,
`ethos-bench` workflow automation is deferred and does not gate Ethos delivery. Public benchmark
reports, comparative wording, and all associated claims remain governed by the existing Ethos
claim-audit and public-wording boundaries.

NIP-3.3's internal Ethos-versus-judge comparison is merged in `ethos-bench` at `5945fce`. It
The internal Ethos-versus-judge comparison is merged in `ethos-bench` at `5945fce`. It
contains a source/binary-bound Ethos 0.4.0 baseline, confusion matrices, grounded/ungrounded
precision and recall, cost per 1,000 citations, descriptive latency variance, category cells, and
deterministic report evidence. The measurements remain internal; different latency environments
support no speed claim, and NIP-3.4 claim audit plus the public-wording lane still control any
support no speed claim, and the claim audit plus public-wording lane still control any
external comparative wording.

NIP-3.4's internal claim-audit packet is merged in `ethos-bench` at `9287671`. It is generated
from the complete NIP-3.3 comparison and retains all three confusion matrices, all 21 category
The internal claim-audit packet is merged in `ethos-bench` at `9287671`. It is generated
from the complete comparison and retains all three confusion matrices, all 21 category
cells, and source/binary/input hashes while excluding cross-environment latency, local-compute
cost comparisons, rankings, semantic-truth, parser-quality, speed, footprint, and production
claims from proposed wording. All 50 sibling tests, smoke commands, hash binding, and
byte-identical regeneration pass on the merged tree. This closes the internal NIP-3 workstream,
byte-identical regeneration pass on the merged tree. This closes the internal benchmark workstream,
not the public-wording lane: no approved public claim string or publication state has changed.

NIP-5.3 and NIP-6.1–6.2 completed their remote validation on PR #223 source `a9c1ced`. Release
The Windows verify-only implementation and CI Action completed remote validation on PR #223
source `a9c1ced`. Release
run `29728642038` produced byte-identical Windows verify-only candidates and passed real `.exe`
smoke plus inventory validation; determinism run `29728692721` passed the verification matrix on
macOS, Linux, and Windows. PR CI run `29728324553` passed the checksum-pinned released-CLI Action
Expand Down
34 changes: 17 additions & 17 deletions docs/integrations/docushell.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Integration Contract: DocuShell (first consumer)

Status: active. Created: 2026-07-19. Plan reference: `NEXT_IMPLEMENTATION_PLAN.md` §NIP-1.
Status: active. Created: 2026-07-19. Integration closeout accepted 2026-07-20.
This document is the template for future `docs/integrations/<consumer>.md` files.

## Why this document exists
Expand All @@ -18,8 +18,9 @@ surface, that is an Ethos product gap — it goes into the
`docling-fast`), plus the evidence layer in `packages/evidence`.
- DocuShell currently mirrors Ethos verification-report and answer-release types in TypeScript
(`packages/evidence/src/ethos-answer-release.ts`, `openai-chat-evidence.ts`) and implements
the release policy from `docs/app-answer-release-contract.md`. NIP-4.5 adds schema-generated
declarations to the v0.4.0 npm candidate so that mirror can be retired after publication.
the release policy from `docs/app-answer-release-contract.md`. The v0.4.0 candidate adds
schema-generated declarations to the npm candidate so that mirror can be retired after
publication.

## Surfaces DocuShell consumes (all public)

Expand All @@ -38,14 +39,14 @@ Pinned versions (update on every DocuShell bump):

| Item | Version | Pinned at |
| --- | --- | --- |
| `ethos` CLI artifact | v0.3.0 (Linux x64) | 2026-07-19 — vendored in the DocuShell parse-pdf worker image (NIP-1.2, `docker/parse-pdf/ethos-vendor.json`) |
| `ethos` CLI artifact | v0.3.0 (Linux x64) | 2026-07-19 — vendored in the DocuShell parse-pdf worker image (`docker/parse-pdf/ethos-vendor.json`) |
| PDFium (caller-provided) | `chromium/7881` (PDFium 151.0.7881.0, Linux x64) | 2026-07-19 — installed by the same image, `ETHOS_PDFIUM_LIBRARY_PATH` set at build |
| Report schema | as shipped in v0.3.0 | 2026-07-19 |
| Grounding adapter | `opendataloader-json` | 2026-07-19 |
| Citation emission callback | v1.0.0 (not yet consumed) | 2026-07-19 — frozen by NIP-4.1; Python helpers delivered by NIP-4.2 |
| TypeScript declarations | v0.4.0 candidate (not published) | 2026-07-19 — generated and package-tested by NIP-4.5; DocuShell adoption waits for the human-operated npm release |
| Citation emission callback | v1.0.0 (not yet consumed) | 2026-07-19 — frozen contract with delivered Python helpers |
| TypeScript declarations | v0.4.0 candidate (not published) | 2026-07-19 — generated and package-tested; DocuShell adoption waits for the human-operated npm release |

### Consumer Dockerfile pattern (from the NIP-1.2 integration; friction entry FR-3)
### Consumer Dockerfile pattern (friction entry FR-3)

DocuShell vendors both artifacts in a dedicated build stage with sha256 pins duplicated into a
consumer-side manifest (`docker/parse-pdf/ethos-vendor.json`), verified before extraction and
Expand All @@ -72,9 +73,8 @@ ENV ETHOS_PDFIUM_LIBRARY_PATH=/opt/ethos/pdfium/lib/libpdfium.so

Pins to duplicate into the consumer manifest: the CLI release-asset and binary sha256 values
(the same values recorded in `packages/npm/ethos-pdf/vendor/manifest.json`) and the PDFium
archive/library sha256 values from `docs/pdfium-profile.md` / `scripts/fetch-pdfium.sh`. Until
NIP-5 ships `ethos doctor` and a published pin manifest, consumers must re-sync these by hand on
every version bump (friction entries FR-2/FR-3/FR-4).
archive/library sha256 values from `docs/pdfium-profile.md` / `scripts/fetch-pdfium.sh`.
Consumers must re-sync these pins by hand on every version bump (friction entries FR-2/FR-3/FR-4).

## Compatibility promise (Ethos → DocuShell and all consumers)

Expand All @@ -95,7 +95,7 @@ every version bump (friction entries FR-2/FR-3/FR-4).
- Reports are stored with the job record so status/download routes can serve them under the
existing ownership/expiry checks; crop artifacts follow DocuShell's retention/purge windows.

### Parse-job verification lane (NIP-1.3)
### Parse-job verification lane

After OpenDataLoader produces JSON, the parse worker deterministically projects its selected
evidence refs into quote/table-cell citations and runs the public CLI with
Expand All @@ -113,7 +113,7 @@ The worker stores only the canonical report as a companion artifact; its checks
submitted claims, and the deterministic citation input is tested byte-identically across runs.
This verifies citation grounding, not the semantic truth of parser text.

### Answer-release gate (NIP-1.4)
### Answer-release gate

The server-owned Evidence Chat answer path derives `proof_summary` from the canonical Ethos
report, maps reusable check IDs back to stable application claim IDs, and then applies
Expand All @@ -133,7 +133,7 @@ The DocuShell fixture test reproduces the checked-in Ethos
byte-identical JSON across two runs. The canonical verification report remains the grounding
audit artifact; the answer-release envelope records application policy above it.

### Crop inspection lane (NIP-1.5)
### Crop inspection lane

Evidence-required parse jobs render inspectable citation crops while the original PDF is still
available in the parse worker. Because the public `crop_element` contract accepts native Ethos
Expand Down Expand Up @@ -163,11 +163,11 @@ The integration test runs crop production twice over identical inputs and compar
bundle bytes, checks request-reference compatibility with Ethos's committed schema example, and
covers partial mapping plus missing-PDFium failure behavior.

## Sequenced work
## Integration history

Tracked in `NEXT_IMPLEMENTATION_PLAN.md` §NIP-1 (NIP-1.2 vendored CLI → NIP-1.3 verify lane →
NIP-1.4 answer-release gate → NIP-1.5 crop inspection → NIP-1.6 friction log → NIP-1.7
closeout). DocuShell-side tickets should mirror these IDs.
The vendored CLI, verification lane, answer-release gate, crop inspection, friction log, and
closeout were completed in sequence. The dated validation record retains their historical task
IDs and evidence bindings.

## Friction log process

Expand Down
81 changes: 0 additions & 81 deletions docs/prompts/nip-kickoff.md

This file was deleted.

16 changes: 8 additions & 8 deletions docs/release-lane-v2.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Release Lane v2 (NIP-7.1)
# Release Lane v2

Status: **Accepted** (2026-07-19, decider direction: keep the process smooth end-to-end).
Created: 2026-07-19. Owner: product / decider. Plan reference: `NEXT_IMPLEMENTATION_PLAN.md` §NIP-7.
Created: 2026-07-19. Owner: product / decider.

**Smoothness rule:** a routine release train never waits on ceremony. When the prep doc's gate
checklist is green, the train ships. The only human moments in the pipeline are PR review, the
Expand Down Expand Up @@ -66,13 +66,13 @@ outside one.

## Pilot

The next release train (carrying NIP-5 install-friction work and any landed NIP-1/NIP-4
deliverables) is the pilot (NIP-7.2). Success criteria: exactly two governance documents, no
loss of evidence quality (closeout contains per-surface versions, hashes, and commands), decider
review time reduced.
The v0.4.0 release train is the pilot. Success criteria: exactly two governance documents, no
loss of evidence quality (the closeout contains per-surface versions, hashes, and commands), and
reduced decider review time. Publication is tracked in `docs/v0-4-0-release-prep.md` and its
eventual single closeout record, independently of any feature-planning ledger.

## Decider sign-off

- [x] Accepted: 2026-07-19, per decider direction recorded in NIP-1 revision v1.2 (process must
stay smooth from idea to release; no ceremony blockers).
- [x] Accepted: 2026-07-19, per decider direction that the process stay smooth from idea to
release without ceremony blockers.
- [ ] Amendments required: —
Loading
Loading