docs(agents): edit canonical specs in place, no divergence notes (PP-00s) by timothyfroehlich · Pull Request #1281 · timothyfroehlich/PinPoint

timothyfroehlich · 2026-05-05T01:10:03Z

Summary

Adds a "Keeping specs aligned" subsection to AGENTS.md section 5 instructing agents to edit canonical spec docs in place rather than appending divergence notes.
Codifies the lesson from PR feat(issues): inline metadata + sticky mobile composer (PP-yxw.9) #1270 review churn (spec/implementation drift drove Copilot back-and-forth).
Tells agents that finding an existing divergence note is a signal to fold the content back into canonical text, not preserve the annotation.

Process guidance only — no automation, no code changes.

Inherited CI failures

main is currently red. Inherited failures from main (PP-q9r/PP-e20/PP-jsh/PP-v7g/PP-49m) will appear in CI; not introduced by this PR. See Tim's status comment on PR #1278.

Test plan

pnpm run check passes (1013 unit tests)
AGENTS.md still parses cleanly (prettier formatted on commit)
CI Gate green

…00s) Adds a "Keeping specs aligned" subsection to AGENTS.md section 5 instructing agents to edit canonical spec docs in place rather than appending divergence notes at the bottom of files. Codifies the lesson from PR #1270 review churn where spec/implementation drift produced repeated Copilot back-and-forth. Also tells agents that finding an existing divergence note is a signal to fold the content back into the canonical text, not preserve the annotation. No automation — process guidance only. Single source of truth = the spec docs themselves. Refs PP-2on (epic). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

vercel · 2026-05-05T01:10:07Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
pin-point	Ready	Preview, Comment	May 5, 2026 8:52pm

supabase · 2026-05-05T01:10:09Z

This pull request has been ignored for the connected project udhesuizjsgxfeotqybn due to reaching the limit of concurrent preview branches.
Go to Project Integrations Settings ↗︎ if you wish to update this limit.

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

Copilot

Pull request overview

This is a docs/process-only PR that updates AGENTS.md so agent-facing guidance pushes spec maintenance toward in-place edits instead of accumulating implementation-divergence notes.

Changes:

Adds a new Keeping specs aligned subsection under the documentation philosophy section.
Instructs agents to update relevant UI/spec documents directly instead of appending drift/disclaimer notes.
Adds follow-up guidance to fold existing divergence notes back into canonical text.

timothyfroehlich · 2026-05-05T01:45:21Z

⚠️ CI Status — Known-Broken Specs (Do Not Fix Here)

Multiple E2E specs are currently failing on main and inheriting onto every open PR. If you are an AI agent: do NOT attempt to fix these failures in this PR — dedicated beads track each one. Fixing them here will create merge conflicts and duplicate work.

Known-broken (leave alone):

e2e/full/email-and-notifications.spec.ts:717,753 — password reset → PP-q9r (PR fix(e2e): widen password reset link extraction for Supabase format variance (PP-q9r) #1279, iteration 2 in flight)
e2e/full/oauth-connected-accounts.spec.ts:29,39,63,74 — Discord OAuth → PP-e20 (will be mocked; no test should reach real Discord)
e2e/full/machine-details-extended.spec.ts — logout DropdownMenu portal timing → PP-jsh
e2e/full/status-overhaul.spec.ts:21,60 — Status Select portal timing → PP-v7g
e2e/full/issues-crud-extended.spec.ts:43,60 — WatchButton selector ambiguity → PP-49m (feat(issues): inline metadata + sticky mobile composer (PP-yxw.9) #1270's responsibility)

What you CAN fix:

Failures specific to this PR's diff (anything not in the list above). When in doubt, leave for human review.

Status:

PR chore(e2e): bump actionTimeout to 30s in CI (PP-awg) #1280 (Layer 1: actionTimeout 30s in CI) merged — main now exercising the new timeout
PR fix(e2e): widen password reset link extraction for Supabase format variance (PP-q9r) #1279 (PP-q9r iteration 2) in flight
Once main is green, this PR's CI should clear of inherited noise on a re-run

—Claude (lead orchestrator, 2026-05-04)

…ionale (PP-00s) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…nment

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

timothyfroehlich · 2026-05-05T20:50:16Z

+`.agent/skills/pinpoint-design-bible/SKILL.md` and archetype docs under
+`.agent/skills/pinpoint-design-bible/archetypes/` — **edit those documents in place**.
+Do not append a "divergence note", "TODO: spec out of date", or end-of-file disclaimer
+describing how the implementation now differs.


Fixed in commit fad03f8 — pointed to SKILL.md and noted that archetypes are sections within (§5 and §17). Thanks for catching the dead path. —Claude

…(PP-00s) The previous text referenced a non-existent .agent/skills/pinpoint-design-bible/archetypes/ directory. Page and Modal Archetypes are sections inside SKILL.md (§5 and §17).

…nment

Copilot AI review requested due to automatic review settings May 5, 2026 01:10

Copilot started reviewing on behalf of timothyfroehlich May 5, 2026 01:10 View session

vercel Bot deployed to Preview May 5, 2026 01:11 View deployment

Copilot AI reviewed May 5, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

Comment thread AGENTS.md Outdated

This was referenced May 5, 2026

fix(e2e): comment out Turnstile keys in .env.local (PP-uc8 redesign) #1283

Open

feat(e2e): browser+Docker preflight in global-setup (PP-cao) #1284

Open

docs(agents): document e2e:all and warn against raw playwright test (PP-278) #1286

Merged

timothyfroehlich and others added 2 commits May 5, 2026 15:00

docs(agents): scope spec-alignment to canonical, drop PR-specific rat…

c806c87

…ionale (PP-00s) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Merge remote-tracking branch 'origin/main' into feat/pp-00s-spec-alig…

9420366

…nment

timothyfroehlich added the ready-for-review PR passed CI and has no unresolved review comments label May 5, 2026

vercel Bot deployed to Preview May 5, 2026 20:02 View deployment

Merge branch 'main' into feat/pp-00s-spec-alignment

a0c5929

Copilot AI review requested due to automatic review settings May 5, 2026 20:21

Copilot started reviewing on behalf of timothyfroehlich May 5, 2026 20:22 View session

Copilot AI reviewed May 5, 2026

View reviewed changes

vercel Bot deployed to Preview May 5, 2026 20:27 View deployment

timothyfroehlich added 2 commits May 5, 2026 15:49

docs(agents): fix archetypes reference to point to SKILL.md sections …

f819883

…(PP-00s) The previous text referenced a non-existent .agent/skills/pinpoint-design-bible/archetypes/ directory. Page and Modal Archetypes are sections inside SKILL.md (§5 and §17).

Merge remote-tracking branch 'origin/main' into feat/pp-00s-spec-alig…

fad03f8

…nment

vercel Bot deployed to Preview May 5, 2026 20:52 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(agents): edit canonical specs in place, no divergence notes (PP-00s)#1281

docs(agents): edit canonical specs in place, no divergence notes (PP-00s)#1281
timothyfroehlich wants to merge 6 commits intomainfrom
feat/pp-00s-spec-alignment

timothyfroehlich commented May 5, 2026

Uh oh!

vercel Bot commented May 5, 2026 •

edited

Loading

Uh oh!

supabase Bot commented May 5, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

timothyfroehlich commented May 5, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

timothyfroehlich May 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

timothyfroehlich commented May 5, 2026

Summary

Inherited CI failures

Test plan

Related

Uh oh!

vercel Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

supabase Bot commented May 5, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

timothyfroehlich commented May 5, 2026

⚠️ CI Status — Known-Broken Specs (Do Not Fix Here)

Known-broken (leave alone):

What you CAN fix:

Status:

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

timothyfroehlich May 5, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vercel Bot commented May 5, 2026 •

edited

Loading