Skip to content

ci: add launcher-standard prose↔a2ml lock-step gate#172

Merged
hyperpolymath merged 1 commit into
mainfrom
ci/launcher-standard-lockstep
May 26, 2026
Merged

ci: add launcher-standard prose↔a2ml lock-step gate#172
hyperpolymath merged 1 commit into
mainfrom
ci/launcher-standard-lockstep

Conversation

@hyperpolymath
Copy link
Copy Markdown
Owner

Summary

launcher/README.adoc §Sync requirement declares that the
machine-readable form (launcher/launcher-standard.a2ml) and the prose
form (docs/UX-standards/launcher-standard.adoc) MUST be edited in the
same PR, and calls drift between them a "standards-compliance bug"
but nothing enforced the rule. The recently-fixed cross-doc
contradictions in #170
were exactly the drift this rule was meant to prevent.

This adds .github/workflows/launcher-standard-lockstep.yml — a hard
gate that runs on every PR touching either file. If only one is in the
diff, it fails with a message naming the missing partner and pointing
back at §Sync requirement.

How it works

```yaml
on:
pull_request:
paths:
- 'launcher/launcher-standard.a2ml'
- 'docs/UX-standards/launcher-standard.adoc'
```

GitHub's paths: filter ensures the workflow only triggers when one of
the two files is touched (cheap — no wasted runs for unrelated PRs).
Inside the job, a 30-line bash check diffs pull_request.base.sha
against pull_request.head.sha, computes which of the two files are
touched vs missing, and fails iff the touched set is non-empty but
incomplete.

Dry-run verification

Logic dry-run locally against six synthetic diffs:

Diff Expected Result
only a2ml touched FAIL — drift FAIL ✓
only adoc touched FAIL — drift FAIL ✓
both touched PASS PASS ✓
both touched + unrelated PASS PASS ✓
neither touched skip (no trigger) workflow doesn't run ✓
a2ml + unrelated (drift) FAIL — drift FAIL ✓

Pattern conformance

Modelled on the existing makefile-blocker.yml gate:

  • Same SPDX header.
  • Same actions/checkout@de0fac2… pin (verified live against
    github.com/actions/checkout — corresponds to v4 commit
    de0fac2e4500dabe0009e67214ff5f5447ce83dd "Fix tag handling" #2356).
  • Same concurrency block that cancels superseded runs (safe — this is
    a read-only check, no mutations).
  • Same permissions: contents: read.

Scope notes

  • Initial group is the 2-file pair the README literally calls out.
    Once #171
    lands and introduces launcher/resolve-desktop-tools.sh, a follow-up
    should extend the group to include the resolver (which mirrors
    [resolution] in the a2ml and currently relies on reviewer
    discipline).
  • Hard fail, not warning. The README uses "MUST" / "is a bug"
    language; the gate matches that strictness. Genuinely one-sided
    edits (e.g. a prose-only typo fix with no a2ml equivalent) need a
    no-op whitespace touch to the other file — the error message
    documents this escape.
  • Not added to required-checks list. Branch-protection config
    lives outside the repo. Owner can promote this to a required check
    via the UI or .github/settings.yml once they've seen it pass green
    on a few PRs.

Coordination

Test plan

🤖 Generated with Claude Code

The launcher/README.adoc §Sync requirement declares that
`launcher/launcher-standard.a2ml` and
`docs/UX-standards/launcher-standard.adoc` MUST be edited in the same
PR, and calls drift between them a "standards-compliance bug" — but
nothing enforced the rule. The recently-fixed cross-doc contradictions
(PR #170) were exactly the drift this rule was meant to prevent.

This gate runs on every PR that touches either file. If only one is in
the diff, it fails with a message naming the missing partner and
referencing §Sync requirement so the contributor knows the rule.

Pattern matches the existing makefile-blocker.yml gate (same
actions/checkout SHA pin, same concurrency-cancel-superseded shape,
same SPDX header). Logic dry-run locally against six synthetic
diffs (a2ml-only, adoc-only, both, both+unrelated, neither,
a2ml+unrelated) — all six produce the expected pass/fail/skip
outcomes.

Scope notes:
- Initial group is the 2-file pair the README literally calls out
  (a2ml + adoc). Once PR #171 lands and introduces
  launcher/resolve-desktop-tools.sh, a follow-up should extend the
  group to include the resolver.
- Hard fail, not warning. The README uses "MUST" / "is a bug"
  language; the gate matches that strictness. Genuinely one-sided
  edits (prose-only typos with no a2ml equivalent) need a no-op
  whitespace touch to the other file, documented in the error message.

Action SHA pin (actions/checkout@de0fac2…) verified live against
github.com/actions/checkout — corresponds to v4 "Fix tag handling"
commit (#2356).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@github-actions
Copy link
Copy Markdown

🔍 Hypatia Security Scan

Findings: 118 issues detected

Severity Count
🔴 Critical 64
🟠 High 43
🟡 Medium 11

⚠️ Action Required: Critical security issues found!

View findings
[
  {
    "reason": "Action hyperpolymath/standards/.github/workflows/deno-ci-reusable.yml@main needs attention",
    "type": "unpinned_action",
    "file": "deno-ci-reusable.yml",
    "action": "pin_sha",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "Action hyperpolymath/standards/.github/workflows/governance-reusable.yml@main needs attention",
    "type": "unpinned_action",
    "file": "governance-reusable.yml",
    "action": "pin_sha",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "Action hyperpolymath/standards/.github/workflows/governance-reusable.yml@main needs attention",
    "type": "unpinned_action",
    "file": "governance.yml",
    "action": "pin_sha",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "Python file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/standards/standards/a2ml-templates/state-scm-to-v2.py",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/standards/standards/a2ml/bindings/deno/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/standards/standards/lol/test/vitest.config.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/standards/standards/k9-svc/bindings/deno/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "Agda postulate assumes without proof -- potential soundness hole (4 occurrences, CWE-704)",
    "type": "agda_postulate",
    "file": "/home/runner/work/standards/standards/lol/proofs/theories/information_theory.agda",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "critical"
  },
  {
    "reason": "believe_me undermines formal verification (1 occurrences, CWE-704)",
    "type": "believe_me",
    "file": "/home/runner/work/standards/standards/lol/src/abi/Locale.idr",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "critical"
  },
  {
    "reason": "Wildcard CORS -- restrict to specific origins or use env var (1 occurrences, CWE-942)",
    "type": "js_wildcard_cors",
    "file": "/home/runner/work/standards/standards/consent-aware-http/examples/reference-implementations/deno/aibdp_middleware.js",
    "action": "flag",
    "rule_module": "code_safety",
    "severity": "high"
  }
]

Powered by Hypatia Neurosymbolic CI/CD Intelligence

@hyperpolymath hyperpolymath enabled auto-merge (squash) May 26, 2026 09:02
hyperpolymath added a commit that referenced this pull request May 26, 2026
…ifest

Filed alongside the 8 launcher-standard PRs (#170, #171, #172, #173,
#175, #176, #177, #179) so reviewers landing on any individual PR
can find the full picture in one place.

Two files following the existing `docs/audits/` convention:

- launcher-standard-review-2026-05-26.adoc — prose narrative for
  humans. Headline findings table (class × finding × addressed-in PR),
  PR map (number, branch, files, class), what-this-campaign-produces
  summary, deferred follow-ups, method notes including the
  parallel-session amend incident and how recovery worked.

- launcher-standard-review-2026-05-26.a2ml — machine-readable manifest
  for tooling (PR-batching bots, change-impact analyzers,
  launch-scaffolder regenerators). Same PR set as parseable A2ML:
  per-PR file lists, addressed-issues, new-files lists, new-a2ml-keys
  lists, plus coordination notes (spec-version conflict resolution,
  lock-step gate trigger map) and deferred-followups with gating
  conditions. Includes a session-lessons-captured block pointing at
  the two memory entries written during this campaign.

Pattern matches existing gap-matrix-2026-04-17.a2ml (A2ML extension
syntax including @abstract: block). Pure tomllib does NOT parse A2ML;
the repo's A2ML tooling does.

Signing-key fingerprint deliberately NOT recorded inline — gitleaks's
generic-api-key rule misclassifies 40-char PGP fingerprints as
secrets. The all-prs-gpg-signed flag is the load-bearing assertion;
the fingerprint is recoverable from `git log --show-signature` if
anyone needs to verify against a specific key.

Independent of all 8 review PRs — touches only docs/audits/.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
hyperpolymath added a commit that referenced this pull request May 26, 2026
…e format (#173)

## Summary

The launcher-standard requires `--help` but not `--version`, so
launchers
had no obligation to emit a version string. Result: field bug reports
consistently lack a build identity ("it's broken on my machine" with no
SHA, no way to bisect, no way to tell two builds apart).

This adds `--version` (and the alias `-V`) to the required meta-modes.
The first line of output MUST follow a machine-greppable format:

\`\`\`
{app-name} {version} ({build-sha-short}) [{platform}]
\`\`\`

Example: `aerie-launcher 0.4.2 (a1b2c3d) [linux-x86_64]`

Additional lines (build date, runtime versions, dep summary) MAY follow.
Exit code MUST be 0 on success.

## Changes

- **`launcher/launcher-standard.a2ml`**: added `--version` to
  `[required-modes].meta`; added new `[version-output]` table specifying
  the first-line format, an example, exit code, and machine-greppable
  flag.
- **`docs/UX-standards/launcher-standard.adoc`**: added a row to the
  §Required Modes table describing `--version` / `-V`, the format, and
  the rationale.

Both files updated in the same commit per the §Sync requirement and the
lock-step CI gate (PR #172) — this PR is a good first live test of that
gate.

## Test plan

- [x] a2ml parses (python tomllib): `meta = ['--help', '--version']`,
      `[version-output]` round-trips with all four fields intact.
- [x] AsciiDoc table renders (visual — added one row, no structural
      changes).
- [ ] Lock-step gate (#172) goes green on this PR's first push (both
      files in diff).

## Coordination

- Independent of #170, #171, #172. The lock-step gate runs on every PR
  touching either of the two group files, so this PR will be one of
  the first live exercises of that gate once #172 lands.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
hyperpolymath added a commit that referenced this pull request May 26, 2026
…#176)

## Summary

`keepopen.sh` always emitted ANSI colour escapes — even when the user
redirected output to a file or pipeline, and even when `NO_COLOR=1`
was set. [no-color.org](https://no-color.org/) has been the canonical
opt-out env var since 2017; respecting it is one of the cheapest UX
wins available.

## Change

At the top of `keepopen.sh`, if either `NO_COLOR` is set OR stdout is
not a TTY, all colour variables become empty strings. Banners and
prefix labels become plain text — still loud and clearly labelled,
just without escapes.

\`\`\`bash
if [[ -n "${NO_COLOR:-}" ]] || [[ ! -t 1 ]]; then
    C_RED='' C_YEL='' C_CYA='' C_GRN='' C_BOLD='' C_RST=''
else
    # original ANSI definitions
fi
\`\`\`

## Verified

\`\`\`
$ NO_COLOR=1 keepopen.sh testapp /tmp false false | grep -c $'\033'
0
$ keepopen.sh testapp /tmp false false | grep -c $'\033' # piped → not
TTY
0
\`\`\`

Desktop-launch path keeps colour (real terminal, no `NO_COLOR`), so
the on-screen failure banners are unchanged. The new behaviour only
fires when:

- User has `NO_COLOR` set globally (their explicit preference), or
- Output is piped to a file / capture (CI logs, `tee`, `.log`
  redirects)

## Scope

Touches `launcher/keepopen.sh` only — not part of the
a2ml↔adoc lock-step group, so the gate in #172 does not fire on this
PR.

## Coordination

Independent of all other open launcher-standard PRs (#170, #171,
#172, #173, #175) — different file, no conflicts in any merge order.

## Test plan

- [x] `NO_COLOR=1` produces zero ANSI escapes
- [x] Pipe (non-TTY stdout) produces zero ANSI escapes
- [x] Default TTY behaviour unchanged (loud red/yellow banners)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
hyperpolymath added a commit that referenced this pull request May 26, 2026
…ttack hardening) (#175)

## Summary

The launcher-standard specified `/tmp/{app-name}-server.pid` and
`/tmp/{app-name}-server.log` as the required runtime paths. Predictable
names in a world-writable directory are a **symlink-attack target** on
any shared host:

- An attacker can pre-create `/tmp/<app>-server.pid` containing their
  own PID. The launcher's `is_running()` returns true, and
  `stop_server()` will `kill <attacker-pid>` — DoS or signal-handling
  abuse.
- Similar pattern for the log: pre-symlink `/tmp/<app>-server.log` →
  some target the attacker wants clobbered, then the launcher's
  `nohup ... > LOG_FILE` does the write.
- The standard already warns "don't log sensitive information"
  (§Best Practices > Security), but the predictable-path defence is
  belt-and-braces.

## Fix

Route both to XDG dirs with documented fallback ladders:

- **PID** → `${XDG_RUNTIME_DIR:-${TMPDIR:-/tmp}}/<app>-server.pid`.
  `$XDG_RUNTIME_DIR` is mode `0700` and user-scoped per the XDG Base
  Directory spec (Linux). `$TMPDIR` covers macOS / BSDs (typically
  `/var/folders/.../T`, per-user). `/tmp` remains only as a last-resort
  fallback for hosts that set neither (rare).
- **Log** → `${XDG_STATE_HOME:-$HOME/.local/state}/<app>/server.log`.
  Per-user, survives reboot, not world-writable. The `<app>` subdir
  isolates each launcher's logs.

## Changes

Both files in the same commit per the lock-step requirement
(and the gate in #172):

- **`launcher/launcher-standard.a2ml`**
  - `[runtime].pid-file-pattern` / `log-file-pattern` updated with
    fallback ladders + commented rationale
  - `[disinteg].preserve` updated to reference the new log dir
- **`docs/UX-standards/launcher-standard.adoc`**
  - Standard Launcher Template snippet uses XDG paths + `mkdir -p`
    for the state dir
  - §What `--disinteg` removes / does not remove: paths updated
  - Desktop File `Exec=` example log-arg updated
  - Calling Convention daemon-chain example updated
  - Debugging Checklist now uses `$LOG_FILE` / `$PID_FILE` variable
    refs rather than literal paths
  - §Best Practices > Logging: lead bullet rewritten with rationale
  - §Best Practices > Security: new lead bullets explaining the
    attack vector and the XDG choice
  - §Compliance Checklist: "Log to predictable location (`/tmp/...`)"
    replaced with the XDG requirement

Remaining `/tmp/` mentions in the prose are in *forbidden-patterns*
text that explicitly tells readers NOT to use `/tmp` — intentional.

## Compatibility

Bash-expansion syntax (`${VAR:-${VAR2:-/literal}}`) matches the
shell-expansion style already in the a2ml (e.g.
`$HOME/.local/share/applications` in `[integration.linux]`). Any
consumer that already interpolates `$HOME` here will handle
`${...:-...}`
without changes.

Existing launchers that hard-coded `/tmp/<app>-server.pid` continue to
work but become non-compliant; no break for them, just a green-field
contract change for new launchers and a flagged migration for old
ones.

## Coordination

- Independent of #170, #171, #172, #173. No file overlap.
- Lock-step gate (#172) will go green on first push (both files in
  diff).

## Notes

- Spec `[spec].version` intentionally NOT bumped — five PRs (#170,
  #171, #173, this one, plus any future) all touch the contract; the
  merger sequences them.

## Test plan

- [x] a2ml parses (python tomllib): new patterns round-trip cleanly,
      `[disinteg].preserve` reflects the new log path
- [x] No `/tmp/` literals remain in non-forbidden-patterns prose
      (grep verified)
- [ ] Live lock-step gate (#172) goes green on first push

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
hyperpolymath added a commit that referenced this pull request May 26, 2026
…-chain (#179)

## Summary

The a2ml declared `[soft-attach]` and `[error-visibility]` contracts
but provided no reference implementations. Every downstream launcher
had to re-implement the "if-installed-then-invoke" pattern and the
GUI dialog ladder — guaranteed drift, and a common reason downstream
launchers either skip these features (silent failures stay silent) or
implement them inconsistently.

This adds two sourceable bash helpers in `launcher/`, mirroring the
contract semantics from the a2ml, plus prose with graceful-degradation
usage patterns.

## `launcher/gui-error.sh`

`hp_gui_error "title" "message"`:

| Condition | Behaviour |
|-----------|-----------|
| Always | Write `[title] message` to stderr |
| stderr is TTY or `NO_GUI_ERROR=1` | stderr only, return 0 |
| no `\$DISPLAY` and no `\$WAYLAND_DISPLAY` | return 1 (cannot show GUI)
|
| Else | Try `kdialog → zenity → notify-send → xmessage`; first success
wins |

Mirrors `[error-visibility].gui-dialog-chain` exactly. Verified
locally: `NO_GUI_ERROR=1 ./launcher/gui-error.sh "T" "M"` → stderr
"[T] M", exit 0.

## `launcher/soft-attach.sh`

Three primitives mirroring the three shapes in `[soft-attach].tools`:

\`\`\`bash
hp_soft_attach_present "command"          # 0 if on PATH
hp_soft_attach_run "command line" # run if first token present, silent
no-op + 0 if missing
hp_soft_attach_event "tool" "event-name" [args] # `tool emit event-name
args` if present, silent no-op if missing
\`\`\`

All non-fatal — missing tools never break the launcher (per the
§soft-attach spec: *"called if present, silently skipped if absent"*).
CLI mode for ad-hoc use:

\`\`\`
./soft-attach.sh run "hypatia diagnose --app foo"
./soft-attach.sh event feedback-o-tron launcher:start_failed
./soft-attach.sh present hypatia
\`\`\`

## a2ml contract additions

`[error-visibility]`:
- `reference-impl = "launcher/gui-error.sh"` (pointer)
- `suppress-env-var = "NO_GUI_ERROR"` (formalises the override name)

`[soft-attach]`:
- `reference-impl = "launcher/soft-attach.sh"` (pointer)
- Each `tools` entry now carries explicit `style`
  (`"event" | "command"`) and `trigger` (e.g. `"on-start-failed"`) so
  launchers know **WHEN** to invoke each tool, not just **HOW**.
  Previously only `feedback-o-tron` had an explicit failure trigger.

## Prose additions (`launcher-standard.adoc`)

- §Error Handling: rewritten with `hp_gui_error` integration, graceful
  degradation pattern, and a NOTE on stderr-always behaviour
- §Soft-Attach (new subsection): documents the three primitives, the
  graceful-degradation source pattern, and an example `on_start_failed`
  hook wiring all three default tools

## Test plan

- [x] a2ml parses (python tomllib); new fields round-trip cleanly
- [x] Both helpers pass `bash -n`
- [x] `hp_gui_error` writes stderr + respects `NO_GUI_ERROR`
- [x] `hp_soft_attach_present` returns 0/1 correctly
- [x] `hp_soft_attach_run` runs installed, silently skips missing
- [x] `hp_soft_attach_event` silently skips missing tool
- [ ] Manual dialog test (deferred — requires KDE/GNOME desktop;
      logic matches well-documented invocation conventions per each
      dialog's man page)
- [ ] Lock-step gate (#172) goes green on first push (both files in
diff)

## Coordination

Independent of #170, #171, #172, #173, #175, #176, #177 — no file
overlap. Builds on the resolution ladder shipped in #171
(`hp_resolve_desktop_tools` is referenced in the prose examples) so
the new helpers are findable wherever `.desktop-tools/` resolves.
Both work standalone or via the ladder.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@hyperpolymath hyperpolymath merged commit fd11d1f into main May 26, 2026
18 checks passed
@hyperpolymath hyperpolymath deleted the ci/launcher-standard-lockstep branch May 26, 2026 14:41
hyperpolymath added a commit that referenced this pull request May 26, 2026
…ifest (#182)

## Summary

Documentation companion to the 8 launcher-standard PRs filed today
(#170, #171, #172, #173, #175, #176, #177, #179). Two files following
the existing `docs/audits/` convention:

| File | Audience | Purpose |
|------|----------|---------|
| `launcher-standard-review-2026-05-26.adoc` | Humans | Prose narrative
— headline findings table (class × finding × addressed-in PR), full PR
map, what-this-campaign-produces summary, deferred follow-ups, method
notes |
| `launcher-standard-review-2026-05-26.a2ml` | Machines | Parseable
manifest — per-PR file lists, addressed-issues, new-files,
new-a2ml-keys, coordination notes (spec-version conflict resolution,
lock-step gate trigger map), deferred-followups with gating conditions |

Reviewers landing on any individual PR can find the full picture in
one place.

## Why this exists

After 8 PRs the campaign story is spread across 8 PR bodies and 8
commit messages. Without a single landing-page document:

- A reviewer landing on, say, PR #175 has no easy way to see that
  it's part of a larger coordinated change set, or that the
  `[spec].version` bump conflicts with PR #170's bump.
- Tooling (PR-batching bots, change-impact analyzers,
  launch-scaffolder regenerators) has nothing to introspect; each
  bot would have to re-parse 8 PR descriptions.
- Future audits need an entry point — `docs/audits/` already follows
  the dated-audit pattern (`dogfooding-matrix-2026-04-04.md`,
  `gap-matrix-2026-04-17.a2ml`); this matches.

## Pattern conformance

- Files in `docs/audits/` matches the existing convention.
- A2ML extension syntax (`@abstract:` block) matches
  `gap-matrix-2026-04-17.a2ml`. Pure `tomllib` does not parse A2ML;
  the repo's A2ML tooling does.
- SPDX headers on both files.

## Coordination

- Independent of the 8 review PRs — touches only `docs/audits/`,
  no overlap with `launcher/` or `docs/UX-standards/`.
- Lock-step gate (#172) does NOT fire on this PR (touches neither
  `launcher-standard.a2ml` nor `launcher-standard.adoc`).
- Final PR in the campaign. After this lands, the campaign is fully
  documented and merge-sequenceable purely from `main` artefacts.

## Test plan

- [x] adoc structure: 7 top-level sections (`==`) render under
      `asciidoctor` (visual)
- [x] a2ml structure: 8 `[[pr]]` array entries, `[campaign]`,
      `[coordination]`, `[deferred-followups]` with 2 `[[deferred]]`
      items, `[session-lessons-captured]`, `[provenance]` — all
      present and consistent
- [x] All 8 PR numbers in the manifest match the actually-filed PRs

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant