issue-217: Register the penpot tests in npm test, complete the extension README, and roll out #249

Merged

david merged 3 commits from feature/issue-217/register-the-penpot-tests-in-npm-test-complete-the into main

2026-09-15 08:11:15 +00:00

david commented

2026-09-15 08:11:14 +00:00

Owner

217: Register the penpot tests in npm test, complete the extension README, and roll out

Closes #217 — 217.

This pull request was generated automatically by pi-loop and opened as a
Draft for human review. Do not merge without reviewing the changes.

Generated in 14m 12s.

Review findings

All fixes applied and npm test is green (864 tests, 863 pass, 1 skipped, 0 fail). No build/lint gate exists in this repo.

# Review Findings — 217

## Summary

Remediated the documentation-accuracy findings in a single pass. Fixed: the root README **Extension notes** now lists `penpot`; the two broken relative cross-references in `extensions/penpot/README.md` now resolve from the extension directory (`../../docs/…`, `../../skills/…`); the **Write model** staging sentence now says no **write** request is sent while staging (the path only reads); the CHANGELOG issue-217 entry now frames the `npm test` registration as pre-existing verification (confirmed against `origin/main`, where the globs already exist) rather than a change made here, and is separated from the issue-215 entry by a blank line. Left unresolved: the `AGENTS.md:26` commit-message convention finding — amending the commit is forbidden by this stage's no-commit/no-stage rule and would not appear in the captured working-tree diff; it remains for the rollout stage's PR title/commit hygiene. Gate re-run: `npm test` → 864 tests, 863 pass, 1 skipped, 0 fail.

## Critical

## High

## Medium

- [x] README.md:127 — the root README's **Extension notes** list omits `penpot`, although every other extension registered in the `pi.extensions` manifest has a bullet there (rg, postgres, pr-comments, forgejo, grillme, victorialogs, mongodb). This issue is the rollout step that completes the package docs, and the penpot README is only reachable from the extensions table. Suggested fix: add a bullet, e.g. ``- **penpot** — Penpot design-creation tools (`penpot_whoami` … `penpot_commit`); needs `PENPOT_URL`/`PENPOT_TOKEN` and a token with edit rights for writes; vendored reference pinned in `skills/penpot/docs/VERSION` (2.17.2); see [`extensions/penpot/README.md`](extensions/penpot/README.md).``
- [x] extensions/penpot/README.md:83 — the cross-reference `` See `docs/PENPOT_SKILL_DESIGN.md` `` is written as a repo-root path, but this file lives in `extensions/penpot/`, so it resolves to the non-existent `extensions/penpot/docs/PENPOT_SKILL_DESIGN.md` (the real file is `<repo>/docs/PENPOT_SKILL_DESIGN.md`). The same section's `[findings.md](findings.md)` and the earlier `[skills/penpot/docs/](../../skills/penpot/docs/)` links are correct, so this is an inconsistency. Suggested fix: use `../../docs/PENPOT_SKILL_DESIGN.md` (ideally as a markdown link).
- [x] extensions/penpot/README.md:85 — same defect: `` `skills/penpot/SKILL.md` → "Lossy areas" `` resolves to `extensions/penpot/skills/penpot/SKILL.md`, which does not exist. Suggested fix: use `../../skills/penpot/SKILL.md` (the "Lossy areas" heading does exist at `skills/penpot/SKILL.md:465`).

## Low

- [x] extensions/penpot/README.md:48 — "**stages** an `add-*` change … held in memory; **no request is sent while staging**" is inaccurate: every staging call issues at least a `get-file` read to seed the base `revn` (`ensureChangesetFromFile` in `src/staging.ts`), and `penpot_create_typography` additionally reads `get-font-variants` while `penpot_add_svg`/`penpot_instance_component` read linked-library data. The per-tool descriptions in the same file correctly say "nothing is *written*". Suggested fix: reword to "no **write** request is sent while staging (the staging path only reads)".
- [x] CHANGELOG.md:51 — the entry states "the penpot unit tests are registered in the root `npm test` script (…) which runs green" in the issue-217 entry, but those globs were already present on `main` before this branch (`git log -- package.json`: `e0f3b13`, "214", added `skills/penpot/scripts/*.test.mjs`; the `extensions/penpot/src/**` globs predate it), so this change did not register them. Suggested fix: reword to make the verification, not the change, explicit — e.g. "the penpot unit tests are already registered in the root `npm test` script (…) and the suite was confirmed green here".
- [ ] AGENTS.md:26 — the branch commit is `217: Register the penpot tests in npm test, complete the extension README, and roll out`, but the standards require `issue-<N>: <summary>` (and `issue-<N>: <title>` for the PR at AGENTS.md:27); the branch name itself (`feature/issue-217/…`) follows the convention. Suggested fix: amend the commit message to `issue-217: register the penpot tests in npm test, complete the extension README, and roll out`, and use the `issue-217:` form for the PR title in the rollout stage.
- [x] CHANGELOG.md:52 — the new issue-217 entry is appended directly against the issue-215 entry with no blank line, while the rest of the `### Changed` section separates entries with a blank line (lines 54, 56, 58/59). Suggested fix: insert a blank line between the two entries for consistent rendering.

## Friction

- category: out-of-scope
  description: The AGENTS.md:26 finding asks to amend the branch commit message to the `issue-<N>:` form, but this stage is forbidden from committing/staging and the pipeline captures only the working-tree diff, so a history rewrite could not be represented anyway.
  impact: One review finding left unresolved and deferred to the rollout stage's PR title/commit hygiene.
  resolution: unresolved
  ref: AGENTS.md

Documentation

Updated files:

docs/PENPOT_SKILL_DESIGN.md

## 217: Register the penpot tests in npm test, complete the extension README, and roll out Closes #217 — [217](https://git.excelera.net/david/pi-extensions-and-skills/issues/217). > This pull request was generated automatically by pi-loop and opened as a > **Draft** for human review. Do not merge without reviewing the changes. Generated in 14m 12s. ## Review findings All fixes applied and `npm test` is green (864 tests, 863 pass, 1 skipped, 0 fail). No build/lint gate exists in this repo. ```markdown # Review Findings — 217 ## Summary Remediated the documentation-accuracy findings in a single pass. Fixed: the root README **Extension notes** now lists `penpot`; the two broken relative cross-references in `extensions/penpot/README.md` now resolve from the extension directory (`../../docs/…`, `../../skills/…`); the **Write model** staging sentence now says no **write** request is sent while staging (the path only reads); the CHANGELOG issue-217 entry now frames the `npm test` registration as pre-existing verification (confirmed against `origin/main`, where the globs already exist) rather than a change made here, and is separated from the issue-215 entry by a blank line. Left unresolved: the `AGENTS.md:26` commit-message convention finding — amending the commit is forbidden by this stage's no-commit/no-stage rule and would not appear in the captured working-tree diff; it remains for the rollout stage's PR title/commit hygiene. Gate re-run: `npm test` → 864 tests, 863 pass, 1 skipped, 0 fail. ## Critical ## High ## Medium - [x] README.md:127 — the root README's **Extension notes** list omits `penpot`, although every other extension registered in the `pi.extensions` manifest has a bullet there (rg, postgres, pr-comments, forgejo, grillme, victorialogs, mongodb). This issue is the rollout step that completes the package docs, and the penpot README is only reachable from the extensions table. Suggested fix: add a bullet, e.g. ``- **penpot** — Penpot design-creation tools (`penpot_whoami` … `penpot_commit`); needs `PENPOT_URL`/`PENPOT_TOKEN` and a token with edit rights for writes; vendored reference pinned in `skills/penpot/docs/VERSION` (2.17.2); see [`extensions/penpot/README.md`](extensions/penpot/README.md).`` - [x] extensions/penpot/README.md:83 — the cross-reference `` See `docs/PENPOT_SKILL_DESIGN.md` `` is written as a repo-root path, but this file lives in `extensions/penpot/`, so it resolves to the non-existent `extensions/penpot/docs/PENPOT_SKILL_DESIGN.md` (the real file is `<repo>/docs/PENPOT_SKILL_DESIGN.md`). The same section's `[findings.md](findings.md)` and the earlier `[skills/penpot/docs/](../../skills/penpot/docs/)` links are correct, so this is an inconsistency. Suggested fix: use `../../docs/PENPOT_SKILL_DESIGN.md` (ideally as a markdown link). - [x] extensions/penpot/README.md:85 — same defect: `` `skills/penpot/SKILL.md` → "Lossy areas" `` resolves to `extensions/penpot/skills/penpot/SKILL.md`, which does not exist. Suggested fix: use `../../skills/penpot/SKILL.md` (the "Lossy areas" heading does exist at `skills/penpot/SKILL.md:465`). ## Low - [x] extensions/penpot/README.md:48 — "**stages** an `add-*` change … held in memory; **no request is sent while staging**" is inaccurate: every staging call issues at least a `get-file` read to seed the base `revn` (`ensureChangesetFromFile` in `src/staging.ts`), and `penpot_create_typography` additionally reads `get-font-variants` while `penpot_add_svg`/`penpot_instance_component` read linked-library data. The per-tool descriptions in the same file correctly say "nothing is *written*". Suggested fix: reword to "no **write** request is sent while staging (the staging path only reads)". - [x] CHANGELOG.md:51 — the entry states "the penpot unit tests are registered in the root `npm test` script (…) which runs green" in the issue-217 entry, but those globs were already present on `main` before this branch (`git log -- package.json`: `e0f3b13`, "214", added `skills/penpot/scripts/*.test.mjs`; the `extensions/penpot/src/**` globs predate it), so this change did not register them. Suggested fix: reword to make the verification, not the change, explicit — e.g. "the penpot unit tests are already registered in the root `npm test` script (…) and the suite was confirmed green here". - [ ] AGENTS.md:26 — the branch commit is `217: Register the penpot tests in npm test, complete the extension README, and roll out`, but the standards require `issue-<N>: <summary>` (and `issue-<N>: <title>` for the PR at AGENTS.md:27); the branch name itself (`feature/issue-217/…`) follows the convention. Suggested fix: amend the commit message to `issue-217: register the penpot tests in npm test, complete the extension README, and roll out`, and use the `issue-217:` form for the PR title in the rollout stage. - [x] CHANGELOG.md:52 — the new issue-217 entry is appended directly against the issue-215 entry with no blank line, while the rest of the `### Changed` section separates entries with a blank line (lines 54, 56, 58/59). Suggested fix: insert a blank line between the two entries for consistent rendering. ## Friction - category: out-of-scope description: The AGENTS.md:26 finding asks to amend the branch commit message to the `issue-<N>:` form, but this stage is forbidden from committing/staging and the pipeline captures only the working-tree diff, so a history rewrite could not be represented anyway. impact: One review finding left unresolved and deferred to the rollout stage's PR title/commit hygiene. resolution: unresolved ref: AGENTS.md ``` ## Documentation Updated files: - docs/PENPOT_SKILL_DESIGN.md

david added 3 commits

2026-09-15 08:11:14 +00:00