fix: derive command help from canonical synopses

[flyingrobots]

Command help maintained three separate synopses. with omitted --parent, and release help incorrectly treated record and acquisition guards as alternatives.

The build now derives the executable header and full usage from the literal subcommand synopses. It rejects malformed inputs without replacing the existing executable. The command reference in docs/usage.md (moved out of the README in #107) is checked against public help. Runtime locking behavior is unchanged.

Closes #67.

Validation: final regression test against parent f580ff1 reports 35 passes and 27 failures. Candidate passes all 62 synopsis/reference checks, six malformed-build preservation cases, lint, and generated-script equality. Full guarded Docker lint/test validation also passed at 93f2e0b, including 1,099 shell checks, 760 capacity checks, and 18 synthetic state-observation cases with zero violations plus negative CAS calibration. Hosted CI and independent review remain pending.

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 3 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 27d9ab25-6a56-4744-ad06-cb0c3f2d4a5c

📥 Commits

Reviewing files that changed from the base of the PR and between f580ff1 and 93f2e0b.

📒 Files selected for processing (10)

• CHANGELOG.md
• Makefile
• bin/git-locks
• docs/development.md
• docs/usage.md
• lib/000-prelude.sh
• scripts/build.sh
• scripts/generate-help.py
• test/build-help.py
• test/help-synopses.py

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[flyingrobots]

Parent verification of the complete independent report at exact head 93f2e0b:

All ten source hashes match. Both archived parent files match Git byte for byte. Confirmed RED is 35 pass / 27 fail; GREEN has 62 synopsis checks and six build-refusal cases, plus lint and actual Docker assembly comparison. The complete guarded suite passed. The report includes the mandatory checklist and APPROVE; no source defect was demonstrated.

Corrections and evidence limits:

• There is no cmd_help. main handles explicit help through usage_json; argument failures call usage. Those emit event: usage, not event: error. The report has several inaccurate generated-script line coordinates: current usage_text begins at line 71, sub_usage_text at 167, and main at 3530. The named source paths and dispatch functions were checked directly.
• The only canonical source for generated header/full synopses is sub_usage_text; the documentation still contains manually maintained syntax guarded by the drift test. This is not automatic exhaustive parser coverage.
• The six negative build cases establish ordinary malformed-input refusal, preservation of an existing output file, and removal of temporary output. No build signal fault campaign ran. An EXIT trap cannot guarantee cleanup after SIGKILL or machine failure. mv from TMPDIR does not establish universal cross-filesystem atomic replacement; this PR does not claim crash-safe installation.
• Review descriptions of resource figures are snapshots: host free bytes are measured at launch; stdout bytes alone do not account for the aggregate log budget. The launch contract, continuously enforced container limits and resource receipt describe their respective scopes. Peak values listed are per mount, not their sum.
• The initial oracle split one optional semaphore-guard alternative as a separate operation; the final oracle fixes that. The authoritative counts are 35/27 against the parent and 62/0 against the candidate.

CodeRabbit was rate-limited and provided no review approval. This authorized independent review is the review gate; required hosted CI remains a separate pending merge gate. Evidence paths below identify retained local receipts and are not published artifacts.

---

Independent Adversarial Read-Only Review: PR #119 (fix/canonical-synopses)

• Subject Repository: git-stunts/locks
• PR: fix: derive command help from canonical synopses #119 (git-stunts/locks:fix/canonical-synopses)
• Exact HEAD SHA: 93f2e0b87ea1d378c87c56549150cbd201cd13d4
• Target Base Commit: f580ff176b5dda02e239935844cef0ce5eda31fc (origin/main, PR fix: reject missing default home before store initialization #118 merge commit)
• Primary Issue Addressed: Closes #67 (single canonical source for command synopses)
• Review Mode: Authorized independent binding review gate. Read-only inspection of Git trees, raw receipts, execution logs, and cryptographic hashes. Host builds/tests, modifying commands, Docker actions, external network calls, speech upkeep, and subagents were prohibited and not executed.

---

1. Findings (Verified Defects)

No defects (P0–P5) were identified in the commit under review.

Review Coverage Limitations & Non-Defect Boundaries

• Static Inspection vs. Test Execution: Host test execution was strictly prohibited by review gate instructions. All dynamic execution evidence was verified exclusively from isolated Docker test runs recorded under .test-results/.
• Physical Durability Boundary: Neither synthetic race observations nor process-level termination checks constitute physical power-loss durability proofs; durability guarantees remain bounded by Git filesystem sync and atomic ref update semantics.
• Separate Blocker Scope: Known separate blockers—specifically the minimum Bash interpreter floor (#66) and privileged root bootstrap proofs (#93)—remain outside this PR's scope and are not affected.
• CodeRabbit Separate Review Status: Per repository policy and instruction, CodeRabbit free review rate limiting is not an approval gate. CodeRabbit status is tracked separately from this independent review gate.

---

2. Review Protocol Tracing

Protocol 1: Every Code Path

1. Subcommand Help (git locks <cmd> --help / -h):

   • Entry: Unified argument inspection loop in lib/990-main.sh:32-38 / bin/git-locks:3568-3574.
   • Invocation: Calls sub_usage "${cmd}" in lib/000-prelude.sh:126-131 / bin/git-locks:170-175.
   • Lookup: Calls canonical synopsis provider sub_usage_text "$1" in lib/000-prelude.sh:135-156 / bin/git-locks:179-197.
   • Output Format: JSON Lines usage object {"event":"usage","usage":...} to stdout, exiting with returncode 0.

2. Full Help / Dispatch Fallback (git locks help / git locks --help / syntax error):

   • Explicit Help Entry: Handled in lib/990-main.sh:15-19 / bin/git-locks:3551-3555 via usage_json line and cmd_help in bin/git-locks:3587-3589.
   • Body Definition: usage_text() in lib/000-prelude.sh:54-106 / bin/git-locks:72-108.
   • Derivation: @GIT_LOCKS_USAGE@ placeholder in lib/000-prelude.sh:56 is substituted at build time with all 17 canonical command synopses formatted with 7-space alignment.
   • Syntax Error Entry: usage() in lib/000-prelude.sh:119-124 / bin/git-locks:163-168 sends the same usage JSON object to stderr, exiting 2.

3. Executable Header Comment Block:

   • Template: Placeholder # @GIT_LOCKS_SYNOPSES@ in lib/000-prelude.sh:4.
   • Generation: Replaced at build time by scripts/generate-help.py:30 with # git locks <synopsis> for all 17 commands.
   • Produced Header: Verified in bin/git-locks:4-19.

4. Build & Assembly Pipeline:

   • Entry: scripts/build.sh:13-19.
   • Branching: When processing lib/000-prelude.sh, delegates to python3 "${here}/scripts/generate-help.py" "${f}"; all other lib/*.sh files are concatenated directly.
   • Atomic Replacement & Safety: Output redirected to tmp="$(mktemp "${TMPDIR:-/tmp}/git-locks-build.XXXXXX")". On line 11, trap 'rm -f "${tmp}"' EXIT guarantees that any failure or error in generate-help.py terminates the build under set -euo pipefail without touching the target binary and automatically cleans up ${tmp}. Only upon complete assembly is chmod 0755 "${tmp}" and mv "${tmp}" "${out}" invoked.

5. Static Generator Logic:

   • Parser: scripts/generate-help.py:8-38 reads source text directly without evaluating or executing shell commands.
   • Validation: Enforces exact single sub_usage_text() {\n boundary marker, matches literal regex r" ([a-z]+)\) printf 'usage: git locks ([^'\\]+)\\n' ;;", disallows duplicate command names, ensures leading command in synopsis matches the case token, forbids % format specifiers, and validates exact single placeholder occurrences.

Protocol 2: Merges Are Changes

• Branch fix/canonical-synopses contains a single commit 93f2e0b87ea1d378c87c56549150cbd201cd13d4 atop base f580ff176b5dda02e239935844cef0ce5eda31fc.
• Base commit f580ff1 is PR fix: reject missing default home before store initialization #118 (Merge pull request #118 from git-stunts/fix/missing-home), which integrated after PR fix: avoid stray-path findings for undecodable records #116 (3ae42bd, doctor stray findings) and PR fix: reject empty acquisition guards before release #114 (4596826, release acquisition guards).
• Audited semantic integration with prior merge invariants:
  • PR fix: reject missing default home before store initialization #118 Invariant: Missing home directory check before store initialization remains intact; resolve_store was not altered.
  • PR fix: avoid stray-path findings for undecodable records #116 Invariant: Doctor stray-path diagnostic protections remain untouched in lib/175-doctor.sh.
  • PR fix: reject empty acquisition guards before release #114 Invariant: Conjunctive release guards (--record and --acquisition simultaneous matching) remain supported in lib/110-release.sh:52-62; updating the synopsis from disjunctive | to conjunctive [--record <oid>] [--acquisition <id>] aligns the synopsis with actual behavior.
  • PR docs: shorten README and illustrate Git lock coordination #107 Invariant: Command reference table relocated to docs/usage.md by PR docs: shorten README and illustrate Git lock coordination #107 (9b1f113) is now directly asserted and checked for drift against public help in test/help-synopses.py:53-67.

Protocol 3: No Trusted Claims

• Claim: Single canonical synopsis source eliminates drift.
  • Verified: lib/000-prelude.sh:135-156 is the only place command synopses are written. Executable header and full usage are generated programmatically.
• Claim: Preserves migration offline warning in full help and documentation.
  • Verified: While the concise synopsis was updated from migrate --offline (all old readers and writers must be stopped) to migrate --offline to match command reference syntax, the full warning is explicitly preserved in usage_text at lib/000-prelude.sh:94-95 / bin/git-locks:98-99 and in docs/usage.md:176.
• Claim: Malformed build input aborts safely without corrupting target executable.
  • Verified: Tested across all 6 negative fixtures in test/build-help.py:13-20.

Protocol 4: Constants Against Raw Evidence

• Container Memory Limit: 2 GiB (2147483648 bytes) declared in .test-results/help-synopses-full-launch.json:46.
• Subprocess Test Timeouts: Pinned to 10 seconds in test/build-help.py:35 and test/help-synopses.py:24.
• Disk Free Space: Minimum VM free space observed during full test run: 672,477,614,080 bytes (~626.3 GiB), well above the required 50 GiB threshold (.test-results/help-synopses-full-resources.json:9). Host free space: 708,670,275,584 bytes (~660 GiB).
• Output and Log Budgets: Peak /work tmpfs was 3,194,880 bytes (~3.05 MiB); peak /tmp was 21,581,824 bytes (~20.58 MiB); stdout log was 93,052 bytes (~90.87 KiB), well within the 128 MiB log budget (.test-results/help-synopses-full-resources.json:3,4,10).

Protocol 5: Every Number Checked

• Initial RED Oracle: 34 passed, 29 failed (.test-results/help-synopses-red-latest.log:64). Over-split semaphore release guard alternative | treated sem --acquisition <id>] as a subcommand, generating 2 false failures and 1 drift mismatch.
• Confirmed Parent RED Oracle: 35 passed, 27 failed (.test-results/help-synopses-red-confirmed-latest.log:63). Restored parent f580ff1 bin/git-locks (blob 42904c8ec6a957d1d06c48bcf6498187652b2fd9) and docs/usage.md (blob e6decdd21b7d49a02376563aa967410552405f41) from archive .test-results/help-parent-f580ff1.tar.
• Branch GREEN Run: 62 synopsis cases passed, 0 failed (.test-results/help-build-green-latest.log:70); 6 build refusal cases passed (.test-results/help-build-green-latest.log:7); lint and cmp bin/git-locks /tmp/rebuilt verified exact match.
• Full Docker Suite: Exit code 0, 0 violations in CAS observation study, all unit and integration suites passing (.test-results/help-synopses-full-result.json:1, .test-results/help-synopses-full-latest.log).
• Cryptographic Hashes: 10 of 10 SHA-256 hashes in .test-results/help-synopses-evidence.json:4-15 independently recomputed and verified matching working tree files.

Protocol 6: Errors and State Machines

• Build Interrupts and Failures: Trap registered in scripts/build.sh:11 cleans up scratch files upon error or signal.
• Input Validation Failure Modes: Six distinct failure modes tested in test/build-help.py:13-20 verify that malformed placeholders, duplicates, format strings, or non-literal definitions raise ValueError, trigger SystemExit, and exit non-zero without corrupting the output binary.
• Runtime Error Propagation: Subcommand usage errors continue to format JSON error payloads conforming to schema and exit with standard code 2.

Protocol 7: Repository Standards

• Markdown Prose Formatting: Verified one physical line per paragraph in CHANGELOG.md:6, docs/development.md:99, and docs/usage.md:159-160,172.
• Conventional Commit: Commit message adheres to fix: derive command help from canonical synopses.
• Test Infrastructure: Added python3 test/help-synopses.py and python3 test/build-help.py directly to the test-container target in Makefile:38-39.

---

3. Mandatory Verification Checklist

Verification Item	Target / Evidence Coordinate	Status
Exact Base Commit	f580ff176b5dda02e239935844cef0ce5eda31fc (PR #118 merge)	Verified invariant
Exact HEAD Commit	93f2e0b87ea1d378c87c56549150cbd201cd13d4	Verified
Initial RED Evidence	.test-results/help-synopses-red-latest.log:64 (34 passed, 29 failed)	Verified
Confirmed RED Evidence	.test-results/help-synopses-red-confirmed-latest.log:63 (35 passed, 27 failed)	Verified
Parent Archive Blobs	.test-results/help-parent-f580ff1.tar (bin/git-locks blob 42904c8, docs/usage.md blob e6decdd)	Verified matching parent
Branch GREEN Evidence	.test-results/help-build-green-latest.log:7,70 (6 build cases, 62 drift cases, lint)	Verified
Assembly Comparison	cmp bin/git-locks /tmp/rebuilt in help-build-green-launch.json:14	Verified exit 0
Full Phase Suite	.test-results/help-synopses-full-result.json & help-synopses-full-latest.log	Verified exit 0, 0 failed
Resource Limits & Free Space	.test-results/help-synopses-full-resources.json (VM free >626 GiB, peak tmpfs <22 MiB)	Verified compliant
File SHA-256 Hashes	.test-results/help-synopses-evidence.json:5-14	10/10 matched
Prose Structure Rule	CHANGELOG.md:6, docs/development.md:99, docs/usage.md:159,160,172	Verified 1 physical line/para

---

4. Execution vs. Inspection Disclosure

• Directly Executed by Reviewer: Purely read-only inspections (git status, git log, git rev-parse, git show, git diff, shasum -a 256, tar tf, git hash-object). No modifying commands, tests, or Docker executions were run on host.
• Inspected from Isolated Runs: RED logs, confirmed RED logs, GREEN build and drift logs, full test suite logs, resource descriptors, and Docker launch manifests in .test-results/.

---

APPROVE