my-pi/pi-permission-system/docs/retro/0022-relax-on-disk-identity-rule.md

issue, issue_title

issue	issue_title
22	Relax 'preserve upstream on-disk identity' rule in AGENTS.md and README (lands with #10)

Retro: #22 — Relax "preserve upstream on-disk identity" rule in AGENTS.md and README

Final Retrospective (2026-05-03T02:30:00Z)

Session summary

Narrowed the "preserve upstream on-disk identity" rule in AGENTS.md (3 locations) and README.md (1 location) so only the /permission-system slash command and event channel name are treated as stable. Also updated README.md badges to match the pi-autoformat style (live npm version, CI status, TypeScript, Pi Package). Released as v1.2.1.

Observations

What went well

• Implementation committed on first try. The 4 prose edits across 2 files passed markdownlint and pre-commit hooks immediately. All friction was confined to the plan file, not the implementation itself.
• Badge update was clean. User requested an unplanned badge refresh mid-session; the change was scoped, committed separately, and passed CI.

What caused friction (agent side)

• instruction-violation (self-identified) — Markdownlint MD060 table-column alignment failed the plan commit three times. The first two failures were caused by em-dash characters (—) inflating column widths beyond what markdownlint-cli2 expected. The fix was to simplify to minimal | --- | separators with shorter cell content. Impact: ~3 minutes of rework across 3 failed pre-commit attempts, all on the plan file. This is the third consecutive session with MD060 friction (also seen in #18 and #19 retros). The specific trap this time was multi-byte UTF-8 characters (—) causing markdownlint-cli2 to miscount column widths.

What caused friction (user side)

• The user noted the absence of a /build-plan command (analogous to /tdd-plan) for docs-only or non-TDD issues. This would have streamlined the plan-to-implementation handoff for this session. Follow-up: consider creating a /build-plan prompt template (file as a GitHub issue, not a retro-scoped change).

Changes made

1. Created docs/retro/0022-relax-on-disk-identity-rule.md (this file).