Add audit-freeze CI gate and ENGAGEMENT.md template (#158)

[Jerryvic911]

Closes (partially) #158
Closes #158

Scope note

Per the maintainer's scoping comment on #158, this PR covers only the
contributor-facing subset of the issue:

• .github/workflows/audit-freeze.yml
• audit-prep/ENGAGEMENT.md as a template (placeholders, not a signed SOW)
• A demonstration that the gate fires (separate throwaway PR, link below)

audit-prep/README.md, audit-prep/AUDIT_FIRMS.md, and
stellar/MAINNET_READINESS.md are intentionally untouched — firm
selection, the signed SOW, and the real coordinator/technical-contact
names are the maintainer's to fill in, and no row in
MAINNET_READINESS.md should flip until a real engagement is signed.

Security design (maintainer asked to pick one approach and say which)

Two independent layers, not just one:

1. Primary: the workflow checks out the PR's base ref
   (github.event.pull_request.base.sha), not the default PR-merge ref —
   so the gate script itself (scripts/audit-freeze/*.ts) cannot be
   modified by the PR it's judging. check.ts separately fetches
   ENGAGEMENT.md's content from that same base SHA via the GitHub
   Contents API, so a PR's edits to that file are simply invisible to the
   check.
2. Secondary (defense in depth): ENGAGEMENT.md is always treated as
   a frozen path in its own right whenever a freeze is active, regardless
   of what freeze_paths lists — so even if (1) ever regressed, editing
   the file still requires the audit-approved label.

Full writeup in scripts/audit-freeze/README.md.

Testing

26 tests passing:

• Unit tests for the front-matter parser, glob matcher, and decision logic
  (parse.test.ts, glob.test.ts, decide.test.ts) — no network.
• A subprocess end-to-end suite (check.e2e.test.ts) that runs the real
  check.ts CLI against a local mock GitHub API server, covering: a
  blocked PR, the audit-approved label override, no active freeze, a
  missing ENGAGEMENT.md at the base ref, and the self-protection case.

cd scripts/audit-freeze
npm install
npm test

Demonstration that the gate fires

---

Update: fixes found via live demonstration

While putting together the required demonstration that the gate fires
(see below), two real bugs surfaced that only a live PR run — not local
mock tests — could catch:

1. sparse-checkout in non-cone mode silently dropped
   scripts/audit-freeze/, causing ERR_MODULE_NOT_FOUND at runtime.
   Fixed by dropping sparse-checkout entirely in favor of a plain full
   checkout at the base ref (sparse-checkout was only ever a minor
   optimization, not load-bearing).
2. The gate crashed instead of passing cleanly on the very first PR
   that introduces the audit-freeze system itself — since the base-ref
   checkout (by design) finds nothing at scripts/audit-freeze/check.ts
   on develop, because it doesn't exist there yet. Fixed by having the
   workflow check whether check.ts exists on the checked-out base ref
   first, and pass with an explanatory message if not. This isn't a
   security gap: if the system doesn't exist on base, there's nothing to
   enforce or bypass.

Both fixes are now included in this PR and verified against a real PR
run (see the demonstration below).

Demonstration that the gate fires

Jerryvic911#1

That PR (base: this branch, issue-158-audit-freeze) temporarily
activated the freeze and touched stellar/stealth-announcer/README.md
(an in-scope frozen path):

• Without the audit-approved label: Audit Freeze Gate failed, as
  expected.
• After adding the audit-approved label: the same check passed,
  confirming the override path works.

The freeze activation was reverted afterward (see the revert: commit)
— audit-prep/ENGAGEMENT.md is back to the inactive "TBD" placeholder
on this branch.

[drips-wave]

@Jerryvic911 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[truthixify]

Merged @Jerryvic911, and you closed the hole I flagged rather than just noting it. Reading ENGAGEMENT.md from the base ref and treating it as an always-frozen path is belt and braces, which is right for a control whose whole job is to be un-bypassable. You also left MAINNET_READINESS.md alone as asked and kept the coordinator fields as placeholders for me. Exactly the split I described.