unic-spec-review S1: skeleton tracer bullet — classify one URL, fetch page, one Gaps agent, write report

[orioltf]

Parent

Epic: #200 — unic-spec-review plugin: adversarial review of web specifications.

What to build

The first end-to-end tracer bullet for /review-spec. Given a single Confluence page URL, the command classifies the link, fetches that one page over the Atlassian REST API, runs exactly one dimension agent (Gaps/Completeness), prints the resulting Findings conversationally, and writes a durable timestamped markdown report to .spec-review/ (gitignored). The run is strictly read-only.

This slice establishes the plugin's skeleton: argument parsing, link classification, Confluence page read, the report renderer, and vendored credentials — the rails every later slice builds on. It is deliberately one source, one page, one agent: no traversal, no comments, no Figma/live, no posting.

Because this is the first .mjs to land, this slice also restores the plugin's test harness: re-add the test and typecheck scripts and tsconfig.json to package.json, and create the scripts/ and tests/ directories (the scaffold is command-only until now).

Vendor (copy, do not cross-import) atlassian-fetch.mjs and credentials.mjs from unic-pr-review, per ADR-0001 self-containment. For this slice only the Confluence page-read path of atlassian-fetch is needed.

Acceptance criteria

• /review-spec <one Confluence page URL> fetches that page and runs the Gaps/Completeness dimension agent against its content.
• link-classifier routes a Confluence URL to the confluence kind and extracts the page id; non-Confluence/unknown URLs are handled gracefully.
• args parses /review-spec arguments (a pasted URL block today; --post is recognised but inert in this slice).
• Gaps Findings are printed conversationally and report-renderer writes a timestamped markdown report under .spec-review/.
• The run performs zero writes to any external service (read-only invariant holds with no --post handling yet).
• atlassian-fetch.mjs and credentials.mjs are vendored by copying from unic-pr-review; nothing is cross-imported from another plugin.
• package.json regains test and typecheck scripts and tsconfig.json; scripts/ and tests/ exist.
• node:test unit tests cover every pure module in this slice (link-classifier, args, report-renderer, vendored credentials, and the atlassian-fetch page-read path) using injected fetch/homedir/env; no live services touched. The Gaps agent prompt and the thin command orchestrator are not unit-tested.
• PR adds CHANGELOG.md bullets under [Unreleased] and bumps the patch version via pnpm --filter unic-spec-review bump patch; verify:changelog passes. No em dash in authored text (except the mandated CHANGELOG version header).

Blocked by

None - can start immediately.

[orioltf]

✅ Issue Resolution Report

PR: #210 (#210)
Status: COMPLETE
Workflow: 726ece72bff7a491669f686b44d41045

---

Summary

Implemented the S1 skeleton tracer bullet for unic-spec-review: URL classification → Confluence page fetch → Gaps dimension agent → durable timestamped report. Two vendor files were copied from unic-pr-review (ADR-0001 self-containment respected), four new pure-function modules were added, and the test harness was fully restored. After a 5-agent post-implementation review (18 findings), 15 were fixed in a follow-up commit; 3 were intentionally skipped (vendor carryover / dead code by design). The branch ships with 59 passing tests, clean typecheck, lint, and Prettier.

---

Changes Made

File	Change
scripts/atlassian-fetch.mjs	CREATE — vendor copy from unic-pr-review (1 string changed)
scripts/lib/credentials.mjs	CREATE — vendor copy (bit-for-bit identical)
scripts/lib/args.mjs	CREATE — parse /review-spec CLI arguments
scripts/lib/link-classifier.mjs	CREATE — classify Confluence / Figma / unsupported URLs
scripts/lib/report-renderer.mjs	CREATE — render gap findings to timestamped Markdown report
agents/gaps-agent.md	CREATE — Gaps/Completeness dimension agent prompt
tsconfig.json	CREATE — tsc --checkJs --noEmit config
tests/ (5 files)	CREATE — 59 tests across all new modules
package.json	UPDATE — test/typecheck scripts + devDeps
.claude-plugin/plugin.json	UPDATE — registered gaps-agent.md
commands/review-spec.md	UPDATE — S1 orchestration (classify → fetch → Gaps agent → render)
CHANGELOG.md	UPDATE — 0.1.1 entry
AGENTS.md, CONTEXT.md, README.md	UPDATE — status banners refreshed from "scaffolding only" to S1-live

---

Validation

✅ Type check | ✅ Lint (Biome CI) | ✅ Format (Prettier) | ✅ Tests (59 passed) | ✅ verify:changelog (0.1.1)

---

Review & Self-Fix

• 18 review findings (0 CRITICAL, 1 HIGH, 7 MEDIUM, 10 LOW)
• 15 fixed — including 5 new tests, docs refresh, FS error handling, shell-quoting fix, module docstring rewrite
• 3 skipped (all LOW, all intentional — see below)
• 0 blocked

---

Unaddressed Items

Finding	Severity	Reason
any type in vendored atlassian-fetch.mjs JSDoc	LOW	Vendor carryover from unic-pr-review — not authored code
Duplicate extractPageId logic across two files	LOW	Intentional per ADR-0001 self-containment
loadAzureCreds exported but untested	LOW	Dead code in this plugin — never called

---

Suggested Follow-up Issues

• "unic-spec-review: remove or suppress dead loadAzureCreds export" (P3) — minor cleanup candidate for a later S2 housekeeping pass; no functional impact now

---

Resolved by Archon workflow 726ece72bff7a491669f686b44d41045