From 6477aebfaba4efa28d0b5e5750514bab6adeeff9 Mon Sep 17 00:00:00 2001 From: NagyVikt Date: Tue, 21 Apr 2026 18:21:43 +0200 Subject: [PATCH] Protect README About copy with regression coverage Add one metadata test that locks the merged README problem/solution visual placement and ensures the README mirrors the canonical about_description.txt copy. This keeps the docs contract from drifting without adding broader test churn. Constraint: Follow-up must stay test-only and scoped to the merged README/about-description contract Rejected: Re-run the entire install.test.js suite to prove this docs change | unrelated long-running suite still times out without incremental output Confidence: high Scope-risk: narrow Directive: If the README About copy changes again, update about_description.txt first and keep this metadata test aligned with the same source Tested: node --test test/metadata.test.js; openspec validate agent-codex-readme-about-description-regression-test-2026-04-21-18-20 --type change --strict; openspec validate --specs; git diff --check Not-tested: full npm test aggregate run still contains a long-running install.test.js file that timed out during ad hoc verification --- .../.openspec.yaml | 2 ++ .../notes.md | 5 +++++ .../proposal.md | 17 +++++++++++++++++ .../readme-about-description-regression/spec.md | 11 +++++++++++ .../tasks.md | 17 +++++++++++++++++ test/metadata.test.js | 17 +++++++++++++++++ 6 files changed, 69 insertions(+) create mode 100644 openspec/changes/agent-codex-readme-about-description-regression-test-2026-04-21-18-20/.openspec.yaml create mode 100644 openspec/changes/agent-codex-readme-about-description-regression-test-2026-04-21-18-20/notes.md create mode 100644 openspec/changes/agent-codex-readme-about-description-regression-test-2026-04-21-18-20/proposal.md create mode 100644 openspec/changes/agent-codex-readme-about-description-regression-test-2026-04-21-18-20/specs/readme-about-description-regression/spec.md create mode 100644 openspec/changes/agent-codex-readme-about-description-regression-test-2026-04-21-18-20/tasks.md diff --git a/openspec/changes/agent-codex-readme-about-description-regression-test-2026-04-21-18-20/.openspec.yaml b/openspec/changes/agent-codex-readme-about-description-regression-test-2026-04-21-18-20/.openspec.yaml new file mode 100644 index 0000000..4b8c565 --- /dev/null +++ b/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 diff --git a/openspec/changes/agent-codex-readme-about-description-regression-test-2026-04-21-18-20/notes.md b/openspec/changes/agent-codex-readme-about-description-regression-test-2026-04-21-18-20/notes.md new file mode 100644 index 0000000..98258bb --- /dev/null +++ b/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. diff --git a/openspec/changes/agent-codex-readme-about-description-regression-test-2026-04-21-18-20/proposal.md b/openspec/changes/agent-codex-readme-about-description-regression-test-2026-04-21-18-20/proposal.md new file mode 100644 index 0000000..8041955 --- /dev/null +++ b/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. diff --git a/openspec/changes/agent-codex-readme-about-description-regression-test-2026-04-21-18-20/specs/readme-about-description-regression/spec.md b/openspec/changes/agent-codex-readme-about-description-regression-test-2026-04-21-18-20/specs/readme-about-description-regression/spec.md new file mode 100644 index 0000000..a34e658 --- /dev/null +++ b/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`. diff --git a/openspec/changes/agent-codex-readme-about-description-regression-test-2026-04-21-18-20/tasks.md b/openspec/changes/agent-codex-readme-about-description-regression-test-2026-04-21-18-20/tasks.md new file mode 100644 index 0000000..2cccb11 --- /dev/null +++ b/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. diff --git a/test/metadata.test.js b/test/metadata.test.js index 4d63748..41ea192 100644 --- a/test/metadata.test.js +++ b/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'];