Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

chore(ci): require agent PR readiness evidence

Abdurrahman Fakhrul7c1182c183d8
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 00000000..3d92097a
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,21 @@
+## Summary
+- Change:
+- Risk/rollback:
+
+## Agent validation evidence (required)
+- Exact branch / HEAD SHA:
+- Targeted regression tests:
+- `bun run pr:local`: PASS / FAIL / BLOCKED (evidence):
+- `bun run pr:security`: PASS / FAIL / BLOCKED (evidence):
+- Missing tooling or environment constraints:
+
+## Remote readiness checklist
+- [ ] All required GitHub CI and security jobs pass on the **latest HEAD**.
+- [ ] No new unresolved CodeQL/code-scanning security alerts.
+- [ ] All review threads resolved after actual fixes.
+- [ ] Test, build, security evidence matches the reviewed commit.
+- [ ] Deployment not claimed until changes reach `origin/main` and runtime verified.
+
+**Policy:** If any preflight check is incomplete, open or leave this PR as **Draft**.
+Never bypass required checks, hide parser failures, or dismiss security findings
+to manufacture a green status.
diff --git a/AGENTS.md b/AGENTS.md
index c85023a4..784386f8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -100,6 +100,36 @@ and official skill `mso-agent-bootstrap`, not by jumping to `exec_run`.
- System service actions require exact owner allowlisting and fixed argv. Do not add wildcard units,
raw `systemctl` arguments, or package-update/apply buttons to the Viewer/Operator surface.
+## Pull request readiness (mandatory for all coding agents)
+
+**A code change is not PR-ready because it compiles or has been committed.**
+After targeted tests and a local commit on an isolated worktree:
+
+1. Run `bun run pr:local` and capture the exact HEAD SHA + first failure.
+ This reuses the full committed `scripts/gates.sh`: typecheck, lint, coverage,
+ architecture/docs/audit, isolated build, and mandatory browser journeys.
+2. Run `bun run pr:security` when Docker is available (pinned Semgrep + ShellCheck,
+ same arguments/images as CI). **No Docker, failed scan, or incomplete evidence is
+ BLOCKED, not PASSED.** Never interpret Semgrep's "0 findings" as success when
+ its process exits nonzero; `--strict` also checks parse warnings.
+3. If any check fails, fix it and rerun. If an environment prerequisite cannot
+ be satisfied, create/leave a **Draft PR**, record the missing evidence, and do
+ not assert "ready" or bypass checks. Never use `--no-verify`, `SKIP`, branch
+ protection bypass, scanner suppression, or `continue-on-error` to fake green.
+4. After opening the draft, verify the exact pushed SHA in GitHub Actions.
+ CodeQL/Code scanning, Dependency Review and other remote required checks must
+ complete successfully; resolve all actual review threads after fixing their
+ underlying issues, then mark the PR ready. CodeQL new alerts require real
+ remediation and retesting, not a blanket dismissal.
+5. Report a compact evidence table: SHA, local result, security result, remote
+ result, failing log URLs, unresolved threads, and merge-readiness. Never
+ merge/declare shipped while required checks are red or the PR is a draft.
+
+Run `bun run pr:preflight` to request both local and scanner parity in one
+command. The gate exits 2 when required local tools are missing. If security
+scanners cannot run locally, CI can provide the missing evidence *after* a
+Draft PR; a local-only pass never implies CodeQL approval.
+
## Shipping
Run validation with `umask 077`: security fixtures must create private files/directories, not inherit group-writable shell defaults. On a busy shared host, bound Vitest concurrency with `VITEST_MAX_WORKERS=2` before changing timeout or coverage limits.
diff --git a/CLAUDE.md b/CLAUDE.md
index ff954650..23ff6f40 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -218,6 +218,15 @@ to `resources/` (rr) and drive any project from one manifest:
- For browser verification, discover an available authenticated/local or mock-only endpoint from
the current installation; do not encode an operator hostname or home path into tests.
+## Pull request readiness
+
+Follow the cross-agent hard gate in [`AGENTS.md`](./AGENTS.md#pull-request-readiness-mandatory-for-all-coding-agents).
+Use `bun run pr:local` before pushing a committed task branch and
+`bun run pr:security` for pinned CI scanner parity where Docker is available.
+If either is missing/failed, keep the PR in **Draft** and explicitly record the
+blocker. CodeQL and review-thread clearance are GitHub-side gates after PR
+creation; a local green run cannot supersede them. Never bypass branch rules.
+
## Rules in force
- **One canonical checkout; parallel work only through isolated hidden worktrees.**
The canonical `main` checkout is a **release/integration surface, not an agent scratchpad**. Automated source-changing work must happen in a task-owned hidden worktree; if canonical is dirty with another session's work, stop and preserve it rather than stashing, resetting, committing, merging or overwriting on that session's behalf. Only a release/integration step may advance canonical after the candidate and concurrent work are independently preserved and verified.
@@ -237,8 +246,9 @@ to `resources/` (rr) and drive any project from one manifest:
not hex, mobile-first. Barrel-only cross-slice imports.
- `/api/v1` host ops go through `lib/host` (bounds + realpath checks) — never call
`fs`/`child_process` straight from a route.
-- Solo-dev: push direct to `main` once `bun run verify` is green (typecheck + lint +
- test + check + audit). Conventional commits + Claude co-author.
+- Autonomous coding agents must use isolated task branches and PR review, never push
+ directly to `main`. Human-owned release integration still uses the verified
+ `bun run ship` path after review. Conventional commits + Claude co-author.
- **The gates live in `scripts/gates.sh`, which IS committed.** `.git/hooks/pre-push`
is a one-line shim that execs it; reinstall with `bash scripts/gates.sh --install`.
They used to live in the untracked hook itself, which meant a fresh clone had NO
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
index e07ff546..36920532 100644
--- a/docs/PROGRESS.md
+++ b/docs/PROGRESS.md
@@ -123,6 +123,12 @@ verb, and `docs/CLI.md` was regenerated from the help text (the same change keep
gates passed (100% routing recall, 97.3% schema reduction, deterministic selection). Per the P7 #5 / P8 #6
closed-loop rule, a passing corpus is not evidence of a defect, so it reported the observed gate values instead
of inventing a speculative change.
+## 2026-10-17: Make PR readiness auditable across MSO coding agents (candidate)
+
+PR #123 showed four distinct blockers: two gateway tests failing during CI coverage, a ShellCheck SC2164 warning, strict Semgrep exiting 3 with zero findings, and two new CodeQL filesystem race alerts. Existing `AGENTS.md` and the pre-push `scripts/gates.sh` offered guidance but could not establish whether another AI surface had run it, and GitHub-only CodeQL cannot be proven before the PR exists.
+
+The candidate adds an explicit agent-facing `scripts/pr-preflight.sh` and Bun commands `pr:local`, `pr:security`, `pr:preflight`. Local mode reuses the checked-in gates and strict audit rather than defining a weaker test suite; security mode reproduces pinned Semgrep/ShellCheck CI checks and fails closed when Docker is missing. A PR template and both agent manuals require exact-commit evidence, Draft state for unavailable checks, required GitHub CodeQL/review-thread clearance before marking ready, and no bypass. Automated contracts pin scanner parity. This is a candidate branch, **not deployed or merged into main**; GitHub-required checks and review resolution remain separate.
+
## 2026-10-17: Handoff the managed-domain CLI candidate for a new session
The owner explicitly requested a committed, pushed draft PR checkpoint and progress record before continuing in a new session. Implementation is preserved on `agent/mso-103047d38625`; the code commit is `da3ce4f69dfcdcb44a26f4522ced653194ec6172`, based on `89d61bb0d73b47047c67e51df9a6ee30351c8c3a`. The task worktree is `~/.cache/mso-worktrees/mso-103047d38625`; canonical remains `~/mso`. Keep the draft separate from release integration until the remaining checks pass.
diff --git a/package.json b/package.json
index fcc6d3f5..76e5d9f3 100644
--- a/package.json
+++ b/package.json
@@ -17,6 +17,9 @@
"check": "node scripts/check-cycles.mjs && node scripts/check-architecture.mjs && node scripts/check-docs.mjs && node scripts/gen-comparison.mjs --check && node scripts/check-contrast.mjs && bun scripts/check-skill-flows.mjs && bun run check:instance-literals && bun run test:ci && bun run parity:nakama && bun run test:parity",
"audit": "node scripts/audit.mjs",
"verify": "bun run typecheck && bun run lint && bun run coverage && bun run check && bun run audit",
+ "pr:preflight": "bash scripts/pr-preflight.sh --full",
+ "pr:local": "bash scripts/pr-preflight.sh --local",
+ "pr:security": "bash scripts/pr-preflight.sh --security",
"security:ultimate": "bash scripts/security-ultimate.sh",
"e2e": "node scripts/e2e/shell.mjs",
"e2e:preview": "node scripts/e2e/preview.mjs",
diff --git a/scripts/pr-preflight.sh b/scripts/pr-preflight.sh
new file mode 100755
index 00000000..fa209716
--- /dev/null
+++ b/scripts/pr-preflight.sh
@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# Agent-facing pre-PR gate. Uses the same repository gates and scanner versions as CI.
+# Exit 0 = selected LOCAL checks passed; remote CodeQL/reviews are never implied.
+set -euo pipefail
+umask 077
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+usage() {
+ cat <<'HELP'
+Usage: bash scripts/pr-preflight.sh [--local|--security|--full]
+ --local Verify committed code, strict audit, out-of-tree build and E2E.
+ --security Reproduce CI Semgrep and ShellCheck scans using pinned Docker images.
+ --full Both local and security (default).
+Exit: 0 = selected local checks passed; 1 = check failed; 2 = cannot validate.
+Never mark a PR ready until its required GitHub checks, CodeQL alerts and review
+threads are also cleared. Open a Draft PR if a local check cannot run.
+HELP
+}
+case "${1:---full}" in
+ --local) mode=local ;;
+ --security) mode=security ;;
+ --full) mode=full ;;
+ --help|-h) usage; exit 0 ;;
+ *) usage >&2; exit 64 ;;
+esac
+if (($# > 1)); then usage >&2; exit 64; fi
+
+block() { printf 'BLOCKED: %s\n' "$*" >&2; exit 2; }
+fail() { printf 'FAILED: %s\n' "$*" >&2; exit 1; }
+command -v git >/dev/null 2>&1 || block 'git is required'
+command -v bash >/dev/null 2>&1 || block 'bash is required'
+
+branch="$(git symbolic-ref --short -q HEAD)" || block 'detached HEAD; use a task branch'
+[[ "$branch" != main && "$branch" != master ]] || block 'work on an isolated task branch, not main'
+[[ -z "$(git status --porcelain --untracked-files=normal)" ]] || block 'uncommitted/untracked changes; commit intended changes and re-run'
+git diff --check HEAD^ HEAD || fail 'commit contains whitespace errors'
+git rev-parse --verify HEAD >/dev/null || block 'no committed HEAD'
+printf 'MSO PR preflight | branch=%s | sha=%s | mode=%s\n' "$branch" "$(git rev-parse --short=12 HEAD)" "$mode"
+
+if [[ "$mode" == local || "$mode" == full ]]; then
+ command -v bun >/dev/null 2>&1 || block 'bun is required'
+ [[ -d node_modules ]] || block 'install dependencies using bun install --frozen-lockfile'
+ # This already includes typecheck, lint, coverage, policy checks, dependency
+ # audit, the isolated build, and mandatory browser journeys. Never replace it
+ # with a shortened "green" command.
+ echo '>> Repository-owned pre-push verification'
+ bash scripts/gates.sh || fail 'repository gates failed (see first error above)'
+ echo '>> Fail-closed CI dependency audit'
+ bun run audit:strict || fail 'strict dependency audit failed'
+fi
+
+if [[ "$mode" == security || "$mode" == full ]]; then
+ command -v docker >/dev/null 2>&1 || block 'Docker unavailable; cannot reproduce CI security scanners'
+ docker info >/dev/null 2>&1 || block 'Docker daemon unavailable'
+ semgrep_image='semgrep/semgrep@sha256:f1f7b71861c7b28b6e0f661225a2c4f58a484f5d0f182465c6d6b3b22f972ade'
+ shellcheck_image='koalaman/shellcheck-alpine@sha256:9955be09ea7f0dbf7ae942ac1f2094355bb30d96fffba0ec09f5432207544002'
+ echo '>> Strict Semgrep with pinned CI image'
+ docker run --rm -v "$ROOT:/src:ro" "$semgrep_image" \
+ semgrep scan --metrics=off --config=p/javascript --config=p/typescript \
+ --config=p/owasp-top-ten --strict --error /src \
+ || fail 'Semgrep failed, including parser warnings; zero findings is not sufficient'
+ echo '>> ShellCheck warning-level scan with pinned CI image'
+ # NUL delimiters preserve valid paths with spaces.
+ mapfile -d '' -t files < <(git grep -Ilz '^#!.*sh' -- '*.sh' 'bin/*' 'scripts/*' 'claude-skills/*' || true)
+ args=()
+ for file in "${files[@]}"; do args+=("/src/$file"); done
+ if (("${#args[@]}" > 0)); then
+ docker run --rm -v "$ROOT:/src:ro" "$shellcheck_image" \
+ shellcheck --severity=warning -e SC1090,SC2034 "${args[@]}" \
+ || fail 'ShellCheck warnings detected'
+ fi
+fi
+
+[[ -z "$(git status --porcelain --untracked-files=normal)" ]] || fail 'validation modified tracked/untracked sources; inspect and recommit'
+echo "PASS: selected local preflight completed for $(git rev-parse --short=12 HEAD)."
+echo 'REMOTE REQUIRED: open Draft PR, inspect all required GitHub checks, CodeQL alerts,'
+echo 'and unresolved review threads. Only mark ready once all are clear.'
diff --git a/scripts/pr-preflight.test.ts b/scripts/pr-preflight.test.ts
new file mode 100644
index 00000000..4e911822
--- /dev/null
+++ b/scripts/pr-preflight.test.ts
@@ -0,0 +1,38 @@
+import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { describe, expect, it } from "vitest";
+
+const preflight = readFileSync(new URL("./pr-preflight.sh", import.meta.url), "utf8");
+const securityCI = readFileSync(new URL("../.github/workflows/security-core.yml", import.meta.url), "utf8");
+const securityUltimate = readFileSync(new URL("./security-ultimate.sh", import.meta.url), "utf8");
+
+describe("agent PR preflight", () => {
+ it("exposes a documented, non-executing help route", () => {
+ const result = spawnSync("bash", ["scripts/pr-preflight.sh", "--help"], { encoding: "utf8" });
+ expect(result.status).toBe(0);
+ expect(result.stdout).toContain("CodeQL");
+ expect(result.stdout).toContain("Draft PR");
+ });
+ it("rejects unknown switches instead of quietly ignoring them", () => {
+ const result = spawnSync("bash", ["scripts/pr-preflight.sh", "--skip-security"], { encoding: "utf8" });
+ expect(result.status).toBe(64);
+ });
+ it("reuses the committed release gate and refuses incomplete evidence", () => {
+ expect(preflight).toContain("bash scripts/gates.sh");
+ expect(preflight).toContain("bun run audit:strict");
+ expect(preflight).toContain("git status --porcelain");
+ expect(preflight).toContain("BLOCKED:");
+ expect(preflight).toContain("CodeQL");
+ expect(preflight).not.toContain("continue-on-error");
+ });
+ it("keeps shell and SAST scanner digests pinned to the required CI checks", () => {
+ for (const name of ["semgrep/semgrep", "koalaman/shellcheck-alpine"]) {
+ const image = preflight.match(new RegExp(name.replace("/", "\\/") + "@sha256:[a-f0-9]{64}"))?.[0];
+ expect(image).toBeDefined();
+ expect(securityCI).toContain(image);
+ expect(securityUltimate).toContain(image);
+ }
+ expect(preflight).toContain("--strict --error /src");
+ expect(preflight).toContain("--severity=warning -e SC1090,SC2034");
+ });
+});