Gate 4: staged Read-Need Fit settlement

[geraldarthurdavis]

Summary

• Adds the staged Reading flow: Read Request -> Read-Need review -> Need-Fit pipeline -> source-safe preview -> BTC settlement/read-right posture -> unlock/PR delivery readback.
• Extends the AssetPack pipeline primitives with deterministic Share-to-Fee quote structure, source-safe preview evidence, and read-right state resolution.
• Wires accepted Read-Need contracts through the Terminal API, pipeline harness request, sandbox runner evidence, and Terminal UI.
• Updates Gate 4 specification/QA notes and CI workflows so the staged Reading API/UI contracts are validated for gate and V28 promotion checks.

Validation

• pnpm --filter @bitcode/pipeline-asset-pack exec jest --config jest.config.cjs --runTestsByPath src/__tests__/read-need.test.ts --runInBand
• pnpm --filter @bitcode/pipeline-hosts exec jest --config jest.config.cjs --runTestsByPath src/__tests__/asset-pack-harness.test.ts --runInBand
• pnpm --dir uapi exec jest --runTestsByPath tests/api/readReviewRoute.test.ts tests/api/pipelineHarnessRoute.test.ts tests/terminalPipelineHarnessClient.test.ts tests/terminalDepositReadWorkbench.test.ts tests/pipelineExecutionLogHeader.test.tsx --runInBand
• pnpm --filter @bitcode/pipeline-asset-pack typecheck
• pnpm --filter @bitcode/pipeline-hosts typecheck
• pnpm --dir uapi exec tsc --noEmit --pretty false --incremental false
• pnpm --filter @bitcode/pipeline-asset-pack exec jest --config jest.config.cjs --passWithNoTests --forceExit
• pnpm --filter @bitcode/pipeline-hosts exec jest --config jest.config.cjs --passWithNoTests --forceExit
• npm --prefix protocol-demonstration run test:v28-mvp-qa
• Local Playwright browser check against http://127.0.0.1:3028/terminal confirmed the staged Reading section, Read-Need actions, Need-Fit action, source-safe preview panel, no Next error overlay, and HTTP 200.
• git diff --check
• Non-doc diff secret/self-referential label scan: no matches.

Notes

• No deployment performed. Local application verification only.
• The Need-Fit action remains readiness-gated: it is visible throughout the staged flow, but execution still requires an accepted Read-Need plus complete repository/commit/harness readiness.

[vercel]

Deployment failed with the following error:

There is no GitHub account connected to this Vercel account.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
engi-uapi	Ready	Preview, Comment	May 18, 2026 11:54pm

[chatgpt-codex-connector]

💡 Codex Review

https://github.com/engineeredsoftware/ENGI/blob/141b1ee00224f9aec9476128af335bb732444507/packages/pipeline-hosts/src/asset-pack-harness.ts#L1546-L1548
Reject missing accepted Read-Need before harness execution

When the manifest does not contain an already accepted readNeed (or contains one still in review), this fallback synthesizes and accepts a new Need inside the live harness, so a direct /api/pipeline-harness/asset-pack request with requireAcceptedReadNeed defaulting to true can still run candidate recall without the review/acceptance boundary the gate is adding. This bypasses the newly documented invariant that only a user-accepted Read-Need is admissible for Need-Fit search; the harness should fail closed here instead of manufacturing acceptance.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".