docs(v06): close out stages 8-10 — test, review, release prep for v0.8.1

CHANGELOG.md

@@ -8,6 +8,40 @@ All notable changes to Specorator are documented here. Format follows [Keep a Ch
 
 ---
 
+## [v0.8.1] — 2026-05-14
+
+### Added
+
+- **Specorator product steering split** (`docs/specorator-product/`) — Specorator's own product steering is now in a dedicated folder, separated from blank downstream starter templates in `docs/steering/`. `AGENTS.md` and `CLAUDE.md` route template-improvement agents to the new folder. T-V06-001/002, PR #175.
+- **Golden-path demo contract and evidence** (`docs/golden-path-contract.md`, `examples/glossary-term/EVIDENCE.md`) — the first-feature tutorial is backed by a maintainer-run evidence note. A deterministic check in `scripts/lib/spec-state.ts` validates EVIDENCE.md presence in every example directory. T-V06-003/004, PR #176.
+- **Cross-tool adapter inventory** (`docs/adapters.md`) with thin pointer files for GitHub Copilot (`.github/copilot-instructions.md`), Cursor/editor-agents (`.cursor/rules/agents.mdc`), and Codex (`.codex/instructions.md`) — each references `AGENTS.md` as source of truth. T-V06-005/006/007, PR #177.
+- **Opt-in advisory hook packs** (`.claude/hooks/`) — five scripts covering worktree guard, branch guard, Markdown guard, secrets guard, and handoff-context. Advisory by default (exit 0); activate via `settings.example.json`. `docs/hooks.md` documents disable paths and the ADR-gated promotion path to blocking behavior. T-V06-008/009, PR #178.
+- **Agentic security review path** (`docs/agentic-security-review.md`, skill, and findings template) — OWASP-aligned internal risk-reduction guidance covering seven risk categories. No certification or completeness claims. T-V06-010, PR #179.
+- **Adoption profiles** (`docs/adoption-profiles/`) — five persona-keyed starting paths: solo builder, product team, agency delivery, enterprise governance, and brownfield migration. T-V06-011, PR #180.
+- **ISO 9001:2026 watch item** — FDIS timeline reference added to `docs/quality-assurance-track.md`; named follow-up tracked in issue #91. T-V06-013, PR #181.
+- **Tiered verify gate** — `git hooks` path and `verify:ci` split for CI use without a local git-hooks setup. PR #494.
+- **`docs/backlog/` as canonical issue + PR mirror** — feature tracker page defaults to `docs/backlog/`. PR #476.
+- **CI pass-through for backlog-only PRs** — dedicated workflow passes CI on mirror-only `docs/backlog/` updates. PR #498.
+
+### Fixed
+
+- Site feature tracker defaults to `docs/backlog/` source. PR #504.
+- `specorator init` edge cases in target-path resolution. PR #499.
+
+### Internal
+
+- `@octokit/rest` bumped from 21.1.1 to 22.0.1 (#490).
+- `yaml` dev dependency bumped (#489).
+- GitHub Actions toolchain maintenance bumps.
+
+### Notes
+
+- REQ-V06-010 (evidence-first public positioning of README and product page) is deferred to PR-H branch. Owner: release-manager. Expected: v0.8.1 or v0.8.2.
+- REQ-V06-011 (named "Watch items" section in `docs/quality-assurance-track.md`) is a v0.7 follow-up tracked in issue #91. Owner: qa.
+- Hook-pack positioning in the root README and product page is intentionally withheld until v0.7.
+
+---
+
 ## [v0.8.0-rc.1] — 2026-05-10
 
 Release candidate for the v0.8.0 cycle. Smoke-tests npmjs.com Trusted Publishing on the `specorator` package after [ADR-0044](docs/adr/0044-restore-npmjs-trusted-publishing.md) restored the OIDC + `--provenance` path (supersedes ADR-0041). The first successful RC dispatch confirms `release.yml` mints an OIDC token, `npmjs.com` accepts the publish, and the package page surfaces a sigstore provenance attestation. Surface content is identical to the v0.8.0 final entry below.

specs/version-0-6-plan/implementation-log.md

@@ -129,13 +129,24 @@ A running record of what was implemented, why a deviation was taken, and what wa
 - **Deviation from spec:** none
 - **Notes:** Five persona profiles (solo builder, product team, agency delivery, enterprise governance, brownfield migration). Each links to existing tracks without duplicating method content. Folder README carries `entry_point: true` frontmatter. Root README and `docs/specorator-product/product.md` cross-link the index. Codex P2 finding (plan file referenced `sites/index.html` instead of `sites/src/pages/index.astro`) resolved in the same commit.
 
+### 2026-05-14 - T-V06-013 - Add ISO 9001:2026 follow-up
+
+- **Files changed:** `specs/version-0-6-plan/pr-plan-g-iso-9001-watch.md` (new); `docs/quality-assurance-track.md` (FDIS reference in line 11, added as part of agentic-security PR)
+- **Commit:** dbf41c2 (PR #181 — merged to develop)
+- **Spec reference:** SPEC-V06-008 (REQ-V06-011)
+- **Owner:** qa
+- **Outcome:** partial — plan file and FDIS prose reference landed; dedicated Watch-items section with named review trigger not yet added to `docs/quality-assurance-track.md`
+- **Deviation from spec:** PR #181 delivered the PR plan file and verified the ISO/FDIS reference exists in `docs/quality-assurance-track.md` line 11. A dedicated "Watch items" section with an explicit review trigger was not added. REQ-V06-011 acceptance criterion is partially met. FINDING-V06-001 in the test report captures this gap for dev resolution.
+- **Notes:** The ISO/FDIS 9001 publication timeline reference is present in `docs/quality-assurance-track.md`. The named follow-up record and review trigger are absent. Dev should add a "Watch items" subsection before the review stage closes or the reviewer should accept this as a v0.7 follow-up.
+
 ## Deviations summary
 
 | Date | Task | Deviation | Reason | ADR |
 |---|---|---|---|---|
 | 2026-05-02 | T-V06-001 | None | Existing template ownership preserved. | - |
 | 2026-05-02 | T-V06-002 | None | Implementation follows SPEC-V06-001. | - |
 | 2026-05-02 | T-V06-008/T-V06-009 | Slipped to v0.7 | Optional hook automation expands pre-v1.0 surface area and is not required for v1.0 readiness. | - |
+| 2026-05-14 | T-V06-013 | Watch-item section not added to quality-assurance-track.md | Plan file and FDIS reference landed; dedicated Watch-items section with review trigger deferred. FINDING-V06-001 in test-report.md. | - |
 
 ## Quality gate
 

specs/version-0-6-plan/release-notes.md

@@ -0,0 +1,143 @@
+---
+id: RELEASE-V06-001
+title: Specorator v0.8.1 — Release notes
+stage: release
+feature: version-0-6-plan
+version: v0.8.1
+status: draft
+owner: release-manager
+inputs:
+  - REVIEW-V06-001
+created: 2026-05-14
+updated: 2026-05-14
+---
+
+# Release notes — Specorator v0.8.1
+
+## Summary
+
+v0.8.1 is a consolidation patch that closes out the v0.6 productization work. It packages changes shipped incrementally after v0.8.0: a Specorator product steering split, a verified golden-path demo, cross-tool adapter surfaces for Copilot, Cursor, and Codex, five opt-in advisory hook packs, an OWASP-aligned agentic security review path, persona-keyed adoption profiles, an ISO 9001:2026 watch item, plus CI, site, dependency, and template init fixes accumulated since the v0.8.0 tag.
+
+All new surfaces are opt-in and additive. No schema migration is required. Users who rely only on the core 11-stage workflow and `npm run verify` see no breaking changes.
+
+## Changes
+
+### New
+
+- **Specorator product steering** (`docs/specorator-product/`) — Specorator's own product steering is now in a dedicated folder, separated from the blank downstream steering templates in `docs/steering/`. `AGENTS.md` and `CLAUDE.md` route template-improvement agents to the new folder. T-V06-001/002, PR #175.
+
+- **Golden-path demo contract and evidence** (`docs/golden-path-contract.md`, `examples/glossary-term/EVIDENCE.md`) — the first-feature tutorial is backed by a maintainer-run evidence note (date, commit, commands, caveats). A new deterministic check in `scripts/lib/spec-state.ts` validates EVIDENCE.md presence in every example directory. T-V06-003/004, PR #176.
+
+- **Cross-tool adapter inventory** (`docs/adapters.md`, `.github/copilot-instructions.md`, `.cursor/rules/agents.mdc`, `.codex/instructions.md`) — thin pointer files for GitHub Copilot, Cursor/editor agents, and Codex each reference `AGENTS.md` as the source of truth. `docs/adapters.md` is the canonical adapter inventory. T-V06-005/006/007, PR #177.
+
+- **Opt-in advisory hook packs** (`.claude/hooks/`) — five hook scripts covering worktree guard, branch guard, Markdown guard, secrets guard, and handoff-context. All scripts are advisory (exit 0 by default). Enable paths are documented in `docs/hooks.md`; the ADR-gated promotion path to blocking behavior is documented. Hook packs are not wired into `.claude/settings.json` by default — activation is always a deliberate opt-in step. T-V06-008/009, PR #178.
+
+- **Agentic security review path** (`docs/agentic-security-review.md`, `.claude/skills/agentic-security-review/`, `templates/agentic-security-findings.md`) — OWASP-aligned internal risk-reduction guidance covering seven risk categories: goal/instruction hijacking, tool misuse, excessive agency, memory/context poisoning, secrets exposure, inter-agent handoff failures, and observability. The doc explicitly states no certification or completeness claims. T-V06-010, PR #179.
+
+- **Adoption profiles** (`docs/adoption-profiles/`) — five persona-keyed starting paths: solo builder, product team, agency delivery, enterprise governance, and brownfield migration. Each profile routes to the minimal relevant surfaces without duplicating method content. T-V06-011, PR #180.
+
+- **ISO 9001:2026 watch item** (`specs/version-0-6-plan/pr-plan-g-iso-9001-watch.md`) — the expected ISO/FDIS 9001 timeline is noted in `docs/quality-assurance-track.md`. A formal "Watch items" section in the QA track doc is tracked as a v0.7 follow-up in issue #91. T-V06-013, PR #181.
+
+- **Tiered verify gate** — `git hooks` path and `verify:ci` split so CI can run the full gate without needing a local git-hooks setup. PR #494.
+
+- **`docs/backlog/` as canonical issue + PR mirror** — the feature tracker page now sources from `docs/backlog/` by default. PR #476.
+
+- **CI pass-through for backlog-only PRs** — a dedicated workflow passes CI on PRs that touch only `docs/backlog/` files, avoiding spurious failures on mirror-only updates. PR #498.
+
+### Fixed
+
+- Site fixes: feature tracker defaults to `docs/backlog/` as its source. PR #504.
+- Template init: resolved edge cases in `specorator init` that caused failures on paths with certain layouts. PR #499.
+
+### Dependencies
+
+- `@octokit/rest` bumped from 21.1.1 to 22.0.1 (#490).
+- `yaml` dev dependency bumped (#489).
+- GitHub Actions toolchain bumps (#484, #485 and related maintenance PRs).
+
+### Deprecated
+
+- Hook-pack positioning in the root `README.md` and public product page is intentionally withheld until v0.7. The packs are delivered and documented in `docs/hooks.md`; the public README and product page do not yet reference them.
+
+## User-visible impact
+
+- **Adopters using `AGENTS.md` and `docs/` as the method source:** no action required. All changes are additive. The steering split, adapter files, hook packs, security path, and adoption profiles land alongside existing surfaces without modifying them.
+
+- **Tool-specific adapter users (Copilot, Cursor, Codex):** new pointer files are in place. If you were relying on `AGENTS.md` directly, the pointer files simply add a thin overlay — no reconfiguration needed.
+
+- **Hook pack opt-in:** to enable any hook pack, follow the instructions in `docs/hooks.md` and copy the relevant snippet from `settings.example.json` into your `.claude/settings.json`. This is a deliberate manual step and will not happen automatically.
+
+- **Breaking changes:** none. `npm run verify` still exits 0 with no new mandatory gates. `sites/index.html` was replaced in v0.6.0 and remains replaced — if you depend on the static HTML file rather than the Astro build output, see the v0.6.0 entry in `CHANGELOG.md`.
+
+## Readiness summary
+
+- Release readiness guide: not used. This is an additive documentation release with a single stakeholder (human maintainer). Conditions from the review are documented directly below.
+- Go/no-go verdict: go with conditions — all three review conditions are satisfiable in this stage and are addressed here.
+- Required conditions from review (REVIEW-V06-001):
+
+  1. **Issue #91 remains open as ISO watch-item tracker.** Confirmed open on `develop` as of 2026-05-14. Named owner: qa. Expected resolution: v0.7 or v1.0 readiness, whichever is first. Release proceeds with this gap disclosed; the partial evidence (FDIS timeline prose in `docs/quality-assurance-track.md` line 11) is present. A formal "Watch items" section with explicit review trigger is the v0.7 follow-up.
+
+  2. **REQ-V06-010 deferral recorded with a named owner.** T-V06-012 (evidence-first public positioning of the README and product page) is deferred to the PR-H branch. Named owner: release-manager. Tracking: issue RISK-V06-007 from the review document; PR-H branch. Expected: v0.8.1 or v0.8.2. The current README and product page do not contain misleading claims about unshipped features — hook-pack positioning is withheld from public copy until the packs are explicitly highlighted in v0.7.
+
+  3. **PR-D scope-cut row corrected in workflow-state.md.** Corrected in this stage: T-V06-008 and T-V06-009 are now recorded as delivered in v0.6 via PR #178, not slipped to v0.7. Condition met.
+
+## Known limitations
+
+- **REQ-V06-010 (evidence-first public positioning) is deferred.** The public README and product page do not yet reflect the new golden-path proof, cross-tool adapter support, or adoption profiles. This is a known managed scope-cut. The features are fully delivered and documented in `docs/`; only the public-facing positioning is deferred. Expected resolution: PR-H branch, v0.8.1 or v0.8.2. Owner: release-manager.
+
+- **REQ-V06-011 (ISO 9001:2026 watch-item section) is partially complete.** The ISO/FDIS 9001 timeline reference is present in `docs/quality-assurance-track.md`. The "Watch items" named section with an explicit review trigger and link to issue #91 is absent. This is a "should" priority requirement, accepted by the reviewer as a v0.7 follow-up. No premature compliance claim was made. Owner: qa. Tracker: issue #91.
+
+- **Hook-pack README and product page positioning is withheld.** The hook packs are available and documented in `docs/hooks.md`. They are not mentioned in the root `README.md` or the public product page. This is intentional per the scope-cut decision: positioning will land in v0.7 after false-positive behavior is understood in practice.
+
+- **Fully automated interactive golden-path CI demo is deferred.** The golden-path demo runs as a maintainer-run check backed by `EVIDENCE.md`. Fully automated CI execution of the interactive demo is deferred until the path is stable. Tracked as a known caveat in `examples/glossary-term/EVIDENCE.md`.
+
+- **Cross-tool adapter generation script is deferred.** Adapter files are hand-authored thin pointers. A generation script to automate drift detection between canonical sources and adapter files is deferred per ADR-0028. Manual sync triggers are documented in `docs/adapters.md`.
+
+## Verification steps
+
+1. Run `npm run verify` from the repository root. Expected: exit 0.
+2. Confirm `docs/specorator-product/` exists and contains the five steering files (product.md, ux.md, tech.md, quality.md, operations.md).
+3. Confirm `examples/glossary-term/EVIDENCE.md` is present and contains date, commit, commands, and caveats fields.
+4. Confirm `.github/copilot-instructions.md`, `.cursor/rules/agents.mdc`, and `.codex/instructions.md` each reference `AGENTS.md`.
+5. Confirm `.claude/hooks/` contains five hook scripts and `docs/hooks.md` documents their disable paths.
+6. Confirm `docs/agentic-security-review.md` frontmatter states "no certification or completeness claims."
+7. Confirm `docs/adoption-profiles/README.md` and all five persona files are present.
+8. Confirm issue #91 is open on `develop`.
+9. Confirm `specs/version-0-6-plan/workflow-state.md` PR-D row reads "Delivered in v0.6."
+
+## Rollback plan
+
+- **Trigger criteria:** `npm run verify` exits non-zero post-release; a new surface (hook pack, adapter file, security doc) causes demonstrable harm to existing adopter workflows; or the tiered verify gate breaks CI for a significant share of PRs.
+
+- **Mechanism:** All new surfaces in this release are opt-in and additive. For documentation-only regressions (incorrect guidance, broken links, bad hook behavior), roll forward through a corrective PR on a topic branch — follow the standard branch-per-concern flow in `docs/branching.md`. If the npm package or GitHub Release artifact must be remediated, follow the documented path in `docs/release-operator-guide.md` §7.1 (failed publish recovery); do not silently rewrite published history. Revert to the `v0.8.0` tag if the release artifact itself is the problem and no corrective-PR path is viable; the prior tag remains intact and is the stable rollback point.
+
+- **Data implications:** This release is documentation and configuration only. No database, user data, or persistent state is involved. There are no data migration concerns. Opt-in changes (hook packs wired in by the adopter) can be removed by reverting the relevant `.claude/settings.json` additions without affecting repository state.
+
+- **Communication:** For template-level regressions affecting downstream adopters: post a note in the GitHub Release on the `v0.8.1` tag explaining the issue, link the corrective PR or new patch tag, and update the release-notes.md to record the incident. No external broadcast is required unless the regression affects the public product page or the npm package in a way visible to first-time installers. Tone: factual, brief, and linked to the corrective action.
+
+## Observability
+
+- **CI logs** are the primary operational signal. `npm run verify` runs on every PR and must exit 0. No new metrics, dashboards, or alert rules are required for this documentation-only release.
+- **Quality metrics:** run `npm run quality:metrics -- --feature version-0-6-plan` for a feature-scoped KPI snapshot. Current state (2026-05-14): 92.0% overall score, Level 3 maturity, 0 blockers, 0 clarifications. No saved trend baseline exists for this feature — the 92.0% result is the first snapshot and there is no prior baseline to compare against.
+- **Issue #91** is the live tracker for the ISO watch-item follow-up. Monitor open/closed state before the v0.7 or v1.0 readiness gate.
+- No new application-level metrics, dashboards, or paging rules are required.
+
+## Communication
+
+- **Internal announcement:** notify the human maintainer that the Stage 10 prepare phase is complete and all three review conditions are resolved or recorded with owners. Await explicit authorisation before tagging or publishing.
+- **External announcement:** no external announcement is planned for v0.8.1. The public product page (REQ-V06-010, PR-H) is deferred; no public positioning update accompanies this patch tag.
+- **Support / docs updates:** `docs/hooks.md`, `docs/adapters.md`, `docs/agentic-security-review.md`, `docs/adoption-profiles/`, and `docs/golden-path-contract.md` are the canonical references for the new surfaces. These are in the repository at the tagged commit and require no separate publishing step.
+
+---
+
+## Quality gate
+
+- [x] Summary written for the audience (users / stakeholders, not engineers).
+- [x] User-visible impact stated.
+- [x] Readiness conditions and approvals summarized, or guide marked not used. (Guide not used; conditions documented in Readiness summary section.)
+- [x] Known limitations disclosed.
+- [x] Verification steps documented.
+- [x] Rollback plan documented — trigger criteria, mechanism, data implications, and communication all present.
+- [x] Observability hooks in place — CI verify gate; no new metrics required for this documentation release.
+- [x] Communication plan ready.
+- [ ] Merged worktrees pruned (`git worktree prune`) and stale topic worktrees/branches cleaned up. (Post-authorisation cleanup step — not yet actioned.)