Skip to content

docs: propose a checklist-first remote qualification contract - #159

Closed
abruption wants to merge 3 commits into
mainfrom
docs/158-checklist-contract
Closed

abruption wants to merge 3 commits into
mainfrom
docs/158-checklist-contract

Conversation

@abruption

@abruption abruption commented Oct 21, 2026 •

Copy link
Copy Markdown
Owner

Summary

Refs #158 and #23. Propose a checklist-only remote qualification contract before replacement implementation. Keep #155 deferred; do not port its journal, authority, receipt, lock, caller or recovery engine.

  • Add an English design proposal with a short operator workflow, invocation-local per-predicate states, evidence kinds/freshness, remaining design(ssh): define Python-free remote deployment and version compatibility #23 classification and paper acceptance scenarios.
  • Require explicit selected CLI/wrapper paths for diagnostic attribution. Default PATH resolution and a same-version banner do not identify the selected installation; Windows remote invocations use the existing platform mode and accepted path syntax.
  • Distinguish an explicitly selected historical digest baseline from inheriting an old check result. A new comparison describes matching observed digests, not continuous preservation, ownership or authority.
  • Keep doctor completion/readiness/native verification and dry-run effects distinct. Existing tools can perform SSH, process or native checks; labels are not zero-effect guarantees.
  • Record the original isolated POSIX/Windows criterion and the human decision needed for historical recovery debt. No remaining qualification cell is silently closed.
  • Add only a cross-reference in the existing ADR. F1–F6 remain separate proposals, and human design acceptance is still required.

Scope decision

Checklist only for this stage. No demonstrated gap justifies a reporter now. No runtime code, CLI flags, machine schema, installer, authority/recovery logic, metadata/profile/version/pin changes, native/SSH/model experiments, release or operations changes.

This Draft is a design review artifact, not design freeze or implementation approval. #158 and #23 remain open and unassigned to a release. The deferred #155 branch and other worktrees are preserved. Human review must decide the minimum contract before any replacement implementation.

Independent work and review

  • A fresh author subagent drafted the proposal; a separate subagent audited design(ssh): define Python-free remote deployment and version compatibility #23/design(ssh): define a checklist-first remote qualification contract #158 against published source 12f98f2793b78f647107368c06e83286c5026e05 without initially reading that draft. Codex integrated the results and checked source claims.
  • The previous Claude TUI/session was not contacted, resumed or used. A new noninteractive Claude Code 2.1.305 process reviewed frozen source with requested and metadata-confirmed claude-opus-5-5, using the existing user-approved account.
  • Claude ran with tools/MCP/customizations disabled, manual permissions/no permission prompts, safe mode and no session persistence. It reviewed supplied text only; it edited no repository file and ran no tests, destination commands or network tools. This is a read-only CLI contract, not a claim of OS sandbox isolation.
  • Primary frozen input: SHA-256 b586639d010ffc388ea09d299b441d3be836808995437f1737b0f96201b8092c, proposal 9587833. Exit0, success, one turn, input/source hashes unchanged. Two mandatory findings concerned selected-installation attribution and baseline comparison semantics; Codex checked and corrected them in fe441a7.
  • A review claim that before/after observations must always be separate assessments was too broad; same-assessment measurements are possible. A claim of continuous preservation from matching digests was not adopted. The revised predicate is deliberately narrower.
  • A second fresh noninteractive Claude call reviewed the revised contract at fe441a7d66d99ff1cef9fa3c92fe0c3cb8bb877f (input SHA-256 312eb10ecae0319a76f6c0b42d8d7611bb91f3fc714f07467b3f4fa6071278de). Exit0/success, actual model claude-opus-5-5, one turn, input/source unchanged; no mandatory findings. It reviewed the changed contract with the complete proposal and primary source context, not a runtime implementation.

Validation

  • node scripts/check-repository.mjs: pass.
  • git diff --check: pass.
  • New document's relative links resolve; existing guide/README/version/pin contracts are unchanged.
  • Local validation ran document checks only; no additional local runtime test or live qualification was executed. The repository's existing CI runs automatically on this Draft; its current-head status is recorded below, without substituting historical green runs.

No merge, tag, release, npm publication, global installation or operational action is requested by this design PR.

Advisory questions for human design review

The follow-up review recommends further precision around intended-version evidence versus relative wire banner equality; the distinction between CLI/wrapper selection and existing SSH/shell/interpreter PATH behavior; recording exact SSH/agent/home context and invalid-path outcomes; and the disposition of historical guide/recovery debt. These are documented design questions, not permission to implement a reporter or revive #155.

Two requests for primary evidence were checked directly by Codex: the ADR header still explicitly says Proposed, and VALIDATION.md's 2026-10-02 integrity/results show the published 0.2.1 artifact on the destination as well as the operator. Those historical records are preserved, not promoted to current qualification.

Packaging-only follow-up after contract review

npm pack --dry-run --json --ignore-scripts showed that the new review-only design file would otherwise enter the npm archive and break its fixed allowlist. A nested docs/design/.npmignore now excludes only that file; before/after listing confirmed every other selected file is unchanged. The existing installed ADR points to this stable PR rather than a missing package-relative file. No release allowlist, runtime code or test expectation was changed.

The checklist contract document is byte-identical to Claude-reviewed fe441a7. This final delta changes only the packaging exclusion and cross-link; Codex checked it separately, without a third model review. Current PR contains two Markdown files and one narrowly scoped ignore file.

Final current-head verification

Head 353686d78ea3961de3718b7fa4592c0e4a091f79 passes all12checks, including macOS/Ubuntu Node22/24, Windows-native Node22/24, repository policy, release gate, CodeQL and GitGuardian. CLI run39524939366. The earlier contract-only CI run was cancelled as superseded; no failed-job rerun or weakened test expectation was used. Normal package checks passed with the proposal excluded from the archive.

PR remains Draft, auto-merge is not configured, and no issue is closed. These CI/review results are not human design acceptance or implementation authorization.

Define assessment-only states, evidence limits and the remaining qualification work without introducing a reporter, installer or authority/recovery engine. Preserve the historical ADR and defer implementation until human design review.

Refs #158
Require explicit selected command paths for diagnostic attribution, scope current digest comparisons without inheriting historical pass results, and clarify human decisions for open qualification debt. Keep every F1–F6 follow-up outside this checklist-only proposal.

Refs #158
@abruption abruption added documentation Improvements or additions to documentation priority:P2 Planned capability, platform extension or bounded research after prerequisites. labels Oct 21, 2026
Exclude only the unapproved checklist proposal with a nested npm ignore rule and use its stable PR URL in the installed ADR. A dry-run file-list comparison confirms no other package selection changes. The reviewed checklist contract text is unchanged.

Refs #158
@abruption

Copy link
Copy Markdown
Owner Author

Superseded by implementation PR #160 after the owner explicitly selected a repository-only read-only static reporter on 2026-10-21. The new PR includes this reviewed design history and the bounded extension. Closing this design-only Draft to avoid parallel merge paths; no commits, branches or worktrees are deleted and no implementation is merged. #158 and #23 remain open; #155 remains deferred.

@abruption abruption closed this Oct 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation priority:P2 Planned capability, platform extension or bounded research after prerequisites.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant