From 46be04d4c4101ed0fef9028e9a9dd39833a4a6d0 Mon Sep 17 00:00:00 2001 From: docushell-admin Date: Mon, 20 Jul 2026 15:02:54 +0530 Subject: [PATCH 1/2] docs: retire next implementation plan Signed-off-by: docushell-admin --- AGENTS.md | 12 +- CHANGELOG.md | 3 + CONTRIBUTING.md | 2 +- NEXT_IMPLEMENTATION_PLAN.md | 515 ------------------ ...pec-and-attestation-implementation-plan.md | 5 +- ...DR-0015-opt-in-bundled-pdfium-artifacts.md | 4 +- docs/execution-status.md | 19 +- docs/integrations/docushell.md | 34 +- docs/prompts/nip-kickoff.md | 81 --- docs/release-lane-v2.md | 16 +- docs/roadmap.md | 5 + docs/v0-4-0-release-prep.md | 25 +- docs/validation/README.md | 16 +- ...nip-5-1-pdfium-install-smoke-2026-07-19.md | 3 +- docs/windows-verify.md | 4 +- fixtures/README.md | 2 +- fixtures/trust-benchmark/generate.py | 2 +- python/README.md | 2 +- 18 files changed, 85 insertions(+), 665 deletions(-) delete mode 100644 NEXT_IMPLEMENTATION_PLAN.md delete mode 100644 docs/prompts/nip-kickoff.md diff --git a/AGENTS.md b/AGENTS.md index f928f2c6..cc97de6e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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-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-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; diff --git a/CHANGELOG.md b/CHANGELOG.md index 2c137070..4ee69f39 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,9 @@ ## Unreleased +- planning: 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 direct new + work through explicit issues or decider requests while preserving historical evidence IDs. - 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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 228c59cd..b0d90424 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 diff --git a/NEXT_IMPLEMENTATION_PLAN.md b/NEXT_IMPLEMENTATION_PLAN.md deleted file mode 100644 index 8d96c644..00000000 --- a/NEXT_IMPLEMENTATION_PLAN.md +++ /dev/null @@ -1,515 +0,0 @@ -# Ethos Next Implementation Plan (NIP-1) - -Status: **active — this is the canonical "what to build next" document.** -Created: 2026-07-19. Revised: 2026-07-20 (v1.6). Owner: product / decider. -Supersedes nothing; complements `IMPLEMENTATION_PLAN.md` (historical milestone plan A–F) and -`docs/roadmap.md` (milestone/closeout record). Where those documents describe *how Ethos got -here*, this document describes *what to do next and in what order*. - -> **If you are an AI agent or engineer opening this repository to implement something: start -> here.** Read §0 (how to use this document), §2 (operating rules), then pick the highest-priority -> `not_started` task in the Progress Ledger (§7) whose dependencies are `done`. Do not invent new -> workstreams before the P0 set is complete. - -Revision v1.1 (2026-07-19, decider): `ethos-mcp` (NIP-2) deprioritized P0 → P2 — do not start it -before P0/P1 are complete. Citation emission (NIP-4) and install-friction (NIP-5) promoted to P0. -Execution model switched to AI-agent implementation with human review (§6.0); estimates added to -the ledger. NIP-1.1 delivered; NIP-1.6 and NIP-7.1 started (see ledger). - -Revision v1.2 (2026-07-19, decider): **smoothness rule adopted** (§2 rule 9) — from idea to -release there are exactly three human gates (PR review, registry publish, public-wording -changes); everything else is automated CI, and nothing waits on ceremony. Release Lane v2 -accepted (NIP-7.1 done). `CONTRIBUTING.md` rewritten as the single idea-to-release process page -with an external-contributor fast path (NIP-7.3 done). "Blocked" in historical docs is -reinterpreted: honesty gates (no unearned claims) remain as automated checks; approval-queue -blockers are retired. - -Revision v1.3 (2026-07-20, decider): NIP-5.1 validation accepts the committed isolated macOS -`env -i` install smoke in place of a clean-VM transcript. Platform-specific artifact tasks retain -their own target-platform validation requirements. - -Revision v1.4 (2026-07-20, corrective audit): source metadata state is reconciled after v0.4.0 -candidate activation; NIP-3.2–3.4 are reopened pending durable raw evidence and the full promised -Ethos-versus-judge metrics; NIP-6.1–6.2 are returned to `in_progress` until their branch commits -pass remote CI. Routine release gates are distinguished from separately authorized benchmark -spend, ADR, and public-claim decisions. - -Revision v1.5 (2026-07-20, decider): `ethos-bench` workflow automation is explicitly deferred and -does not gate Ethos delivery. Merged, reviewed sibling evidence plus the required local validation -is sufficient for sibling-owned benchmark tasks until that repository adopts workflows. NIP-3.2 -is complete at `ethos-bench` merge `a733411`; NIP-3.3 becomes the active P0 implementation task. - -Revision v1.6 (2026-07-20, decider): the remaining P2 workstreams — `ethos-mcp` (NIP-2), the -WASM verify playground (NIP-8), and scanned-document adapters (NIP-9) — are dropped from this -implementation plan. They are neither implemented nor approved; each may be reconsidered only -through a future release-planning decision with fresh scope and priority. - ---- - -## 0. How to use this document - -### 0.1 For AI agents and implementing engineers - -1. Read §2 (operating rules) fully before writing code. They are non-negotiable repo invariants. -2. Open the Progress Ledger (§7). Select the first task that is `not_started` or `in_progress`, - ordered by priority (P0 → P1 → P2), whose `Depends on` entries are all `done`. -3. Implement against the task's **Acceptance criteria** and **Validation** commands in §5. An - Ethos-repository task is not done until every listed validation command passes locally and in - Ethos CI. Sibling-owned benchmark tasks follow the sibling repository's current process: - reviewed merge plus required local validation is sufficient while `ethos-bench` workflows are - deferred. Adding sibling workflows is future maintenance, not an Ethos roadmap dependency. -4. **Update the Progress Ledger row when you finish**: set status, date, and an evidence link - (PR, validation record, or command output committed under `docs/validation/`). This is - mandatory — the ledger is the single source of truth for NIP-1 progress. Stale ledgers are - treated as bugs. -5. If you are blocked, set the row to `blocked`, add one line describing the blocker in the - ledger's Notes column, and stop rather than working around a guardrail. -6. Keep CHANGELOG discipline: every landed task adds one entry under `## Unreleased` in - `CHANGELOG.md`, in the existing house style. - -### 0.2 Status vocabulary - -`not_started` · `in_progress` · `blocked` · `done` · `dropped` (requires a decider note). - -### 0.3 What this document does NOT approve - -Consistent with `docs/execution-status.md` and the claims gates: this plan approves engineering -work and internal evidence gathering only. It does **not** approve public benchmark claims, -speed/footprint/parser-quality/table-quality claims, hosted production surfaces, production -positioning, Windows packaged artifacts, bundled project-maintained PDFium distribution, or any -change to approved public wording in `README.md` / `docs/public-boundary-claims.json`. Public -wording changes continue to require their own approval lane. Nothing here weakens that. - ---- - -## 1. Context snapshot (2026-07-19) - -What exists and is shipped: - -- v0.3.0 public beta evaluation surfaces: source repo; crates `ethos-doc-core`, `ethos-verify`, - `ethos-pdf`; PyPI wheel `ethos-pdf==0.3.0`; npm `@docushell/ethos-pdf@0.3.0`; macOS arm64 and - Linux x64 CLI artifacts. PDFium is caller-provided via `ETHOS_PDFIUM_LIBRARY_PATH`. -- The working trust loop: `ethos doc parse` → chunks/citations → `ethos verify - --fail-on-ungrounded` → `ethos crop_element` → `ethos evidence anchor`, deterministic and - golden-tested (`make verify-alpha`). -- The OpenDataLoader-style JSON grounding adapter (foreign-parser verification path). -- v0.4.0 release train (`docs/v0-4-0-release-prep.md`): the accumulated next-minor verification, - citation-emission, integration, adoption-tooling, and governance work. Candidate source metadata - is activated at `0.4.0`, while public install wording and published artifacts remain at `0.3.0` - until the release gates pass. The prep note explicitly excludes the P2-gated MCP prototype from - activation and publication. - -What is honestly true about adoption: registry downloads are at mirror-bot baseline, there are no -known external users, and there is one maintainer (ADR-0001). The strategy below is written for -that reality. - -Empty surfaces reserved but unbuilt: `crates/ethos-mcp` (deprioritized to P2 by decider decision -2026-07-19), `crates/ethos-rag` (no NIP workstream; do not start), Node beta. - ---- - -## 2. Operating rules (guardrails — read before any task) - -1. **Determinism is a contract.** Same input + same pinned profile ⇒ byte-identical canonical - payload and fingerprints. Every new surface (Action, adapters, emission helpers) must preserve - this and add determinism tests (double-run byte-diff) for any new artifact it emits. -2. **Fail closed.** Missing capability ⇒ explicit `capability_limited` downgrade, never a silent - pass. New surfaces must map errors to the stable exit-code/error-envelope contract - (see `docs/milestone-d-capability-downgrade-contract.md`, PRD §10). -3. **Claims gates stay green.** `.github/scripts/public_boundary_claims_gate.py` must pass on - every PR. Do not edit approved claim strings. No ranking/superlative claims anywhere, - including code comments and examples (PRD §11.3). -4. **Scope honesty.** Ethos verifies *citation grounding*, not semantic truth. Every new doc, - demo, or integration repeats this boundary where a user could confuse the two. -5. **Licensing:** no AGPL dependencies (ADR-0004). PDFium stays caller-provided in the base - install until a decider accepts a bundling ADR (ADR-0013). -6. **Parser-agnostic first.** New verification features must work over `GroundingSource`, not - only the native parser (ADR-0007). If a feature only works natively, it must degrade with an - explicit capability warning on foreign sources. -7. **Governance right-sizing (NIP-7):** use **one prep note + one closeout record per release** - per `docs/release-lane-v2.md` (accepted 2026-07-19), not per-artifact lanes. Keep the full - v1 lane only for first-of-class surfaces. -8. **AI-execution boundary (v1.1).** AI agents implement, test, and prepare evidence. Humans - retain: decider approvals, all registry-facing operator actions (cargo/npm/PyPI publish, tag - pushes, GitHub Release edits), and public-wording changes. An agent must never execute a - registry action or edit approved claim strings, even if credentials are available. -9. **Smoothness rule (v1.2, clarified v1.4).** The routine idea-to-release lane has exactly three - recurring human gates: PR review, registry publish, and public-wording changes. Separately - scoped work may require a one-time authorization before it enters that lane — for example paid - benchmark spend or acceptance of an ADR — but must not create a request/decision/evidence chain - for routine implementation. Honesty gates (claims CI, determinism CI) are automated checks, not - queues. Public benchmark wording remains part of the public-wording gate. - ---- - -## 3. Strategic direction - -### 3.1 The thesis (unchanged, reaffirmed) - -Ethos is a **verification and grounding layer** that includes a deterministic parser — not a -parser competing with Docling/Marker/MinerU on conversion quality (ADR-0007). The differentiated -wedge is: *citations as tests* — `--fail-on-ungrounded` as a CI/agent release gate, deterministic -reports as audit artifacts, crops as human-inspectable proof. - -### 3.2 DocuShell is the first consumer — and the integration proof - -DocuShell (the private monorepo at `docushell/`, sibling to this repo) consumes Ethos first. -This is deliberate dogfooding with a public purpose: **Ethos is open source, and DocuShell's -integration is the test of whether any outside business can integrate it.** Every point of -friction DocuShell hits is, by definition, friction every future adopter will hit. - -Consequences: - -- DocuShell integrates through **public surfaces only**: the published CLI artifacts, the - published wheel/npm package, and documented JSON contracts. No private APIs, no reaching into - Ethos internals. If DocuShell needs something not on a public surface, that is an Ethos - product gap — file it in the friction log (NIP-1.6), don't special-case it. -- The integration contract lives in `docs/integrations/docushell.md` (delivered, NIP-1.1); - the friction log lives in `docs/integrations/docushell-friction-log.md` (open, seeded with - FR-1..FR-3). -- DocuShell already mirrors the verification-report contract in TypeScript - (`packages/evidence/src/ethos-answer-release.ts`, `openai-chat-evidence.ts`) and implements - the answer-release policy from `docs/app-answer-release-contract.md`. Keep these in lockstep: - any report-schema change requires a same-PR note in the friction log and a version bump note - for DocuShell (see friction entry FR-1 for the types-package gap). -- DocuShell's `services/parse-pdf` runs the OpenDataLoader hybrid backend (`docling-fast`). - Its output enters Ethos through the existing `opendataloader-json` grounding adapter — the - foreign-parser lane, exactly as an external adopter would use it. - -### 3.3 Priorities in one sentence each - -- **P0** — Prove and unblock the loop: DocuShell integration end-to-end (NIP-1), the trust - benchmark that answers "why not LLM-as-a-judge?" (NIP-3), citation emission so real pipelines - can feed `verify` (NIP-4), a one-step install (NIP-5), and right-sized governance (NIP-7). -- **P1** — The CI retention socket (NIP-6) and the contributor on-ramp (NIP-7.3). -- **P2** — Deferred out of this plan by the 2026-07-20 decider decision: `ethos-mcp` (NIP-2), - WASM playground (NIP-8), and scanned-document path via foreign parsers (NIP-9). These are - unapproved future-release candidates, not active Ethos work. - ---- - -## 4. Workstreams and tasks - -Task IDs are stable; never renumber. Add new tasks with the next free number in their workstream. - ---- - -### NIP-1 (P0) — DocuShell first-consumer integration - -**Goal:** DocuShell's parse/evidence lane verifies AI citations with Ethos in a worker-lane -deployment, using only public Ethos surfaces, and produces a written integration-friction report -that drives the Ethos DX backlog. - -**Why first:** it converts "no known users" into "one real production-shaped consumer," produces -the strongest possible DX feedback, and creates the reference integration story for every -external adopter. - -**Non-goals:** no hosted Ethos service, no Ethos claims about DocuShell in public wording, no -DocuShell-specific code inside Ethos. - -| Task | Description | -| --- | --- | -| NIP-1.1 | **Integration contract note.** ✅ Delivered: `docs/integrations/docushell.md` — surfaces consumed, version pins, compatibility promise, worker-lane rules, friction-log process. Template for future `docs/integrations/.md` files. | -| NIP-1.2 | **Vendored CLI in the DocuShell worker image.** (DocuShell-side task, tracked here for sequencing.) DocuShell's `services/parse-pdf` worker image vendors the released Linux x64 `ethos` CLI artifact (sha256-pinned, same pattern as `packages/npm/ethos-pdf` vendor manifest) plus PDFium via `scripts/fetch-pdfium.sh` pins. Worker-lane only — never inside a Next.js request handler (DocuShell golden rule). Update the version-pin table in `docs/integrations/docushell.md` when done. | -| NIP-1.3 | **Verify lane.** DocuShell parse jobs emit OpenDataLoader-style JSON; a post-parse step runs `ethos verify --citations --grounding opendataloader-json --out ` and stores the report alongside job output. Exit-code semantics preserved: 0 grounded / 1 ungrounded-with-report / ≥2 error (fail closed → job error, not silent pass). | -| NIP-1.4 | **Answer-release gate.** DocuShell's OpenAI-playground evidence path feeds `proof_summary` + claim labels into its existing `ethos-answer-release.ts` policy so unverified claims are blocked or flagged before an answer is released. Validate against `docs/app-answer-release-contract.md` fixtures. | -| NIP-1.5 | **Crop inspection.** DocuShell surfaces `crop_element` rendered crops for at least one flow (evidence playground), so a human can see the cited region. Requires caller-provided PDFium in the worker image (NIP-1.2). | -| NIP-1.6 | **Integration friction log.** `docs/integrations/docushell-friction-log.md` — created and seeded with FR-1 (no published TS types), FR-2 (PDFium image wiring), FR-3 (CLI vendoring bookkeeping). Stays open through NIP-1.2–1.5; every step adds or dispositions entries. **Required deliverable.** | -| NIP-1.7 | **Closeout.** One validation record `docs/validation/nip-1-docushell-integration-closeout-.md`: versions used, commands, friction-log summary, and explicit statement that no public wording changed. This satisfies the "DocuShell integration blocked pending separate evidence" line in `docs/execution-status.md`; a decider updates that status file. | - -**Acceptance criteria (workstream):** a DocuShell parse job on a born-digital PDF produces a -stored Ethos verification report; an ungrounded citation demonstrably blocks/flags an answer via -the release policy; friction log has all entries dispositioned; closeout record merged. - ---- - -### NIP-2 (P2 — dropped from this plan) — `ethos-mcp` v0: the agent surface - -> **Decider decision 2026-07-20: dropped from this implementation plan.** The workstream is not -> implemented or approved. The scope below is retained only as historical planning context and -> requires a fresh release-planning decision before any task is started. - -**Goal:** a local MCP (Model Context Protocol) server exposing the trust loop to AI agents: -`verify`, `evidence_anchor`, `crop_element`, `doc_parse` (parse optional, PDFium-gated). - -**Design constraints (unchanged):** experimental label per PRD §9.4; thin adapter over the same -internal code paths as the CLI (no forked logic); fail closed on missing PDFium; stdio transport -only in v0; distribution as an `ethos mcp serve` subcommand on the existing CLI binary. - -Tasks NIP-2.1–2.5 as originally scoped: ADR-0014 (scope/security posture) → core `verify` + -`evidence_anchor` tools with golden/determinism tests → PDFium-gated `crop_element`/`doc_parse` -→ `docs/mcp.md` quickstart (copy-paste configs) → release inside a routine NIP-7 train. - -**Acceptance criteria:** a stock MCP client config can call `verify` against -`schemas/examples/document.example.json` + the checked-in citation fixtures and receive the -grounded/ungrounded reports; determinism tests pass; experimental label present in every -user-facing string; claims gate green. - ---- - -### NIP-3 (P0) — Trust benchmark: Ethos verify vs LLM-as-a-judge - -**Goal:** a reproducible, labeled-fixture study comparing deterministic citation verification -against LLM-judge citation checking on: accuracy (precision/recall on grounded/ungrounded -labels), cost per 1,000 citations, latency, and run-to-run variance. - -**Why:** LLM-as-a-judge is the incumbent alternative; this is the one benchmark category -(**Trust**, `docs/benchmark-plan.md` §Categories) that does not depend on Gate Zero G1/G2 and -directly answers every prospect's first question. Nobody has published this comparison well. - -**Rules (inherited, strict):** results leave the harness only as JSON with reproduction -commands; label Ethos fixtures as Ethos-authored (never neutral); no ranking/superlative -language; LLM-judge prompts, model versions, and dates pinned in the manifest; judge -non-determinism is reported as data (variance across N runs), not editorialized. **Publication -of results remains gated** by the existing claim-audit lane — this workstream builds the study -and internal report; the decider approves public wording separately. - -| Task | Description | -| --- | --- | -| NIP-3.1 | Labeled corpus: extend `fixtures/` with ≥200 citation checks over ≥20 born-digital documents — grounded, fabricated-quote, wrong-page, paraphrase-drift, split-quote, stale-fingerprint, and capability-limited cases. Labels reviewed twice (AI-generated labels require one human spot-check pass over a ≥20% sample); labeling guide committed. Runs in the `ethos-bench` sibling repo per `docs/benchmark-ownership.md`, fixtures live here. | -| NIP-3.2 | Judge harness: 2–3 pinned LLM judges (one frontier, one small/cheap) with a fixed citation-checking prompt; N=5 runs each for variance; cost/latency capture. Judge API runs are a human-triggered operation (spend approval), prepared end-to-end by the agent. The exact internal raw result used downstream must be retained as auditable evidence; a hash without reconstructable bytes is insufficient. | -| NIP-3.3 | Report generator: JSON results + auto-generated Ethos-versus-judge table covering confusion matrices, grounded/ungrounded precision and recall, cost per 1,000 citations, latency, and run-to-run variance, with repro commands; internal snapshot first (dev-labeled per benchmark cadence rules). | -| NIP-3.4 | Claim-audit packet for the decider: proposed public wording, with the honest cells included (where judges beat Ethos, e.g. paraphrase tolerance, say so — that boundary is the semantic-truth line Ethos already disclaims). | - -**Acceptance criteria:** `make trust-bench` (or ethos-bench equivalent) reproduces all numbers -one-command from pinned inputs; internal report exists; publication packet delivered to decider. - ---- - -### NIP-4 (P0 — promoted in v1.1) — Citation emission: meet RAG frameworks where they are - -**Goal:** close the chicken-and-egg — pipelines don't emit Ethos-checkable citations today. Ship -the *emit* side so `verify` has native inputs in real stacks. - -Builds on `docs/citation-emission-spec-and-attestation-implementation-plan.md` (the spec exists; -this workstream implements it) and the existing `adapters/langchain`, `adapters/llamaindex`, -`adapters/docling`, `adapters/unstructured` directories. - -| Task | Description | -| --- | --- | -| NIP-4.1 | Freeze citation-emission spec v1 (JSON shape a framework callback must produce) with schema + fixtures; version it independently of the report schema. | -| NIP-4.2 | Python package `ethos-emit` (or a module inside the existing wheel): helpers that wrap LangChain/LlamaIndex retrieval results + model answers into emission-spec citations. Pure Python, no PDFium, no CLI required to *emit*. | -| NIP-4.3 | Two runnable end-to-end examples in `examples/`: LangChain RAG → emit → `ethos verify --fail-on-ungrounded`; LlamaIndex equivalent. Pinned versions; CI-smoked with recorded/model-free fixtures so CI needs no API keys. | -| NIP-4.4 | Publish integration docs where discovery happens (framework-side integration listings), once wording passes the claims gate. | -| NIP-4.5 | **TypeScript report types (from friction log FR-1).** Generate TS types from the report/emission JSON Schemas and ship them on a public surface (`.d.ts` in the existing npm package or a types package), so consumers like DocuShell stop hand-mirroring types. | - -**Acceptance criteria:** a RAG engineer can go from an existing LangChain pipeline to a failing -`--fail-on-ungrounded` exit on a fabricated citation in <30 minutes using only public docs; -DocuShell friction-log entries FR-1 (and any input-authoring entries from NIP-1) dispositioned. - ---- - -### NIP-5 (P0 — promoted in v1.1) — Kill the install cliff - -**Goal:** "time to first parse" (north-star metric, PRD §3.3) passes without manual PDFium steps. - -| Task | Description | -| --- | --- | -| NIP-5.1 | Make `scripts/fetch-pdfium.sh` the paved road: `ethos doctor` subcommand that checks PDFium presence, prints the exact fix command, and validates sha256 pins. Wheel and npm postinstall print the same guidance (never auto-download in v0 — posture stays ADR-0013-compliant). Include the consumer Dockerfile snippet promised in friction entries FR-2/FR-3 in `docs/pdfium-manual-setup.md`. | -| NIP-5.2 | ADR-0015 proposal: opt-in bundled PDFium artifact class (`ethos-full` archives) for macOS arm64 + Linux x64, with license notices and size documented. Decision remains the decider's; this task prepares the ADR + build evidence only. | -| NIP-5.3 | Windows x64 CLI artifact (parse-optional): ship verify-only Windows support first — verification needs no PDFium, so Windows users get the trust loop's JSON half immediately; PDFium-on-Windows follows the ADR-0015 outcome. | - -**Acceptance criteria:** fresh macOS/Linux machine → working parse in ≤3 commands with zero -manual URL hunting; fresh Windows machine → working `verify` on fixtures in ≤2 commands. - ---- - -### NIP-6 (P1) — `ethos-verify` CI Action - -**Goal:** the retention socket. A GitHub Action under `actions/verify/` in this repository that -runs `ethos verify --fail-on-ungrounded` on PR-supplied evidence/citation artifacts and annotates -the PR with per-check statuses. The decider selected the in-repository Action on 2026-07-20 to -keep its versioning and maintenance with Ethos; a dedicated Marketplace repository is deferred -until external demand exists. Action dogfood exercises the current wrapper against its pinned -published CLI; current-candidate verifier behavior is independently gated by workspace and -determinism CI. Reconcile the Action pin after a new CLI release is published. - -| Task | Description | -| --- | --- | -| NIP-6.1 | In-repository Action v0: pin CLI artifact by sha256, accept source/citations/grounding inputs, emit PR annotations from the report JSON, fail on exit 1/≥2. | -| NIP-6.2 | Dogfood: this repo's own CI runs the Action on the README demo fixtures (the "we gate ourselves" story). | -| NIP-6.3 | Marketplace listing deferred by the decider until external demand justifies a dedicated Action repository. | - -**Acceptance criteria:** a third-party repo can add ≤10 lines of workflow YAML and see a -fabricated-citation PR fail with a readable annotation. - ---- - -### NIP-7 (P0, meta) — Right-size governance - -**Goal:** protect the claims/approval discipline while cutting its cost ~in half, per §2 rule 7. - -| Task | Description | -| --- | --- | -| NIP-7.1 | ✅ `docs/release-lane-v2.md` — written and **accepted 2026-07-19**. One prep doc + one closeout record per release train; full v1 lane retained for first-of-class surfaces only; smoothness rule embedded. | -| NIP-7.2 | Apply it: the next release (carrying NIP-5 work and landed NIP-1/NIP-4 deliverables) ships under the v2 lane as its pilot. | -| NIP-7.3 | ✅ Contributor on-ramp delivered 2026-07-19: `CONTRIBUTING.md` rewritten as the single idea-to-release process page — five-step first PR, three-requirement PR bar (tests, CHANGELOG line, DCO), invariants as a CI-enforced reference table, release process summary. A contributor never needs to read `docs/validation/`. Remaining follow-up: validate with one real first-time contributor or cold-start agent run (fold into NIP-7.2 pilot evidence). | - -**Acceptance criteria:** next release's governance artifacts = exactly 2 documents; contributor -docs tested on one first-time contributor or one cold-start agent run. - ---- - -### NIP-8 (P2 — dropped from this plan) — WASM verify playground - -> **Decider decision 2026-07-20:** deferred to a future release-planning decision. This -> playground is not implemented, approved, or part of the current Ethos release scope. - -**Goal:** in-browser `verify` over pasted/attached JSON — the 10-second "aha" with zero install. -Verification is JSON-only (no PDFium), so `ethos-verify` compiles to wasm32 with modest effort. -Static page (GitHub Pages) — prepare an ADR clarifying that a static, client-side page is not a -"hosted surface" in the blocked sense, and let the decider rule. - -Tasks: NIP-8.1 wasm build of `ethos-verify` + JS shim; NIP-8.2 static page with the README demo -fixtures preloaded; NIP-8.3 ADR + decider review before anything is published. - ---- - -### NIP-9 (P2 — dropped from this plan) — Scanned documents via foreign parsers (not native OCR) - -> **Decider decision 2026-07-20:** deferred to a future release-planning decision. This adapter -> work is not implemented, approved, or part of the current Ethos release scope. - -**Goal:** scanned/image-only PDFs enter the trust loop through OCR-capable foreign parsers -(Docling first) with explicit capability downgrades — Ethos does **not** build OCR (PRD -Release-3 boundary stands). - -Tasks: NIP-9.1 promote the Docling adapter to a documented, fixture-backed grounding source with -an OCR-provenance capability flag; NIP-9.2 verification behavior spec for OCR-derived text -(`match_method` and confidence semantics stay honest — no pixel-proof claims); NIP-9.3 end-to-end -example: scanned PDF → Docling → verify, with downgrade warnings visible. - ---- - -## 5. Validation commands (per task, run before marking `done`) - -Baseline for **every** task: `cargo build --locked --workspace` · `cargo test --locked ---workspace` · `make verify-alpha` · claims gate script · determinism double-run on any new -artifact. Additional per-workstream: - -- NIP-1: DocuShell-side narrow Mocha suite for the touched service (`npm run test:resume-parse` - / parse-pdf suites) + `npm run acceptance:parse-pdf:real` for parse/OCR-adjacent claims, per - DocuShell `CLAUDE.md`; Ethos-side closeout record lint (dates, versions, links resolve). -- NIP-2 (when unblocked): MCP golden tests ×2 runs byte-identical; quickstart configs - copy-paste-verified against at least one real client. -- NIP-3: full one-command repro from a clean checkout of the bench repo; manifest pins resolve. -- NIP-4: both examples run end-to-end offline in CI via fixtures; <30-min walkthrough timed once; - generated TS types compile against DocuShell's `packages/evidence` usage (FR-1 evidence). -- NIP-5.1: isolated install transcript from a fresh home and `env -i` environment committed as - evidence; `ethos doctor` exit codes tested. Later platform-specific artifact tasks must still - validate on their target platforms. -- NIP-6: Action integration test in a scratch repo; annotation snapshot committed. -- NIP-8: wasm build reproducible; page works with JS-disabled fallback message. -- NIP-9: adapter fixtures include at least one real (consented, license-clean) scanned document. - ---- - -## 6. Execution model and sequencing - -### 6.0 Execution model (v1.1): AI-implemented, human-gated - -The default implementer for every task is an **AI agent**; the maintainer acts as reviewer, -decider, and operator. Consequences for planning: - -- Estimates are in **agent-days**: one focused AI working session producing a reviewable PR, - including tests and CHANGELOG entry. Implementation is rarely the bottleneck. -- The routine release critical path is the three §2 rule 9 gates: PR review, registry operator - actions, and public-wording review. One-time workstream authorizations such as benchmark spend - and ADR acceptance happen before their affected implementation enters that lane; they are not - additional per-release ceremony. -- Agents must respect §2 rule 8 (no registry actions, no claim-string edits) and the ledger - protocol (§0.1) without exception. -- Calendar guidance at this model: **P0 ≈ 3–4 calendar weeks** (≈15 agent-days of - implementation, dominated by review/decider cadence), P1 ≈ +1 week. The original human-lane - milestone pacing (weeks per feature) no longer applies. - -### 6.1 Dependency order - -``` -NIP-7.1(sign-off) ──► all release-carrying work uses v2 lane (NIP-7.2) -NIP-1.1 ✅ ──► NIP-1.2 ──► NIP-1.3 ──► NIP-1.4/1.5 ──► NIP-1.6 ──► NIP-1.7 -NIP-3.1 ──► NIP-3.2 ──► NIP-3.3 ──► NIP-3.4 (decider gate for publication) -NIP-4.1 ──► NIP-4.2 ──► NIP-4.3 ──► NIP-4.4 (claims gate); NIP-4.5 after NIP-4.1 -NIP-5.1 ──► NIP-5.2(ADR) ──► NIP-5.3 -NIP-6.1 ──► NIP-6.2 ──► NIP-6.3 -P2 workstreams NIP-2, NIP-8, and NIP-9 are dropped from this plan by the 2026-07-20 decider -decision. They require fresh scope and priority in a future release plan before work starts. -``` - -Parallelism guidance: with AI implementation, NIP-1, NIP-3.1, NIP-4.1, and NIP-5.1 can run as -parallel lanes immediately — they touch disjoint areas. Keep one lane per PR to keep human review -tractable. - ---- - -## 7. Progress Ledger — **update this section as work completes** - -Est. = agent-days (see §6.0). Human-gate tasks marked (gate). - -| Task | Priority | Status | Est. | Depends on | Date | Evidence | Notes | -| --- | --- | --- | --- | --- | --- | --- | --- | -| NIP-1.1 | P0 | done | 0.5 | — | 2026-07-19 | `docs/integrations/docushell.md` | | -| NIP-1.2 | P0 | done | 1 | NIP-1.1 | 2026-07-19 | `docs/integrations/docushell.md` | DocuShell worker-only image; offline determinism + fail-closed installer test | -| NIP-1.3 | P0 | done | 1 | NIP-1.2 | 2026-07-19 | `docs/integrations/docushell.md#parse-job-verification-lane-nip-13` | Stored canonical report; exit 1 preserved; missing capability/exit >=2 fail closed | -| NIP-1.4 | P0 | done | 1 | NIP-1.3 | 2026-07-19 | `docs/integrations/docushell.md#answer-release-gate-nip-14` | v1.1 claim-support labels; official fixture reproduced deterministically; missing support held for review | -| NIP-1.5 | P0 | done | 0.5 | NIP-1.2 | 2026-07-20 | `docs/integrations/docushell.md#crop-inspection-lane-nip-15`; `docs/integrations/docushell-friction-log.md#fr-11--real-acceptance-requires-the-documented-redis-prerequisite` | Operator-approved real born-digital PDF acceptance passed: 1/1 job, 38/38 anchors bound, 38/38 verification checks grounded, all artifact downloads successful, zero failures. | -| NIP-1.6 | P0 | done | ongoing | NIP-1.1 | 2026-07-20 | `docs/integrations/docushell-friction-log.md` | FR-1..FR-11 recorded and dispositioned; FR-11 records the already-documented Redis acceptance prerequisite; remaining product gaps retain explicit owners. | -| NIP-1.7 | P0 | done | 0.5 | NIP-1.4, NIP-1.5, NIP-1.6 | 2026-07-20 | `docs/validation/nip-1-docushell-integration-closeout-2026-07-20.md` | Decider accepted the source-bound closeout, real acceptance, and all friction dispositions; the current execution-status integration blocker is cleared without public wording changes. | -| NIP-3.1 | P0 | done | 2 | — | 2026-07-20 | `fixtures/trust-benchmark/LABELING_GUIDE.md`; `fixtures/trust-benchmark/review-record.json`; `fixtures/trust-benchmark/v1/manifest.json` | Deterministic 20-document/200-check corpus and sibling `ethos-bench` harness pass; all labels executable-reviewed, and the Ethos dev team agreed with the balanced 40-check (20%) human spot-check without corrections. | -| NIP-3.2 | P0 | done | 1 | NIP-3.1 | 2026-07-20 | `../ethos-bench/benchmarks/trust/judges.lock.json`; `../ethos-bench/src/ethos_bench/trust_judges.py`; `../ethos-bench/benchmarks/results/trust/judge-results.json`; `../ethos-bench/tests/test_trust_live_evidence.py`; `ethos-bench#a733411` | PR #7 merged the exact live result and its full-file hash, schema, model/run/document/judgment coverage, cost, internal-only state, and credential-field audit. All 37 sibling tests, smoke commands, the 20-document/200-check corpus, and double-run report regeneration passed locally. No paid rerun is required. | -| NIP-3.3 | P0 | done | 1 | NIP-3.2 | 2026-07-20 | `../ethos-bench/src/ethos_bench/trust_ethos.py`; `../ethos-bench/src/ethos_bench/trust_report.py`; `../ethos-bench/benchmarks/results/trust/ethos-results.json`; `../ethos-bench/benchmarks/results/trust/comparison-report.json`; `../ethos-bench/benchmarks/results/trust/comparison-report.md`; `ethos-bench#5945fce` | PR #8 merged the source/binary-bound Ethos 0.4.0 baseline, raw confusion matrices, grounded/ungrounded precision and recall, cost per 1,000 citations, observed latency/run variance, category cells, and deterministic reports. All 46 tests, smoke commands, the real 20-document/200-check corpus, and byte-identical report regeneration passed on the merged tree. Timing remains descriptive across different environments and supports no speed claim. | -| NIP-3.4 | P0 | done | 0.5 | NIP-3.3 | 2026-07-20 | `../ethos-bench/benchmarks/trust/nip-3.4-claim-audit.md`; `../ethos-bench/src/ethos_bench/trust_claim_audit.py`; `../ethos-bench/tests/test_trust_claim_audit.py`; `ethos-bench#9287671` | PR #9 merged the complete-comparison claim-audit packet with all three confusion matrices, all 21 category cells, exact provenance hashes, and explicit exclusions for cross-environment latency, local-compute cost comparisons, rankings, semantic truth, parser quality, speed, footprint, and production claims. All 50 sibling tests, smoke commands, tracked-artifact hash binding, and byte-identical regeneration passed on the merged tree. Approved public claim strings remain unchanged; any publication still requires the separate public-wording lane. | -| NIP-4.1 | P0 | done | 0.5 | — | 2026-07-19 | `docs/citation-emission-spec.md` | Independently versioned v1 schema; parser-neutral source IDs; grounded/fabricated/OOV/conflict fixtures; hydration and reports double-run byte-identical | -| NIP-4.2 | P0 | done | 1.5 | NIP-4.1 | 2026-07-19 | `python/README.md#citation-emission` | Pure-Python duck-typed LangChain/LlamaIndex adapters; strict retrieval metadata and OOV rejection; emission/hydration artifacts double-run byte-identical; no framework, CLI, PDFium, or network dependency | -| NIP-4.3 | P0 | done | 1 | NIP-4.2 | 2026-07-19 | `examples/README.md` | Native framework objects with resolvable exact core-package pins; Python 3.12 clean-environment install and model-free double-run suite pass in under 7 seconds with grounded exit 0 and fabricated exit 1 artifacts byte-identical | -| NIP-4.4 | P0 | dropped | 0.5 | NIP-4.3 | 2026-07-19 | `adapters/langchain/README.md`; `adapters/llamaindex/README.md` | Decider deferred framework-owned listings on 2026-07-19; adapters and walkthroughs remain available in Ethos, and the prepared upstream patches may be revisited after v0.4.0 | -| NIP-4.5 | P0 | done | 1 | NIP-4.1 | 2026-07-19 | `packages/npm/ethos-pdf/types/index.d.ts` | Schema-generated report, emission, and answer-release declarations ship in the npm candidate; strict fixtures, double-run generation, package tests, actual DocuShell type compatibility, and focused consumer tests pass | -| NIP-5.1 | P0 | done | 1 | — | 2026-07-20 | `docs/validation/nip-5-1-pdfium-install-smoke-2026-07-19.md` | Isolated fresh-home `env -i` macOS fetch, doctor, and byte-identical parse accepted by the decider under plan revision v1.3 | -| NIP-5.2 | P0 | done | 0.5 | NIP-5.1 | 2026-07-20 | `docs/decisions/ADR-0015-opt-in-bundled-pdfium-artifacts.md`; `docs/validation/nip-5-2-ethos-full-build-evidence-2026-07-20.md` | Proposed only: deterministic macOS/Linux candidates and notices verified; publication remains blocked pending ADR acceptance and target-platform smoke | -| NIP-5.3 | P0 | done | 1.5 | — | 2026-07-20 | `docs/validation/nip-5-3-windows-verify-draft-2026-07-20.md`; [release run 29728642038](https://github.com/docushell/ethos/actions/runs/29728642038); [determinism run 29728692721](https://github.com/docushell/ethos/actions/runs/29728692721) | The reviewed source built the Windows x64 CLI, assembled byte-identical verify-only ZIPs twice, executed the real `.exe` smoke, validated inventory/checksum evidence, and passed the macOS/Linux/Windows verification determinism matrix. This completes the implementation task; public Windows artifact publication remains a separate first-of-class release decision. | -| NIP-6.1 | P1 | done | 1 | — | 2026-07-20 | `actions/verify/README.md`; `actions/verify/tests/fixtures/ungrounded.annotations.txt`; [PR #223 CI](https://github.com/docushell/ethos/actions/runs/29728324553) | The checksum-pinned released-CLI Action contract and fail-closed scratch-repository integration tests pass locally and in remote PR CI. The Action intentionally consumes the currently published CLI; candidate-source verification remains covered by repository tests and cross-platform determinism. | -| NIP-6.2 | P1 | done | 0.5 | NIP-6.1 | 2026-07-20 | `.github/workflows/ci.yml`; `actions/verify/tests/test_action.py`; [PR #223 CI](https://github.com/docushell/ethos/actions/runs/29728324553) | Remote PR CI passed the released-CLI dogfood job against both canonical README fixtures, requiring the grounded case to succeed and the fabricated case to fail with readable Action annotations. | -| NIP-6.3 | P1 | dropped | 0.5 | NIP-6.2 | 2026-07-20 | | Decider deferred Marketplace publication until external demand justifies a dedicated repository. | -| NIP-7.1 | P0 | done | 0.5 | — | 2026-07-19 | `docs/release-lane-v2.md` | accepted by decider | -| NIP-7.2 | P0 | in_progress | 0.5 | NIP-7.1 | 2026-07-20 | `docs/v0-4-0-release-prep.md`; `docs/releases/v0.4.0.md`; `.github/scripts/test_v0_4_0_version_activation.py`; [main CI run 29729605736](https://github.com/docushell/ethos/actions/runs/29729605736) | PR #223 is merged, post-merge CI is green, and the exact v0.4.0 release-note wording is approved. Final main-bound artifacts, human registry/tag/GitHub Release actions, and the single v2 closeout record remain. Windows publication is skipped as an unapproved first-of-class surface despite completed implementation validation. | -| NIP-7.3 | P1 | done | 0.5 | NIP-7.1 | 2026-07-20 | `CONTRIBUTING.md`; `docs/v0-4-0-release-prep.md` | NIP-7.2 cold-start validation followed the documented contributor and Release Lane v2 path without per-artifact ceremony. | -| NIP-2.1 | P2 | dropped | 0.5 | all P0/P1 done | 2026-07-20 | | Decider deferred NIP-2 to a future release-planning decision; not implemented or approved. | -| NIP-2.2 | P2 | dropped | 2 | NIP-2.1 | 2026-07-20 | | Decider deferred NIP-2 to a future release-planning decision; not implemented or approved. | -| NIP-2.3 | P2 | dropped | 1 | NIP-2.2 | 2026-07-20 | | Decider deferred NIP-2 to a future release-planning decision; not implemented or approved. | -| NIP-2.4 | P2 | dropped | 0.5 | NIP-2.2 | 2026-07-20 | | Decider deferred NIP-2 to a future release-planning decision; not implemented or approved. | -| NIP-2.5 | P2 | dropped | 0.5 | NIP-2.3, NIP-2.4, NIP-7.1 | 2026-07-20 | | Decider deferred NIP-2 to a future release-planning decision; not implemented or approved. | -| NIP-8.1 | P2 | dropped | 1.5 | all P0/P1 done | 2026-07-20 | | Decider deferred NIP-8 to a future release-planning decision; not implemented or approved. | -| NIP-8.2 | P2 | dropped | 0.5 | NIP-8.1 | 2026-07-20 | | Decider deferred NIP-8 to a future release-planning decision; not implemented or approved. | -| NIP-8.3 | P2 | dropped | 0.5 | NIP-8.2 | 2026-07-20 | | Decider deferred NIP-8 to a future release-planning decision; no publication approval was granted. | -| NIP-9.1 | P2 | dropped | 1 | all P0/P1 done | 2026-07-20 | | Decider deferred NIP-9 to a future release-planning decision; not implemented or approved. | -| NIP-9.2 | P2 | dropped | 0.5 | NIP-9.1 | 2026-07-20 | | Decider deferred NIP-9 to a future release-planning decision; not implemented or approved. | -| NIP-9.3 | P2 | dropped | 0.5 | NIP-9.2 | 2026-07-20 | | Decider deferred NIP-9 to a future release-planning decision; not implemented or approved. | - ---- - -## 8. Success metrics (review monthly) - -- **Time-to-first-verify:** <5 minutes from cold README on a fresh machine (measured, not - estimated; commit transcripts as evidence). -- **DocuShell in production-shape:** verification reports stored for real parse jobs; ≥1 - answer-release gate live; friction log actively dispositioned. -- **Sticky-socket installs:** repos running the CI Action (and MCP quickstart completions once - NIP-2 unblocks). -- **Trust benchmark:** internal report complete; publication decision made either way. -- **OSS health:** median first response on public issues <48h (PRD §3.3); one external - contributor PR landed via the NIP-7.3 fast path; one co-maintainer conversation started. -- **Governance cost:** ≤2 governance documents per release train. - ---- - -## 9. Completion and handoff protocol - -When the last P0/P1 task is `done` (or `dropped` with decider notes): - -1. Write `docs/validation/nip-1-closeout-.md` summarizing ledger state, metric readings, - and the friction-log disposition table. -2. Propose NIP-2 (the successor plan) as a fresh document; do not extend this one past its - scope — plans that grow forever stop being picked up first. -3. Update `AGENTS.md` to point new agents at the successor plan. - -*Maintained by: product/decider. Implementers update §7; only the decider edits §2 and §3.* diff --git a/docs/citation-emission-spec-and-attestation-implementation-plan.md b/docs/citation-emission-spec-and-attestation-implementation-plan.md index c5dcb70d..0fc53573 100644 --- a/docs/citation-emission-spec-and-attestation-implementation-plan.md +++ b/docs/citation-emission-spec-and-attestation-implementation-plan.md @@ -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. @@ -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. diff --git a/docs/decisions/ADR-0015-opt-in-bundled-pdfium-artifacts.md b/docs/decisions/ADR-0015-opt-in-bundled-pdfium-artifacts.md index 711dcb4d..73904226 100644 --- a/docs/decisions/ADR-0015-opt-in-bundled-pdfium-artifacts.md +++ b/docs/decisions/ADR-0015-opt-in-bundled-pdfium-artifacts.md @@ -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. @@ -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: diff --git a/docs/execution-status.md b/docs/execution-status.md index 7583ef2c..dcc5d5a5 100644 --- a/docs/execution-status.md +++ b/docs/execution-status.md @@ -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 diff --git a/docs/integrations/docushell.md b/docs/integrations/docushell.md index a4a8ad92..89554af3 100644 --- a/docs/integrations/docushell.md +++ b/docs/integrations/docushell.md @@ -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/.md` files. ## Why this document exists @@ -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) @@ -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 @@ -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) @@ -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 @@ -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 @@ -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 @@ -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 diff --git a/docs/prompts/nip-kickoff.md b/docs/prompts/nip-kickoff.md deleted file mode 100644 index 9b7b977d..00000000 --- a/docs/prompts/nip-kickoff.md +++ /dev/null @@ -1,81 +0,0 @@ -# NIP Kickoff Prompt - -Reusable session-start prompt for any AI agent implementing NEXT_IMPLEMENTATION_PLAN.md tasks. -Paste the block below as the first message of an implementation session. Keep this file in sync -with the plan's §0 protocol. - ---- - -You are the implementation agent for **Ethos** (open-source deterministic citation-grounding -verifier and PDF evidence layer, Rust workspace) and its first consumer **DocuShell** (private -npm-workspaces monorepo). You implement; humans review, publish, and approve public wording. - -## Repositories - -- Ethos: `/ethos` — plan, ledger, and most tasks live here. -- DocuShell: `/docushell` — DocuShell-side tasks (NIP-1.2–1.5). Read its `CLAUDE.md` - before touching it. - -## Startup sequence (do this before any code) - -1. Read `ethos/AGENTS.md`, then `ethos/NEXT_IMPLEMENTATION_PLAN.md` — fully: §0 (protocol), - §2 (operating rules), §5 (validation commands), §7 (Progress Ledger). -2. From the ledger (§7), select the highest-priority task (P0 → P1 → P2) whose status is - `not_started` or `in_progress` and whose `Depends on` entries are all `done`. If several - qualify, prefer the NIP-1 chain (DocuShell integration) first, then NIP-4.1, NIP-5.1, - NIP-3.1 — they are parallel lanes. -3. State which task you selected and your implementation plan in 5–10 lines. Then implement. - Do not bundle multiple ledger tasks into one branch/PR. - -## Hard rules (non-negotiable, from plan §2) - -- Determinism is a contract: any new emitted artifact needs a double-run byte-identical test. -- Fail closed: missing capability ⇒ explicit downgrade/warning/error, never a silent pass. -- Never edit approved public claim strings (`README.md`, `docs/public-boundary-claims.json`); - the claims-gate CI script must stay green. -- Never execute registry actions (cargo/npm/PyPI publish, tag pushes, GitHub Release edits) — - prepare commands and evidence for a human instead. -- No AGPL or network-capable dependencies in base crates; PDFium stays caller-provided. -- `ethos-verify` compiles against `GroundingSource` only, never parser internals. -- Do not start NIP-2 (MCP), NIP-8, NIP-9, or anything touching `crates/ethos-rag` — P2, gated - until P0/P1 complete. -- Smoothness rule: no ceremony documents for routine work; the only human gates are PR review, - registry publish, and public wording. - -## Definition of done (every task) - -1. Code + tests implemented against the task's acceptance criteria in the plan. -2. All §5 validation commands for that task pass locally (baseline: `cargo build --locked - --workspace`, `cargo test --locked --workspace`, `make verify-alpha`, claims gate script; - DocuShell-side: the narrowest relevant Mocha suite + affected workspace build). -3. One `CHANGELOG.md` line under `## Unreleased` (house style; both repos if both touched). -4. **Ledger row updated** in `NEXT_IMPLEMENTATION_PLAN.md` §7: status, date, evidence link. - For DocuShell integration work, add/disposition entries in - `docs/integrations/docushell-friction-log.md` — every rough edge you personally hit is an - entry; an empty log means you didn't look. -5. Work committed on a descriptively named branch with DCO sign-off (`git commit -s`), - PR-ready with a short description: what, why, how validated. - -## If blocked or uncertain - -Set the ledger row to `blocked` with a one-line note, commit that, and stop — report the -blocker and your recommended resolution. Never work around a guardrail. If a task's scope is -ambiguous, propose an interpretation, note it in the PR description, and proceed with the -narrowest reading. - -## End-of-session report (always produce) - -- Task(s) worked, ledger status changes (before → after). -- Files changed (paths only) + branch name. -- Validation evidence: the commands run and their results. -- Friction-log entries added, if any. -- Recommended next task for the following session. - -Begin with the startup sequence now. - ---- - -## Variant: single-task override - -To direct a session at one specific task, append: "Override task selection: work on -NIP- only. If its dependencies are not `done`, stop and report instead of proceeding." diff --git a/docs/release-lane-v2.md b/docs/release-lane-v2.md index 95d16234..7db7fce4 100644 --- a/docs/release-lane-v2.md +++ b/docs/release-lane-v2.md @@ -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 @@ -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: — diff --git a/docs/roadmap.md b/docs/roadmap.md index 3807f35c..5e897f61 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -9,6 +9,11 @@ layer that includes a deterministic parser, not a parser that may later add veri Current PM status and blockers: `docs/execution-status.md`. +Current work is selected through explicit issues or decider requests. Release-specific scope and +gates live in the current `docs/v-release-prep.md`. The temporary July 2026 next-work +ledger has been retired; its completed and deferred decisions remain available in Git history and +dated validation records rather than acting as an ongoing developer queue. + Milestone C has an internal source-tree artifact-validation closeout for the current RAG chunk and security-report trust-loop checks. The canonical status tracker records the current pre-alpha validation posture plus the remaining diff --git a/docs/v0-4-0-release-prep.md b/docs/v0-4-0-release-prep.md index ac69a735..04a0deff 100644 --- a/docs/v0-4-0-release-prep.md +++ b/docs/v0-4-0-release-prep.md @@ -7,6 +7,11 @@ Release actions, final artifact hashes, and closeout remain pending. The v0.4.0 wording is approved, while public installation wording remains on the actually published `0.3.0` surfaces until publication. +The release scope may be amended before tagging only through an explicitly scoped, reviewed PR. +Any implementation change invalidates earlier final-artifact hashes and requires fresh full CI, +release-artifact, determinism, and release-wording review on the resulting `main`. Feature work is +not tracked in a separate implementation ledger. + Canonical preparation sentence: > v0.4.0 prepares the accumulated verification-hardening, report-contract, citation-emission, @@ -25,11 +30,11 @@ positioning, benchmark claims, or changes to `README.md` / `docs/public-boundary - Additive `1.1.0` verification-config, verification-report, evidence-anchor request/report, and application answer-release contracts. The `1.0.0` forms remain accepted where their contracts permit; compatibility and migration behavior must remain fixture-backed. -- Citation-emission contract `1.0.0` (NIP-4.1), dependency-free Python LangChain/LlamaIndex - emission helpers (NIP-4.2), and model-free framework walkthroughs (NIP-4.3), including +- Citation-emission contract `1.0.0`, dependency-free Python LangChain/LlamaIndex emission + helpers, and model-free framework walkthroughs, including fail-closed hydration and double-run byte-identical artifact checks. -- DocuShell first-consumer integration contracts, friction findings, and closeout for - NIP-1.1–1.7. The private DocuShell implementation remains versioned and validated in its own +- DocuShell first-consumer integration contracts, friction findings, and accepted closeout. The + private DocuShell implementation remains versioned and validated in its own repository; this release does not publish DocuShell or make public adoption claims about it. - Adoption and operator tooling originally prepared for the abandoned v0.3.1 patch scope: the README fixture demo, caller-run pinned PDFium fetch helper, ADR-0013, and related decision @@ -40,8 +45,8 @@ positioning, benchmark claims, or changes to `README.md` / `docs/public-boundary ## Carried but Not Activated as a Release Surface The source tree contains an unpublished `packages/npm/ethos-mcp` prototype inherited from work -that predates the active NIP priority decision. NIP-2 was dropped from this implementation plan -by the 2026-07-20 decider decision and requires fresh scope and priority in a future release plan. +that predates the current release scope. The MCP surface was deferred by the 2026-07-20 decider +decision and requires fresh scope and priority in a future release plan. The prototype is therefore excluded from v0.4.0 package publication, release claims, and release validation. Keeping its commits in the source tree does not activate or approve the surface. @@ -50,8 +55,8 @@ builder/evidence. The proposal does not activate bundled PDFium: no `ethos-full` the v0.4.0 artifact set unless the decider accepts the ADR and this prep scope is updated in a reviewed change. -The NIP-5.3 verify-only Windows x64 implementation and draft workflow remain in source, but the -Windows package is skipped as a v0.4.0 publication surface. Its `windows-latest` double-build, +The verify-only Windows x64 implementation and draft workflow remain in source, but the Windows +package is skipped as a v0.4.0 publication surface. Its `windows-latest` double-build, target-runtime smoke, and cross-platform determinism checks passed, completing the implementation task. Public Windows packaging remains a separate first-of-class release decision under Release Lane v1 and was not approved for this train. The v0.4.0 closeout must list Windows as skipped. @@ -68,7 +73,7 @@ accidentally presents this prototype as shipped. - hosted or network-served surfaces, production positioning, or a WASM playground; - bundled/project-maintained PDFium distribution and Windows-with-PDFium artifacts; - `ethos-rag`, native OCR, or scanned-document support claims; -- NIP-3 trust-benchmark publication and NIP-6 CI Action publication; +- trust-benchmark publication and CI Action Marketplace publication; - any silent weakening of verification, capability, determinism, or licensing guardrails. ## Release Gates @@ -96,7 +101,7 @@ accidentally presents this prototype as shipped. - [x] Built the `ethos-doc-core` crate package plus the Python sdist/wheel, and inspected the npm tarball with `npm pack --dry-run`. Dependent Rust crates remain gated on publishing `ethos-doc-core 0.4.0` first, as required by crates.io dependency ordering. -- [x] NIP-7.3 cold-start check: this release pass followed `AGENTS.md` → active plan → one prep +- [x] Contributor cold-start check: this release pass followed `AGENTS.md` and one release-prep document without creating per-artifact ceremony records. - [x] Windows x64 double-build/runtime smoke passed in release run `29728642038`, and the full macOS/Linux/Windows verification determinism matrix passed in run `29728692721`. Public diff --git a/docs/validation/README.md b/docs/validation/README.md index 300b1f8b..56f5dd75 100644 --- a/docs/validation/README.md +++ b/docs/validation/README.md @@ -10,28 +10,28 @@ in `docs/public-release-checklist.md`. Records: -NIP-1 DocuShell first-consumer integration closeout is accepted and complete in +The DocuShell first-consumer integration closeout is accepted and complete in `nip-1-docushell-integration-closeout-2026-07-20.md`. It binds the public Ethos/PDFium versions, worker-only verification and crop lanes, focused tests, real born-digital PDF acceptance, and all eleven friction dispositions. The decider accepted the record and cleared the current integration blocker on 2026-07-20. -NIP-5.3 Windows verify-only draft evidence is recorded in +Historical Windows verify-only draft evidence is recorded in `nip-5-3-windows-verify-draft-2026-07-20.md`. Implementation, deterministic fixture packaging, -and Windows cross-target checking pass; the task remains blocked until a Windows x64 runner links -and executes the real candidate, records its checksum/inventory, and passes the verify/no-PDFium -smoke. +and Windows cross-target checking pass. Later Windows x64 runner evidence completed the real +candidate execution, checksum/inventory validation, and verify/no-PDFium smoke; publication +remains a separate first-of-class decision. -NIP-5.2 `ethos-full` proposal build evidence is recorded in +The `ethos-full` proposal build evidence is recorded in `nip-5-2-ethos-full-build-evidence-2026-07-20.md`. It records byte-identical macOS arm64 and Linux x64 candidate archives, complete PDFium notices, exact sizes and hashes, a real macOS double-parse smoke, and the required Linux target-smoke/publication blockers while ADR-0015 remains Proposed. -NIP-5.1 isolated PDFium install evidence is recorded in +The isolated PDFium install evidence is recorded in `nip-5-1-pdfium-install-smoke-2026-07-19.md`. It records the fresh-home `env -i` fetch, runtime hash verification, doctor check, and byte-identical macOS parse accepted by the decider under -`NEXT_IMPLEMENTATION_PLAN.md` revision v1.3. +the then-active July 2026 implementation-plan revision, now retired and preserved in Git history. v0.3.0 final GitHub Release metadata closeout is recorded in `v0-3-0-release-metadata-closeout-validation-2026-07-03.md`. It records that GitHub Release diff --git a/docs/validation/nip-5-1-pdfium-install-smoke-2026-07-19.md b/docs/validation/nip-5-1-pdfium-install-smoke-2026-07-19.md index ad668d71..7c52c2ac 100644 --- a/docs/validation/nip-5-1-pdfium-install-smoke-2026-07-19.md +++ b/docs/validation/nip-5-1-pdfium-install-smoke-2026-07-19.md @@ -1,7 +1,8 @@ # NIP-5.1 PDFium install smoke — 2026-07-19 Acceptance: the decider accepted this isolated macOS `env -i` smoke on 2026-07-20 as sufficient -for NIP-5.1 under `NEXT_IMPLEMENTATION_PLAN.md` revision v1.3. Later platform-specific artifact +for the install-friction task under the then-active July 2026 implementation-plan revision v1.3, +now retired and preserved in Git history. Later platform-specific artifact tasks retain their own target-platform validation requirements. Environment: macOS 26.5.1 arm64. The smoke used `env -i`, a fresh `HOME`, and a fresh PDFium diff --git a/docs/windows-verify.md b/docs/windows-verify.md index 8747f209..5c799e1e 100644 --- a/docs/windows-verify.md +++ b/docs/windows-verify.md @@ -1,6 +1,6 @@ # Windows x64 Verify-Only Draft -Status: NIP-5.3 draft artifact contract. No Windows artifact is published or approved by this +Status: draft artifact contract. No Windows artifact is published or approved by this document. The Windows x64 archive provides the JSON citation-verification path without bundling PDFium. @@ -29,7 +29,7 @@ The deterministic ZIP contains: It contains no PDFium DLL. `ethos doc parse` therefore exits with the stable missing-capability code `12` unless a caller separately configures `ETHOS_PDFIUM_LIBRARY_PATH`. Windows-with-PDFium -packaging remains outside NIP-5.3 and follows the ADR-0015 decision. +packaging remains outside this verify-only contract and follows the ADR-0015 decision. ## Build and Validation diff --git a/fixtures/README.md b/fixtures/README.md index f7b037a2..bc75edd6 100644 --- a/fixtures/README.md +++ b/fixtures/README.md @@ -12,7 +12,7 @@ fixtures/ security/ # hidden/off-page/low-contrast text, annotations, actions, scripts, links failure/ # corrupt, encrypted, password, image-only, oversized, rotated foreign/ # pinned third-party parser outputs plus their source files and manifests - trust-benchmark/ # Ethos-authored NIP-3 verifier/judge comparison corpus + trust-benchmark/ # Ethos-authored verifier/judge comparison corpus ``` `trust-benchmark/v1/` is separately generated and pinned because it pairs born-digital PDFs with diff --git a/fixtures/trust-benchmark/generate.py b/fixtures/trust-benchmark/generate.py index fe203f48..dc4eeff5 100644 --- a/fixtures/trust-benchmark/generate.py +++ b/fixtures/trust-benchmark/generate.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -"""Generate the deterministic NIP-3.1 synthetic trust corpus.""" +"""Generate the deterministic synthetic trust corpus.""" from __future__ import annotations diff --git a/python/README.md b/python/README.md index 0f3deb80..91856ba4 100644 --- a/python/README.md +++ b/python/README.md @@ -174,7 +174,7 @@ claim can enter the final answer. For a grounded claim, missing `claim_support` ## Citation emission -The source API prepared under NIP-4.2 builds the independently versioned citation-emission v1 +The source API builds the independently versioned citation-emission v1 artifact and hydrates it into verifier input. Registry publication remains a human release action. No CLI, PDFium, LangChain, or LlamaIndex package is imported by these helpers. From fd2e51a14c147456d3dce6e85023d4ce38fb606c Mon Sep 17 00:00:00 2001 From: docushell-admin Date: Mon, 20 Jul 2026 15:09:03 +0530 Subject: [PATCH 2/2] ci: mark validation boundary cleanup Signed-off-by: docushell-admin --- CHANGELOG.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4ee69f39..a7136d09 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,9 +2,10 @@ ## Unreleased -- planning: 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 direct new - work through explicit issues or decider requests while preserving historical evidence IDs. +- 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.