From 7d3baa62e950c62952caf956e59505eaceda44cb Mon Sep 17 00:00:00 2001 From: "Elias S.W." <310511041+eliasruntime@users.noreply.github.com> Date: Sat, 12 Sep 2026 14:48:01 +0800 Subject: [PATCH] feat: scaffold command-only maintenance workflows --- CHANGELOG.md | 4 + README.md | 7 ++ docs/MAINTENANCE_CASE_2026-09-12.md | 78 +++++++++++++++++++ .../evidence/macos-replacement-candidate.json | 10 +-- docs/evidence/maintenance-2026-09-12.json | 61 +++++++++++++++ scripts/package-smoke.mjs | 11 ++- src/cli.js | 15 ++-- test/cli.test.js | 45 +++++++++++ 8 files changed, 218 insertions(+), 13 deletions(-) create mode 100644 docs/MAINTENANCE_CASE_2026-09-12.md create mode 100644 docs/evidence/maintenance-2026-09-12.json diff --git a/CHANGELOG.md b/CHANGELOG.md index 51de0e0..f25ace3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # Changelog +## Unreleased — after 0.2.0-rc.1 + +- Add explicit `init --command-only` scaffolding for CLI and CI maintenance. Start with one command criterion; retain input discovery, evidence states and overwrite refusal. The default scaffold continues to include a visual criterion. + ## 0.2.0-rc.1 — prerelease candidate - Normalize selected Intake snapshots consistently at every contract-file entry; validate the full source/requirement structure before admitting confirmed items. Keep explicit mappings and optional imports. diff --git a/README.md b/README.md index d7ddfe9..e0a8191 100644 --- a/README.md +++ b/README.md @@ -75,6 +75,13 @@ Initialize a graph: proofline init ``` +For headless maintenance, the **unreleased source checkout** also supports +`node ./bin/proofline.js init /path/to/project --command-only`. It creates one +command criterion, so a CLI-only task can complete without removing an unrelated +screenshot criterion. Review the generated acceptance text and discovered input +paths before recording checks. The published `0.2.0-rc.1` archives keep their +original interface; see the [first-use maintenance case](docs/MAINTENANCE_CASE_2026-09-12.md). + Describe acceptance criteria in `proofline.json`: ```json diff --git a/docs/MAINTENANCE_CASE_2026-09-12.md b/docs/MAINTENANCE_CASE_2026-09-12.md new file mode 100644 index 0000000..327b9a0 --- /dev/null +++ b/docs/MAINTENANCE_CASE_2026-09-12.md @@ -0,0 +1,78 @@ +# First-use observation: Workprint CI maintenance + +On 2026-09-12, the Lab maintainer used the **published Proofline 0.2.0-rc.1 CLI** +while reviewing two existing Dependabot pull requests in Workprint: +[checkout #1](https://github.com/codex-improvement-lab/codex-workprint/pull/1) +and [setup-node #2](https://github.com/codex-improvement-lab/codex-workprint/pull/2). +This was actual internal maintenance, not an external-user trial or a replay +of the earlier [14/22-operation study](SIMPLIFICATION_RESULTS_2026-09-09.md). + +## Task and evidence + +Each PR changes one pinned GitHub Action in the existing workflow. The maintainer +checked the upstream tag/commit, relevant breaking changes, unchanged read-only +permissions, and all four Windows/macOS × Node 22/24 jobs. Each branch was refreshed +against main before verification and merged sequentially. The second refresh +included the first merge. A final check targets the combined main revision. + +Proofline wraps a maintainer-authored, read-only GitHub API checker. The checker +requires an explicit target SHA, the expected diff and action pins, four successful +jobs, and successful test/release/build/package steps. Its script and target files +are tracked command inputs. Each PR and the combined result get separate receipts. + +| Revision under review | Hosted CI | Result | +| --- | --- | --- | +| Refreshed checkout PR, `db68cfb0d320ffb00d72edec1a0120b7ce40892f` | [34678558827](https://github.com/codex-improvement-lab/codex-workprint/actions/runs/34678558827) | Four jobs passed; PR merged | +| Refreshed setup-node PR, `bd80dc70b8420dcf31d8b2e1f1fee47363641a4c` | [34678715695](https://github.com/codex-improvement-lab/codex-workprint/actions/runs/34678715695) | Four jobs passed; PR merged | +| Combined main, `eeec646c6663fad59805d5ac5e235107f6dd264d` | [34678840844](https://github.com/codex-improvement-lab/codex-workprint/actions/runs/34678840844) | Four jobs passed; only the workflow changed | + +The final Proofline query returned three verified receipts and zero gaps. The +[redacted observation record](evidence/maintenance-2026-09-12.json) retains the +selected revisions, receipt hashes and measurement limits. + +A command receipt here records **a Windows process reading GitHub-hosted CI +results**. It does not mean Proofline independently ran the remote tests or observed +a physical Mac. The API checker remains private because it uses the maintainer's +local credential helper; no credentials, local paths, raw receipt or command output +are published in this case note. + +## First-use friction and resulting change + +The released `init` scaffold creates a command criterion and a screenshot criterion. +This task has no visual acceptance condition, so the maintainer had to remove the +screenshot criterion while configuring the actual CI checks. + +The **unreleased source checkout** adds one explicit option: + +```sh +node ./bin/proofline.js init /path/to/project --command-only +``` + +It starts with one command criterion and still discovers existing conventional +input paths. Acceptance wording and input associations require review. The default +scaffold continues to include a visual criterion; existing manifests are never +overwritten. Missing evidence starts as missing, a failed command stays failed, +and changed tracked inputs make an old passing receipt stale. + +The option is not present in the frozen 0.2.0-rc.1 release archives. CLI regression +and installed-package smoke cover a headless init/run/check loop, a spaced project +path, source invalidation, failed execution, and overwrite refusal. + +## What this observation can support + +It identifies one irrelevant criterion that needs removal in this class of task. It does not +establish net savings. Manifest customization, explicit target updates, and the +API checker all cost work. GitHub already retains the underlying CI history; the +additional Proofline record needs to earn its maintenance cost on subsequent use. + +The observed product path used eight CLI invocations: one version probe, one init, +three recorded API checks, one readiness check, one gaps query and one Markdown +report. The custom checker, manifest customization and target-file writes are +additional work. This invocation count is not the earlier study's operation metric; +the scaffold option does not by itself remove a CLI invocation in this case. + +The owner had already inspected notifications and initial PRs before starting the +record. There is no frozen comparison arm, complete task timer, model-usage record, +external-user observation, or repeat-use outcome. The earlier controlled study +remains unchanged. No artificial requirement change was introduced to demonstrate +Goal Delta. diff --git a/docs/evidence/macos-replacement-candidate.json b/docs/evidence/macos-replacement-candidate.json index 4d9dc3b..cbf89a3 100644 --- a/docs/evidence/macos-replacement-candidate.json +++ b/docs/evidence/macos-replacement-candidate.json @@ -3,13 +3,13 @@ "product": "codex-proofline", "gateVersion": 2, "scope": "runtime-gate-tests-v1", - "id": "codex-proofline-macos-rc-24fc73aa5cbb10e1", - "contentSha256": "24fc73aa5cbb10e1beadd169d46f14ed5dd521f743002116959b88eaee4fede1", + "id": "codex-proofline-macos-rc-ec04ead371789c89", + "contentSha256": "ec04ead371789c89607f4e8ab063342fee7e2ea9fed3ac579479e44db66c573b", "contentFiles": 53, - "installedVersion": "0.2.0-rc.1+codex.macos-24fc73aa5cbb10e1", + "installedVersion": "0.2.0-rc.1+codex.macos-ec04ead371789c89", "status": "awaiting-full-real-mac-rerun", "previousMacEvidenceImported": false, - "generatedOn": "2026-09-09", + "generatedOn": "2026-09-12", "evidenceClass": "source-derived-candidate-identity-not-macos-execution", - "documentationUpdate": "Publication README and demo links refreshed; release v0.2.0-rc.1 remains frozen at 033903f6602b6f490e93df6d9364ec56b5ae35f3. No prior physical-Mac result transferred." + "documentationUpdate": "Unreleased command-only init and regression/package coverage. Release v0.2.0-rc.1 stays frozen; physical Mac and fresh-task activation remain pending." } diff --git a/docs/evidence/maintenance-2026-09-12.json b/docs/evidence/maintenance-2026-09-12.json new file mode 100644 index 0000000..a722f0d --- /dev/null +++ b/docs/evidence/maintenance-2026-09-12.json @@ -0,0 +1,61 @@ +{ + "schemaVersion": "proofline-maintenance-observation/1", + "date": "2026-09-12", + "evidenceClass": "actual-internal-maintenance-observation", + "project": "codex-improvement-lab/codex-workprint", + "prooflineVersion": "0.2.0-rc.1", + "prooflineRelease": "https://github.com/codex-improvement-lab/codex-proofline/releases/tag/v0.2.0-rc.1", + "observationEnvironment": "Windows / GitHub API readback", + "records": [ + { + "evidenceId": "C-CHECKOUT/ci", + "head": "db68cfb0d320ffb00d72edec1a0120b7ce40892f", + "ci": "https://github.com/codex-improvement-lab/codex-workprint/actions/runs/34678558827", + "successfulJobs": 4, + "receipt": "sha256:702ba7cf6c6ff95af8735240c2bcf974ce2ac2425b2c0d54274398f535cafb5b" + }, + { + "evidenceId": "C-NODE/ci", + "head": "bd80dc70b8420dcf31d8b2e1f1fee47363641a4c", + "ci": "https://github.com/codex-improvement-lab/codex-workprint/actions/runs/34678715695", + "successfulJobs": 4, + "receipt": "sha256:4ff887e5c64ffa25cf08ba40788adf49ab04f6ce0c644b2bcb486017f75ad4fd" + }, + { + "evidenceId": "C-MAIN/ci", + "head": "eeec646c6663fad59805d5ac5e235107f6dd264d", + "ci": "https://github.com/codex-improvement-lab/codex-workprint/actions/runs/34678840844", + "successfulJobs": 4, + "receipt": "sha256:9264700d7bad3f688a15c5b0585f705107056e73ede25d7df923a714b4cddf9b" + } + ], + "finalQuery": { + "verified": 3, + "missing": 0, + "stale": 0, + "declaredOnly": 0, + "failed": 0, + "returnedGaps": 0 + }, + "observedCliInvocations": { + "version": 1, + "init": 1, + "run": 3, + "check": 1, + "query": 1, + "report": 1, + "total": 8, + "definition": "Product-path calls only; additional checker authoring, manifest and target writes are not included. Not comparable to the earlier full-operation replay metric." + }, + "limits": { + "externalUser": false, + "repeatUseMeasured": false, + "comparisonArm": null, + "completeTaskTime": null, + "modelUsage": null, + "goalDeltaExercise": false, + "physicalDeviceObservation": false, + "netBenefit": "unmeasured", + "receiptBoundary": "Hashes associate private local records with this summary; hashes alone do not prove record authenticity or task correctness." + } +} diff --git a/scripts/package-smoke.mjs b/scripts/package-smoke.mjs index e76039c..15f753a 100644 --- a/scripts/package-smoke.mjs +++ b/scripts/package-smoke.mjs @@ -28,6 +28,15 @@ try { await access(path.join(packageRoot, ".codex-plugin", "plugin.json")); await access(path.join(packageRoot, "skills", "proofline", "SKILL.md")); await access(path.join(packageRoot, "hooks", "hooks.json")); + const headless = path.join(scratch, "headless project"); + const headlessManifest = path.join(headless, "proofline.json"); + invoke(["init", headless, "--command-only"]); + invoke(["check", "--manifest", headlessManifest, "--json"], 1); + invoke(["run", "AC-01/tests", "--manifest", headlessManifest, "--", process.execPath, "-e", + "require('node:assert/strict').equal(require('node:path').basename(process.cwd()), 'headless project')"]); + const headlessStatus = JSON.parse(invoke(["check", "--manifest", headlessManifest, "--json"])); + assert.equal(headlessStatus.ready, true); + assert.equal(headlessStatus.summary.totalProofs, 1); invoke(["init"]); const manifestPath = path.join(scratch, "proofline.json"); const manifest = JSON.parse(await readFile(manifestPath, "utf8")); @@ -85,7 +94,7 @@ try { assert.equal(run.status, 0, run.stderr); } assert.equal(JSON.parse(invoke(["query", "--manifest", selectedManifest, "--contract", "requirements-next.json", "--dependencies", "deps.json", "--gaps"])).evidence.length, 0); - process.stdout.write("Installed package smoke passed: base CLI/five states/reports/plugin, exact Goal Delta projections and JSON, Intake import, configuration checks, bound run/capture and target query.\n"); + process.stdout.write("Installed package smoke passed: headless init loop, base CLI/five states/reports/plugin, exact Goal Delta projections and JSON, Intake import, configuration checks, bound run/capture and target query.\n"); } finally { assert.ok(scratch.startsWith(path.join(os.tmpdir(), "proofline-package-smoke-"))); await rm(scratch, { recursive: true, force: true }); diff --git a/src/cli.js b/src/cli.js index 8bbf986..d5e1a5f 100644 --- a/src/cli.js +++ b/src/cli.js @@ -24,7 +24,7 @@ const HELP = ` Codex Proofline — proof, not promises Usage: - proofline init [directory] + proofline init [directory] [--command-only] proofline run [--environment