feat(RAN-54): add CHANGELOG.md + docs/README.md to clear bestpractices.dev autofill audit

.bestpractices.json

@@ -34,7 +34,8 @@
   "license_location_url": "https://github.com/RandomCodeSpace/snipIT/blob/main/LICENSE",
 
   "documentation_basics_status": "Met",
-  "documentation_basics_justification": "README.md documents install (clone + run), usage, hotkeys (global + preview-window), output paths, system integration, and architecture. CLAUDE.md provides the agent/developer brief covering build/test/run, conventions, gotchas, and engineering standards.",
+  "documentation_basics_justification": "Documentation basics cover three surfaces: (1) README.md at repo root — install (clone + run), usage, hotkeys (global + preview-window), output paths, system integration, architecture overview. (2) docs/README.md — a docs/ index pointing to long-form material (current entry: docs/mockups/preview-redesign.html design mock; plus links back to README, CLAUDE, SECURITY, the engineering-standards runbook, CHANGELOG, and .bestpractices.json). (3) CLAUDE.md — agent/developer brief with build/test/run commands, conventions, gotchas, and the OpenSSF Scorecard baseline + target. Conventional discoverability path (root README → docs/ → docs/README.md) is satisfied.",
+  "documentation_basics_url": "https://github.com/RandomCodeSpace/snipIT/blob/main/docs/README.md",
 
   "documentation_interface_status": "Met",
   "documentation_interface_justification": "snipIT's interface is the global hotkeys, system-tray widget, and preview-window editor — all documented under README.md §Hotkeys (Global + Preview window) and §Usage. There is no programmatic API surface; the .ps1 is invoked directly.",
@@ -72,11 +73,12 @@
   "version_tags_status": "?",
   "version_tags_justification": "No version tags today — see version_semver_justification. The Scorecard `Packaging` check is documented as a known not-a-pass in CLAUDE.md §OpenSSF Scorecard until a tagged-release flow lands.",
 
-  "release_notes_status": "N/A",
-  "release_notes_justification": "snipIT is a single-script project distributed via `git clone` of the main branch (no tagged releases, no compiled binary, no package-manager artifact). Per-merge change history is the squash-merge commit log on main (https://github.com/RandomCodeSpace/snipIT/commits/main), which serves the role of release notes for a continuously-delivered tool. SECURITY.md §Changelog documents the disclosure-policy version history. When a tagged-release flow is added (tracked under Scorecard Packaging in CLAUDE.md), CHANGELOG.md will be added at repo root.",
+  "release_notes_status": "Met",
+  "release_notes_justification": "CHANGELOG.md at repo root, Keep-a-Changelog 1.1.0 format with `[Unreleased]` collecting pre-tag work and per-version sections opened on each tag. Captures Added / Changed / Fixed / Security entries for every merge to main. Until the first tag is cut (tracked under Scorecard `Packaging` in CLAUDE.md), the `[Unreleased]` section is the release-notes surface; on tag, the heading is replaced with the version + date and a fresh `[Unreleased]` opens. SECURITY.md §Changelog separately tracks disclosure-policy version history.",
+  "release_notes_url": "https://github.com/RandomCodeSpace/snipIT/blob/main/CHANGELOG.md",
 
-  "release_notes_vulns_status": "N/A",
-  "release_notes_vulns_justification": "No published security vulnerabilities to date and no tagged release artifact (see release_notes_justification). When a release with a fix for a publicly-known vulnerability ships, the GHSA advisory + commit log entry on main will reference the CVE per SECURITY.md §What you can expect (credit in GHSA advisory and release notes).",
+  "release_notes_vulns_status": "Met",
+  "release_notes_vulns_justification": "CHANGELOG.md reserves a dedicated `### Security` subsection inside every release entry (and the `[Unreleased]` working set) for non-trivial security fixes. The header text states explicitly: 'Each release MUST list any non-trivial security fixes under a dedicated Security subsection so downstream consumers can decide whether to upgrade.' Zero fixes to date — the current `[Unreleased]` Security subsection is honestly marked 'No security-relevant fixes shipped yet under this release line.' When a fix ships, the entry will reference the GHSA advisory + CVE per SECURITY.md §What you can expect.",
 
   "report_process_status": "Met",
   "report_process_justification": "Bug-reporting process documented in README.md and the GitHub Issues tracker (https://github.com/RandomCodeSpace/snipIT/issues). Vulnerability-reporting process documented in SECURITY.md §Reporting a vulnerability (private GHSA advisory + email).",

CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to **snipIT** are documented in this file.
+
+The format is based on [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
+
+snipIT ships as a single PowerShell script (`SnipIT.ps1`); there are no compiled binaries and no package-manager artifacts. Version numbers below correspond to git tags on `main`. Until the first tag lands, all merged work is collected under `[Unreleased]`. When a release is cut, the heading is replaced with the tag and date and a fresh `[Unreleased]` section opens at the top.
+
+Each release MUST list any non-trivial security fixes under a dedicated **Security** subsection so downstream consumers can decide whether to upgrade. The disclosure / triage policy lives in [`SECURITY.md`](SECURITY.md).
+
+---
+
+## [Unreleased]
+
+### Added
+- OpenSSF Best Practices `passing` baseline ([RAN-54](https://github.com/RandomCodeSpace/snipIT/pull/1)):
+  - `.github/workflows/scorecard.yml` — `ossf/scorecard-action` on push to `main` + Mondays 06:00 UTC, SARIF → Security tab.
+  - `.github/workflows/security.yml` — OSS-CLI security stack: Trivy filesystem scan, Semgrep (`p/security-audit` + `p/owasp-top-ten`), **PSScriptAnalyzer** (PowerShell language gate), Gitleaks full-history secret scan, jscpd duplication check, and SPDX + CycloneDX SBOM generation.
+  - `.github/dependabot.yml` — weekly grouped GitHub Actions updates.
+  - `SECURITY.md` — private vulnerability disclosure policy, supported versions, and scope.
+  - `.bestpractices.json` — OpenSSF Best Practices self-assessment (project [12647](https://www.bestpractices.dev/en/projects/12647)).
+  - `CLAUDE.md` — agent / contributor brief: build, test, run, conventions, OpenSSF Scorecard baseline + target.
+  - `shared/runbooks/engineering-standards.md` — PowerShell variant of the company canonical engineering-standards runbook.
+  - `scripts/setup-git-signed.sh` — one-shot signed-commit setup (SSH / OpenPGP / x509).
+  - Branch protection on `main` — required signed commits, linear history, force-push and deletion blocked, eight required CI status checks.
+  - Repo-level Dependabot security updates enabled.
+- Canonical-schema rewrite of `.bestpractices.json` so the bestpractices.dev autofill robot can pre-fill the criteria page on board flip ([RAN-59](https://github.com/RandomCodeSpace/snipIT/pull/3)).
+- `CHANGELOG.md` (this file) and `docs/README.md` index — addresses the `release_notes` and `documentation_basics` gaps surfaced by the bestpractices.dev autofill audit.
+
+### Changed
+- `.github/workflows/test.yml` — every action SHA-pinned (Scorecard `Pinned-Dependencies`); top-level `permissions: read-all`; PSScriptAnalyzer moved out into `security.yml` so the SAST/lint signals are co-located with the rest of the security stack.
+- `README.md` — OpenSSF Best Practices, OpenSSF Scorecard, and Security workflow badges added at the top of the badge row.
+
+### Fixed
+- Capture flow — exclude SnipIT's own widget / preview / tray windows from the capture target so they aren't baked into the frame ([RAN-15](https://github.com/RandomCodeSpace/snipIT/issues)).
+- Color-bar interaction — update the active swatch in-place instead of rebuilding the bar; close `$pickColor` over the swatch handler so the closure resolves correctly at click time.
+
+### Security
+- _No security-relevant fixes shipped yet under this release line._
+
+---
+
+[Unreleased]: https://github.com/RandomCodeSpace/snipIT/commits/main

docs/README.md

@@ -0,0 +1,30 @@
+# snipIT documentation
+
+This folder collects long-form documentation that doesn't fit in the top-level [`README.md`](../README.md), the agent / contributor brief in [`CLAUDE.md`](../CLAUDE.md), or the disclosure policy in [`SECURITY.md`](../SECURITY.md).
+
+snipIT is intentionally a **single-script** product (`SnipIT.ps1`); most of what you need to know lives in the regions inside that script. The files here capture material that is too large or too visual to live alongside the code.
+
+## Index
+
+| Path | What it is |
+|---|---|
+| [`mockups/preview-redesign.html`](mockups/preview-redesign.html) | Standalone HTML mock of the chromeless Fluent preview window — used as the design reference when iterating on the WPF preview chrome. Open it in any browser. |
+
+## Documentation in other places
+
+For convenience, here is where the rest of snipIT's docs live:
+
+| Topic | Where to read it |
+|---|---|
+| Install, hotkeys, usage, architecture overview | [`/README.md`](../README.md) |
+| Build, test, run; conventions; gotchas; OpenSSF Scorecard baseline | [`/CLAUDE.md`](../CLAUDE.md) |
+| Vulnerability disclosure, supported versions, scope | [`/SECURITY.md`](../SECURITY.md) |
+| Quality gates, security tooling, branch / commit / PR rules | [`/shared/runbooks/engineering-standards.md`](../shared/runbooks/engineering-standards.md) — the PowerShell variant of the company-canonical engineering-standards runbook |
+| Per-merge change history | [`/CHANGELOG.md`](../CHANGELOG.md) |
+| OpenSSF Best Practices self-assessment (machine-readable) | [`/.bestpractices.json`](../.bestpractices.json) — companion to project [12647](https://www.bestpractices.dev/en/projects/12647) |
+
+## Contributing documentation
+
+If you're adding a doc that explains design rationale, walks through a non-trivial subsystem, or captures a decision (ADR-style), add a sibling file under `docs/` and link it from the **Index** table above. Keep this README the single entry point so the table of contents stays discoverable.
+
+For docs that belong with the code itself (region-level comments inside `SnipIT.ps1`, function-level help blocks), prefer inline comments per the convention in [`shared/runbooks/engineering-standards.md`](../shared/runbooks/engineering-standards.md) §2.