From 29b0e593abff452c5bc948f6219b6e60a2efd930 Mon Sep 17 00:00:00 2001 From: NagyVikt Date: Tue, 21 Apr 2026 18:56:31 +0200 Subject: [PATCH] Align package metadata with the canonical Guardian T-Rex pitch README and about_description.txt already carried the approved product copy, but package.json still advertised the older generic description. This change brings npm metadata onto the same canonical line, restores the README About and Solution blocks required by the current metadata regression, and records the alignment in a matching OpenSpec delta. Constraint: Package metadata, README About copy, and about_description.txt must stay aligned Rejected: Update package.json only | left README/spec regressions red in this branch Confidence: high Scope-risk: narrow Reversibility: clean Directive: Keep package.json description, README About copy, and about_description.txt in lockstep Tested: node --test test/metadata.test.js; npm test; git diff --check; openspec validate agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46 --type change --strict; openspec validate --specs Not-tested: npm registry rendering of the longer package description --- README.md | 10 ++++++++ .../.openspec.yaml | 2 ++ .../notes.md | 7 ++++++ .../proposal.md | 16 ++++++++++++ .../specs/readme-about-description/spec.md | 14 +++++++++++ .../tasks.md | 25 +++++++++++++++++++ package.json | 2 +- test/metadata.test.js | 2 ++ 8 files changed, 77 insertions(+), 1 deletion(-) create mode 100644 openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/.openspec.yaml create mode 100644 openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/notes.md create mode 100644 openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/proposal.md create mode 100644 openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/specs/readme-about-description/spec.md create mode 100644 openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/tasks.md diff --git a/README.md b/README.md index 4950aae..db33645 100644 --- a/README.md +++ b/README.md @@ -28,8 +28,18 @@ I was running ~30 Codex agents in parallel and hit a wall: they kept working on ### Solution +![Agent branch/worktree start protocol](https://raw.githubusercontent.com/recodeee/gitguardex/main/docs/images/workflow-branch-start.svg) + GitGuardex exists to stop that loop. Every agent gets its own worktree, claims the files it's touching, and can't clobber files another agent has claimed. Your local branch stays clean; agents stay in their lanes. +## GitHub About description + +The canonical GitHub About copy lives in [about_description.txt](./about_description.txt): + +```text +Guardian T-Rex for your multi-agent repo. Isolated worktrees, file locks, and PR-only merges stop parallel Codex & Claude agents from overwriting each other's work. Auto-wires Oh My Codex, Oh My Claude, OpenSpec, and Caveman. +``` +

Install GitGuardex diff --git a/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/.openspec.yaml b/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/.openspec.yaml new file mode 100644 index 0000000..4b8c565 --- /dev/null +++ b/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-04-21 diff --git a/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/notes.md b/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/notes.md new file mode 100644 index 0000000..19a31c8 --- /dev/null +++ b/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/notes.md @@ -0,0 +1,7 @@ +# T1 Notes + +- Handoff: change=`agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46`; scope=`package.json`; action=`align the npm package description with the existing Guardian T-Rex README/About copy`. +- Replace the generic package description with the approved Guardian T-Rex positioning so npm metadata matches README and `about_description.txt`. +- Restore the README GitHub About section so the canonical copy is linked and mirrored from the documented source. +- Restore the README solution image required by the existing metadata/spec regression so the copy-alignment suite stays green after the metadata update. +- Keep the change narrowly scoped to package metadata, one README parity fix, and the matching regression coverage; no version bump or runtime behavior change. diff --git a/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/proposal.md b/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/proposal.md new file mode 100644 index 0000000..950e935 --- /dev/null +++ b/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/proposal.md @@ -0,0 +1,16 @@ +## Why + +- `about_description.txt` and the README already use the approved Guardian T-Rex positioning, but `package.json` still exposes the older generic package description. +- That drift makes the npm package metadata tell a different story than the canonical About copy. + +## What Changes + +- Align `package.json` `description` with the canonical text in `about_description.txt`. +- Restore the README GitHub About section so the canonical copy is visible and linked from the documented source file. +- Restore the missing README solution visual required by the current `readme-about-description` regression. +- Add an OpenSpec delta that requires package metadata to stay aligned with the canonical About description source. + +## Impact + +- Affected surfaces: `package.json`, `README.md`, one metadata regression test, and the matching OpenSpec change record. +- Risk is low and limited to package metadata / product copy consistency. diff --git a/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/specs/readme-about-description/spec.md b/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/specs/readme-about-description/spec.md new file mode 100644 index 0000000..5fc2e52 --- /dev/null +++ b/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/specs/readme-about-description/spec.md @@ -0,0 +1,14 @@ +## MODIFIED Requirements + +### Requirement: README points to one canonical GitHub About description source +The repo SHALL keep one canonical GitHub About description in `about_description.txt`, and the README plus package metadata SHALL mirror that same copy instead of drifting across product surfaces. + +#### Scenario: package metadata matches the canonical About copy +- **WHEN** a maintainer inspects `package.json` and `about_description.txt` +- **THEN** `package.json` `description` matches the full canonical text in `about_description.txt` +- **AND** the README continues to reference that same canonical source. + +#### Scenario: solution visual remains under the solution heading +- **WHEN** a reader opens the top-level README +- **THEN** the `### Solution` heading is followed by the workflow image +- **AND** the Guardex solution copy appears below that image. diff --git a/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/tasks.md b/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/tasks.md new file mode 100644 index 0000000..8464451 --- /dev/null +++ b/openspec/changes/agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46/tasks.md @@ -0,0 +1,25 @@ +## 1. Metadata + +- [x] 1.1 Update `package.json` so the npm description matches the canonical Guardian T-Rex copy. +- [x] 1.2 Restore the README GitHub About section so it links to `about_description.txt` and mirrors the canonical copy. +- [x] 1.3 Restore the README solution visual expected by the existing metadata/about regression. + +## 2. OpenSpec + +- [x] 2.1 Record the scope and handoff in the change notes. +- [x] 2.2 Add a spec delta covering package metadata alignment with `about_description.txt`. + +## 3. Verification + +- [x] 3.1 Validate `package.json` parses as JSON. +- [x] 3.2 Run `git diff --check`. +- [x] 3.3 Update/add regression coverage for canonical About copy alignment. +- [x] 3.4 Run `npm test`. +- [x] 3.5 Run `openspec validate agent-codex-align-guardian-t-rex-package-description-2026-04-21-18-46 --type change --strict`. +- [x] 3.6 Run `openspec validate --specs`. + +## 4. Cleanup + +- [ ] 4.1 Run `bash scripts/agent-branch-finish.sh --branch "agent/codex/align-guardian-t-rex-package-description-2026-04-21-18-46" --base main --via-pr --wait-for-merge --cleanup`. +- [ ] 4.2 Record PR URL + final `MERGED` state in the completion handoff. +- [ ] 4.3 Confirm sandbox cleanup (`git worktree list`, `git branch -a`) or capture a `BLOCKED:` handoff if merge/cleanup is pending. diff --git a/package.json b/package.json index 7422cd6..561864e 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "@imdeadpool/guardex", "version": "7.0.16", - "description": "GitGuardex: hardened multi-agent git guardrails for parallel agent work.", + "description": "Guardian T-Rex for your multi-agent repo. Isolated worktrees, file locks, and PR-only merges stop parallel Codex & Claude agents from overwriting each other's work. Auto-wires Oh My Codex, Oh My Claude, OpenSpec, and Caveman.", "license": "MIT", "preferGlobal": true, "bin": { diff --git a/test/metadata.test.js b/test/metadata.test.js index 41ea192..85f9117 100644 --- a/test/metadata.test.js +++ b/test/metadata.test.js @@ -72,6 +72,7 @@ test('README documents gx release as README-driven GitHub release writer', () => test('README keeps canonical About copy and problem-solution visuals aligned', () => { const readme = fs.readFileSync(readmePath, 'utf8'); const aboutDescription = fs.readFileSync(aboutDescriptionPath, 'utf8').trim(); + const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8')); assert.match( readme, @@ -83,6 +84,7 @@ test('README keeps canonical About copy and problem-solution visuals aligned', ( ); assert.match(readme, /\[about_description\.txt\]\(\.\/about_description\.txt\)/); assert.match(readme, new RegExp(escapeRegexLiteral(aboutDescription))); + assert.equal(pkg.description, aboutDescription); }); test('security workflows are present and use pinned GitHub Actions SHAs', () => {