Skip to main content
EVOKORE// SKILLS / public-release-task-list
Sign in
Workspace
Brutal Honesty Kitmarkdownsha 67C2D1896DD9

public-release-task-list

documentation

Public Appearance and Documentation Task List

Source playbook: D:\GITHUB\OCR_LOCAL\docs\public-release-playbook.md

Repo audited: mattmre/Brutal-Honesty-Kit

Audit date: 2026-05-21

Initial Audit Snapshot

This snapshot records the state found before the public-polish implementation work in this branch. Items that were missing here may now be implemented below or completed as post-merge GitHub-side actions.

  • The repository is public.
  • README.md and VERSION now identify v3.7.1 as current.
  • The implementation path is still v3.5/, and that should remain true because scripts, tests, docs, templates, and schemas depend on literal v3.5/ paths.
  • GitHub metadata has a strong description, Issues enabled, Discussions enabled, Wiki enabled, and 20 topics already set.
  • GitHub Pages is not configured.
  • No GitHub Release is listed, and the only local tag found during audit was v3.7-final.
  • GitHub community profile health was 42% because only README.md and LICENSE were present from the standard community-file set.
  • .github/ is absent, so there are no committed issue templates, PR template, workflows, funding config, social preview image, or CODEOWNERS file.
  • No committed visual/presentation assets were found: no PNG/JPG/SVG/PDF/PPT/PPTX, no presentation/ site, no Pages entry point, and no wiki seed files.

Implementation Status In This Branch

  • Add root README banner using .github/social-preview.png.
  • Add root governance files: CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, SUPPORT.md, CITATION.cff, CODEOWNERS, and INSTALL.md.
  • Add .github/ collaboration surface: issue templates, PR template, funding metadata, Dependabot, and CI workflow.
  • Add public release docs: root CHANGELOG.md, release-notes-v3.7.1.md, v3.7.1/CHANGELOG.md, and concise v3.7.1/INSTALL.md.
  • Add docs index and wiki seed under docs/.
  • Add static GitHub Pages source: index.html, .nojekyll, and the presentation/ HTML suite.
  • Post-merge: enable GitHub Pages and set the repo homepage.
  • Post-merge: create/push the v3.7.1 tag and GitHub Release.
  • Post-merge: publish docs/wiki-seed/ into the GitHub Wiki repository.
  • Manual: upload .github/social-preview.png at GitHub Settings -> Social preview. GitHub has no public API for this.

Guiding Decisions

  • Treat this as an update/refinement of the existing public repo, not a clean first public mirror.
  • Preserve MIT unless the owner explicitly decides to relicense.
  • Preserve the v3.7.1/ release-index plus v3.5/ implementation-path compatibility model.
  • Do not copy OCR-specific Docker, ML, PaddleOCR, ediscovery, worker-image, or model-preload tasks from the source playbook unless this repo later adds those product surfaces.
  • Treat Claude/Codex adoption docs as product surface here. The OCR playbook's instruction to strip CLAUDE.md references does not directly apply.
  • Do not add badges for checks that do not exist or are not green.
  • Do not enable or advertise Pages until a site exists. This branch adds the site source; Pages still needs post-merge configuration.
  • Do not claim the GitHub social share card has changed until the image is manually uploaded in GitHub settings.

Phase 0 - Public Sanitization and Scope Review

  • Decide whether this repository will remain a full provenance repo or become a curated public release surface.
  • Review tracked operational/provenance surfaces:
    • docs/next-session.md
    • out/lane-history.txt
    • out/operator-asks.md
    • v3.5/plans/
    • v3.5/research/issues-raw/
    • v3.5/tier-b-bhs/
  • For each provenance area, choose one action:
    • keep and index as public provenance,
    • move under a clearer public docs area such as docs/provenance/,
    • remove from the public-facing branch,
    • or leave tracked but exclude from landing-page navigation.
  • Run a public-residue grep and classify every hit as governance, fixture, example, historical provenance, or blocker:
    • personal handle: mattmre
    • internal terms: internal, Slack, Jira, AEP-, MP-, customer/project names
    • AI co-author trailers: Co-Authored-By: Claude, Co-Authored-By: Codex, Co-Authored-By: Gemini
    • unfinished markers: TODO, FIXME, XXX, stub, placeholder
  • Decide how to handle existing AI co-author trailers in public git history. Options:
    • accept current history and ban new AI co-author trailers,
    • rewrite history only in a new public-clean mirror,
    • or document that the repository intentionally preserves historical provenance.
  • Add .claude/ to .gitignore unless Claude-local state is intentionally part of the public repo.
  • Confirm fake secret fixtures are safe for public hosting and covered by .gitguardian.yml.
  • Link the fake-secret fixture policy from SECURITY.md.

Phase 1 - Release and Version Confidence

  • Add a concise root CHANGELOG.md for public readers.
    • Put v3.7.1 first.
    • Keep it short: highlights, compatibility note, install link, validation summary.
    • Link deep forensic history to v3.5/CHANGELOG.md or a future docs/release-internals.md.
  • Add release-notes-v3.7.1.md.
    • Include highlights.
    • Include the v3.7.1/ index and v3.5/ implementation-path explanation.
    • Include what is not included: no package distribution yet, no Pages/presentation yet unless completed first, no Docker images.
    • Include validation commands and results.
  • Create and push an annotated v3.7.1 tag after release notes exist.
  • Create a GitHub Release for v3.7.1 and mark it latest.
  • Add docs/version-map.md or VERSIONING.md.
    • Explain historical folders: v3.2/, v3.3/.
    • Explain current implementation folder: v3.5/.
    • Explain current release index: v3.7.1/.
    • State explicitly that v3.5/ must not be renamed casually.
  • Add a public "why implementation still lives under v3.5" section/page and link it from:
    • README.md
    • v3.7.1/README.md
    • v3.7.1/INSTALL.md
    • root INSTALL.md when added.
  • Decide whether ADOPT-PROMPT.md, v3.7.1/ADOPT-PROMPT.md, and v3.5/ADOPT-PROMPT.md should be byte-identical or intentionally variant.
  • Add a small check that detects unintended drift between canonical adoption prompts.

Phase 2 - Root Governance and Community Files

  • Add CONTRIBUTING.md.
    • Explain issue triage, PR expectations, local validation, BHS PR-body expectations, and no new AI co-author trailers if that policy is adopted.
  • Add link-only CODE_OF_CONDUCT.md.
    • Link to Contributor Covenant 2.1 rather than copying full text.
  • Add SECURITY.md.
    • Include supported versions.
    • Point vulnerability reporting to GitHub Security Advisories.
    • Mention fake-secret fixtures and link to the fixture policy.
    • Reference the prior GitHub Actions label-injection fix at a high level without overloading the public landing docs.
  • Add SUPPORT.md.
    • Separate bugs, usage questions, security reports, and contribution discussions.
  • Add CITATION.cff.
    • This enables GitHub's "Cite this repository" button.
  • Add CODEOWNERS or .github/CODEOWNERS.
    • Prefer path-scoped ownership for high-risk surfaces such as .github/, release docs, validators, and security policy.
  • Add root INSTALL.md.
    • Keep it short and public-friendly.
    • Link the full implementation manual in v3.5/INSTALL.md.
  • Add DEVELOPMENT.md.
    • Include local environment setup, key test commands, validation commands, and release checklist.
  • Add root ARCHITECTURE.md.
    • Summarize the rulebook, validators, PR template, smoke gates, hooks, and command surfaces.
    • Include at least one Mermaid diagram.
  • Add a Makefile or documented equivalent command file.
    • Suggested targets: test, test-v371, validate-drift, lint-links, release-check.

Phase 3 - .github/ Collaboration Surface

  • Create .github/.
  • Add .github/PULL_REQUEST_TEMPLATE.md.
    • Include BHS-required fields or link to the canonical template.
    • Include a line banning new AI/LLM co-author trailers if that policy is adopted.
    • Include release-docs and version-map checkboxes.
  • Add .github/ISSUE_TEMPLATE/bug_report.yml.
  • Add .github/ISSUE_TEMPLATE/feature_request.yml.
  • Add .github/ISSUE_TEMPLATE/question.yml.
    • Route support questions to Discussions if Discussions remain enabled.
  • Add .github/ISSUE_TEMPLATE/config.yml.
    • Disable blank issues or clearly explain when blank issues are allowed.
  • Add .github/FUNDING.yml if sponsorship is desired.
  • Add .github/dependabot.yml.
    • Scope updates to Python/GitHub Actions surfaces that actually exist.
  • Add .github/workflows/ci.yml.
    • Start with commands already known to pass in this repo:
      • python -m pytest tests/test_validator_banner_version_stamp.py -v
      • R76-R80/hook focused tests
      • python -m pytest tests/test_pr_template_merge_snippet.py -v
      • explicit-path schema drift validator from repo root.
    • Set minimal permissions:.
    • Add concurrency:.
    • Pin action versions.
  • Add .github/workflows/release.yml if release automation is desired.
    • Trigger on v* tags.
    • Use checked-in release notes.
  • Add a secret-scan workflow only if it can pass reliably with the intentional fake-secret fixtures.
    • Keep GitGuardian/GitHub secret scanning configuration aligned with .gitguardian.yml.
  • Do not add Docker, GHCR, PyPI, npm, Helm, or Playwright workflows unless those surfaces are actually introduced.

Phase 4 - README and Public Landing Polish

  • Rework README.md into a public landing page while preserving current technical accuracy.
  • Add the generated PNG near the top after it exists.
    • Preferred path from the playbook: .github/social-preview.png.
    • Minimum size: 1280x640 PNG.
    • If the PNG is more of an explanatory diagram than a banner, also place or derive docs/assets/brutal-honesty-kit-overview.png.
  • Add a badge row only after the relevant surfaces exist and pass.
    • License: MIT.
    • Current version: v3.7.1.
    • CI: only after .github/workflows/ci.yml is green.
    • Discussions: only if keeping Discussions enabled.
    • Latest release: only after the GitHub Release exists.
  • Add a "30-second quickstart" that works from a fresh clone.
    • Show how to inspect the release index.
    • Show the minimal adoption route.
    • Show one verification command.
  • Add a "Repository Map" section.
    • Root public docs.
    • v3.7.1/ current release index.
    • v3.5/ implementation.
    • docs/ public documentation.
    • presentation/ site when added.
  • Add a "What adoption changes in your repo" example.
    • Copied paths.
    • CLAUDE.md merge behavior.
    • PR-body fields.
    • Verification commands.
  • Add a compact Mermaid system overview or link to root ARCHITECTURE.md.
  • Add links to:
    • install guide,
    • development guide,
    • security policy,
    • contributing guide,
    • docs index,
    • presentation site,
    • GitHub Discussions.
  • Add contributors and star-history widgets only if the maintainer wants those public widgets.
  • Ensure README does not make claims about Pages, Releases, CI, or social preview until each surface exists.

Phase 5 - Documentation Tree and Wiki Seed

  • Add docs/README.md as the public documentation index.
  • Add or link these docs:
    • docs/version-map.md
    • docs/adoption-quickstart.md
    • docs/validator-reference.md
    • docs/pr-template-reference.md
    • docs/hooks-and-commands.md
    • docs/release-process.md
    • docs/security-and-fixtures.md
    • docs/provenance/README.md if keeping internal history/provenance artifacts.
  • Move or clearly label docs/next-session.md.
    • It currently reads like live operator state, not a public docs landing page.
  • Create wiki-ready seed files under a tracked staging directory such as docs/wiki-seed/.
    • Home.md
    • _Sidebar.md
    • Quickstart.md
    • Versioning.md
    • Architecture.md
    • Validator-Reference.md
    • Hooks-and-Commands.md
    • Release-v3.7.1.md
    • FAQ.md
  • Decide whether GitHub Wiki should remain enabled.
    • If yes, publish the seed files to the GitHub wiki repo.
    • If no, disable Wiki and point all docs traffic to docs/ and Pages.
  • Keep wiki pages thin and canonical-link back to repo docs to avoid drift.

Phase 6 - Presentation and GitHub Pages

  • Decide presentation scope:
    • minimum: one public Pages landing page plus docs links,
    • full: playbook-style presentation/ HTML suite.
  • If full presentation is chosen, add:
    • presentation/index.html
    • presentation/executive-summary.html
    • presentation/technical-brief.html
    • presentation/use-cases.html
    • presentation/architecture.html
    • presentation/white-paper.html
    • presentation/slides.html
    • presentation/assets/
  • Include a consistent navigation bar across presentation pages.
  • Use the generated PNG in the presentation landing page and og:image metadata.
  • Add a root index.html, docs/index.md, or other explicit Pages entry point before enabling Pages.
  • Add .nojekyll if serving static HTML directly from the repository root.
  • Enable GitHub Pages only after the site exists.
  • Set the repo homepage only after the Pages URL resolves.
  • Verify Pages at https://mattmre.github.io/Brutal-Honesty-Kit/.
  • Add presentation links to README only after Pages works.

Phase 7 - Social Preview PNG Integration

  • Wait for the user-generated PNG.
  • Commit the primary social image at .github/social-preview.png.
  • If useful, commit an explanatory docs image at docs/assets/brutal-honesty-kit-overview.png.
  • Reference the image from README.md.
  • Reference the image from v3.7.1/README.md.
  • Reference the image from presentation pages if Pages is implemented.
  • Verify the raw image URL returns HTTP 200.
  • Manually upload .github/social-preview.png at GitHub Settings -> Social preview.
  • Verify share cards in Slack, LinkedIn Post Inspector, and X/Twitter preview tools.

Phase 8 - GitHub Settings and Community Configuration

  • Keep or refine the existing repo description.
  • Set homepage only after Pages is live.
  • Review the existing 20 topics.
    • Current topics are strong for AI coding and quality.
    • Consider adding/removing only if a more discoverable topic is clearly better.
  • Keep Discussions enabled if the repo will accept usage questions and contributor onboarding.
  • Post an inaugural Discussion in Announcements.
    • Explain what the kit is.
    • Explain how to adopt it.
    • Explain what help is wanted.
    • Link v3.7.1 release notes.
  • Decide Wiki setting after Phase 5.
    • If wiki is used, publish seed pages.
    • If docs/Pages is canonical, disable Wiki.
  • Verify the About sidebar shows:
    • description,
    • homepage,
    • topics,
    • latest release,
    • license,
    • sponsor button if funding file exists,
    • citation button if CITATION.cff exists.

Phase 9 - Validation and Announcement Gate

  • Fresh clone validation:
    • clone repo into a clean directory,
    • run quickstart exactly as written,
    • run advertised verification commands.
  • Local test validation:
    • banner/version tests pass,
    • R76-R80/hook tests pass,
    • template tests pass,
    • explicit-path schema drift validator passes.
  • Link validation:
    • root README links resolve,
    • v3.7.1/ links resolve,
    • docs index links resolve,
    • presentation links resolve if Pages is enabled.
  • GitHub UI validation:
    • issue templates render,
    • PR template renders,
    • latest Release is visible,
    • Discussions tab works,
    • Wiki or docs decision is reflected in navigation,
    • Pages works if advertised.
  • Security validation:
    • GitHub/GitGuardian checks pass,
    • fake-secret fixtures are acknowledged and allowlisted,
    • SECURITY.md points to the right reporting channel.
  • Public appearance validation:
    • PNG renders in README,
    • social preview upload is verified manually,
    • badge row is green or absent,
    • no public landing page points to missing Pages, releases, packages, or images.
  • Announcement is blocked until all advertised surfaces exist and pass.

Suggested Implementation Order

  1. Sanitize and classify provenance/history surfaces.
  2. Add root governance files and .github collaboration templates.
  3. Add root public changelog, release notes, and version-map docs.
  4. Add repo CI that runs only proven validation commands.
  5. Create the v3.7.1 tag and GitHub Release.
  6. Add docs index and wiki seed.
  7. Add PNG and wire it into README/release README.
  8. Build presentation/Pages surface.
  9. Configure GitHub homepage, social preview, Discussions announcement, and Wiki/Pages settings.
  10. Run final announcement gate.

Immediate Next PR Candidates

  • PR 1: Governance baseline
    • CONTRIBUTING.md
    • CODE_OF_CONDUCT.md
    • SECURITY.md
    • SUPPORT.md
    • CITATION.cff
    • CODEOWNERS
    • .github/ISSUE_TEMPLATE/*
    • .github/PULL_REQUEST_TEMPLATE.md
  • PR 2: Version/release confidence
    • root CHANGELOG.md
    • release-notes-v3.7.1.md
    • docs/version-map.md
    • short root INSTALL.md
    • concise v3.7.1 happy-path install guide
  • PR 3: Public docs and wiki seed
    • docs/README.md
    • public guide pages
    • docs/wiki-seed/*
    • provenance index or relocation plan
  • PR 4: CI and validation
    • .github/workflows/ci.yml
    • .github/dependabot.yml
    • optional release workflow
    • README badges after green runs
  • PR 5: Visual and presentation polish
    • .github/social-preview.png after the user provides it
    • README hero integration
    • presentation/ or docs Pages site
    • GitHub Pages configuration

Notes From Source Playbook Adaptation

  • The source playbook's full-polish path is appropriate if this repo is meant to be a flagship public example.
  • The minimum-viable path is governance files, issue/PR templates, green CI, clear release notes, current tag/release, and a better README.
  • The playbook's Docker/GHCR and package-publish tasks are not current blockers because this repo is a copy-in convention kit with v3.5/requirements.txt, not a packaged Python project.
  • If packaging is desired later, add pyproject.toml and console-script entry points as a separate product decision.