Protect README About copy with regression coverage

openspec/changes/agent-codex-readme-about-description-regression-test-2026-04-21-18-20/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-21

openspec/changes/agent-codex-readme-about-description-regression-test-2026-04-21-18-20/notes.md

@@ -0,0 +1,5 @@
+# T1 Notes
+
+- Handoff: own `test/metadata.test.js` and this change record.
+- Add focused regression coverage for the merged README/about-description contract.
+- Keep the change test-only: assert the problem visual, solution visual, README link to `about_description.txt`, and mirrored canonical copy.

openspec/changes/agent-codex-readme-about-description-regression-test-2026-04-21-18-20/proposal.md

@@ -0,0 +1,17 @@
+## Why
+
+- The merged README/about-description update is currently verified by manual inspection and OpenSpec, but not by a focused regression test.
+- A narrow metadata test is enough to catch accidental drift in the README section layout or canonical About copy reference.
+
+## What Changes
+
+- Add one metadata test that checks:
+  - the collision visual stays under `## The problem`
+  - the branch-start visual stays under `### Solution`
+  - the README links to `about_description.txt`
+  - the canonical About copy in the README matches `about_description.txt`
+
+## Impact
+
+- Affected surface: `test/metadata.test.js` and the matching OpenSpec change docs.
+- Risk is low and limited to test coverage.

openspec/changes/agent-codex-readme-about-description-regression-test-2026-04-21-18-20/specs/readme-about-description-regression/spec.md

@@ -0,0 +1,11 @@
+## ADDED Requirements
+
+### Requirement: metadata tests protect the canonical README About copy contract
+The repo SHALL keep focused regression coverage that verifies the README problem/solution visual placement and the canonical `about_description.txt` mirror.
+
+#### Scenario: metadata test locks the merged README structure
+- **WHEN** the metadata test suite runs
+- **THEN** it verifies the collision visual appears under `## The problem`
+- **AND** it verifies the branch-start visual appears under `### Solution`
+- **AND** it verifies the README links to `about_description.txt`
+- **AND** it verifies the README mirrors the same canonical About copy stored in `about_description.txt`.

openspec/changes/agent-codex-readme-about-description-regression-test-2026-04-21-18-20/tasks.md

@@ -0,0 +1,17 @@
+## 1. Specification
+
+- [x] 1.1 Capture the regression-test scope in proposal + spec artifacts.
+
+## 2. Implementation
+
+- [x] 2.1 Add focused metadata coverage for the README/about-description contract.
+
+## 3. Verification
+
+- [x] 3.1 Run `node --test test/metadata.test.js`.
+- [x] 3.2 Run `openspec validate agent-codex-readme-about-description-regression-test-2026-04-21-18-20 --type change --strict`.
+- [x] 3.3 Run `openspec validate --specs`.
+
+## 4. Cleanup
+
+- [ ] 4.1 Branch is ready for `agent-branch-finish --via-pr --wait-for-merge --cleanup` with PR URL + `MERGED` evidence recorded.

test/metadata.test.js

@@ -6,6 +6,7 @@ const path = require('node:path');
 const repoRoot = path.resolve(__dirname, '..');
 const packageJsonPath = path.join(repoRoot, 'package.json');
 const readmePath = path.join(repoRoot, 'README.md');
+const aboutDescriptionPath = path.join(repoRoot, 'about_description.txt');
 
 function escapeRegexLiteral(value) {
   return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -68,6 +69,22 @@ test('README documents gx release as README-driven GitHub release writer', () =>
   assert.match(readme, /finds the last published GitHub release, and writes one grouped GitHub release body/);
 });
 
+test('README keeps canonical About copy and problem-solution visuals aligned', () => {
+  const readme = fs.readFileSync(readmePath, 'utf8');
+  const aboutDescription = fs.readFileSync(aboutDescriptionPath, 'utf8').trim();
+
+  assert.match(
+    readme,
+    /## The problem\s+!\[Parallel agents colliding in the same files\]\(https:\/\/raw\.githubusercontent\.com\/recodeee\/gitguardex\/main\/docs\/images\/problem-agent-collision\.svg\)/s,
+  );
+  assert.match(
+    readme,
+    /### Solution\s+!\[Agent branch\/worktree start protocol\]\(https:\/\/raw\.githubusercontent\.com\/recodeee\/gitguardex\/main\/docs\/images\/workflow-branch-start\.svg\)/s,
+  );
+  assert.match(readme, /\[about_description\.txt\]\(\.\/about_description\.txt\)/);
+  assert.match(readme, new RegExp(escapeRegexLiteral(aboutDescription)));
+});
+
 test('security workflows are present and use pinned GitHub Actions SHAs', () => {
   const workflowDir = path.join(repoRoot, '.github', 'workflows');
   const expected = ['ci.yml', 'release.yml', 'scorecard.yml', 'codeql.yml', 'cr.yml'];