From 56152f9ecd492aec6dea075b22d02418bf14a060 Mon Sep 17 00:00:00 2001 From: Rook-CodeVolt <260194005+Rook-CodeVolt@users.noreply.github.com> Date: Mon, 31 Aug 2026 09:04:28 +0100 Subject: [PATCH] Strengthen public communication review --- .github/PULL_REQUEST_TEMPLATE.md | 8 ++++- CHANGELOG.md | 5 +++ PUBLICATION_POLICY.md | 20 ++++++++--- PUBLIC_COMMUNICATION_STANDARD.md | 54 ++++++++++++++++++++++++++++++ README.md | 1 + scripts/validate_public_content.py | 54 ++++++++++++++++++++++++++++-- templates/public-work-note.md | 33 ++++++++++++++++-- 7 files changed, 166 insertions(+), 9 deletions(-) create mode 100644 PUBLIC_COMMUNICATION_STANDARD.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 196eeba..c9881dc 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -4,14 +4,20 @@ What public reader outcome does this change support? ## Evidence and publication safety -- Evidence or source: +- Evidence or source opened and checked: - Why this is safe to publish: +- Factual corrections or claims removed: +- Human writing review: - Documentation impact: ## Verification - [ ] `python3 scripts/validate_public_content.py .` - [ ] Links and representative instructions checked +- [ ] Exact claims match opened public evidence and changeable facts were rechecked +- [ ] Commands, examples, versions, dates, counts and states were verified where used +- [ ] Public copy follows `PUBLIC_COMMUNICATION_STANDARD.md`, with em dashes and generated writing patterns removed +- [ ] Reviewer other than the author checked facts and natural language; name the reviewer. When the maintainer is the author, a different model family performs this review and the maintainer records self-approval - [ ] No customer, personal, credential, infrastructure, recovery or private repository information - [ ] `CHANGELOG.md` updated, or no user-visible change because: diff --git a/CHANGELOG.md b/CHANGELOG.md index 7660982..3a8f627 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,11 @@ Material public changes to this repository are recorded here. Date-only maintenance commits are not used to manufacture activity. +## 2026-08-31 + +- Added a public communication standard covering factual verification, natural language, independent review and corrections. +- Strengthened the public work note and pull request checks for evidence accuracy and generated writing patterns. + ## 2026-08-30 - Published the initial CodeVolt public field notes. diff --git a/PUBLICATION_POLICY.md b/PUBLICATION_POLICY.md index 01f13d3..50f652d 100644 --- a/PUBLICATION_POLICY.md +++ b/PUBLICATION_POLICY.md @@ -16,9 +16,19 @@ The maintainer must review architecture descriptions, screenshots, incident less ## Editorial quality -Public copy must read naturally and sound like the person or maintainer responsible for it. Remove chatbot carry-over, stock promotional language, inflated significance, formulaic contrasts, repetitive three-part lists, rhetorical questions that answer themselves, generic upbeat endings and unnecessary formatting. Avoid repeated em dashes, bold labels, emojis and headings that make short material look templated. +Every public draft must pass [`PUBLIC_COMMUNICATION_STANDARD.md`](PUBLIC_COMMUNICATION_STANDARD.md). The author uses specific facts, ordinary words and natural sentence rhythm. The reviewer removes chatbot carry-over, stock promotional language, inflated significance, formulaic contrasts, artificial three part lists, rhetorical questions that answer themselves, generic upbeat endings and unnecessary formatting. -Do not add fake typos, invented opinions or artificial quirks to imitate a person. Use specific facts, ordinary words and natural sentence rhythm. Read the final draft aloud. If it sounds generated or assembled, rewrite it before publication. +Public copy does not use em dashes or dash led fragments for artificial rhythm. It avoids repeated bold labels, emojis and headings that make short material look templated. Required hyphens in technical identifiers, commands and established terms remain unchanged. These rules apply to CodeVolt's own words. Quoted source text, command output, code and identifiers are reproduced exactly. Dash led fragments are caught by the human writing pass, not by the validator. + +Humanising must not introduce fake typos, invented opinions, personal history or artificial quirks. Read the final draft aloud. Rewrite anything that sounds generated, assembled or more confident than the evidence. + +## Correctness review + +The author and independent reviewer must open each cited source, verify that it supports the exact wording, and recheck facts that can change. Commands, examples and tests presented as working must have real execution evidence. Numbers, dates, versions, issue states and declared totals must be checked rather than inferred. + +Separate observed facts, CodeVolt's interpretation and future intent. Name limits and unresolved uncertainty. Remove any claim that cannot be proved from the public evidence. + +Consequential public claims require accountable human approval. A different model family must review factual support, omissions, tone and generated writing patterns before publication. If that review is unavailable, the material waits. ## Never publish here @@ -36,6 +46,8 @@ Do not add fake typos, invented opinions or artificial quirks to imitate a perso ## Evidence rule -Every public claim about completed work must link to evidence a reader can inspect or be limited to a clearly labelled generalized example. Ordinary fork synchronization is not a CodeVolt contribution. A contribution may be described only when its public issue, pull request, commit or release supports the description. +Every public claim about completed work must link to evidence a reader can inspect. The reviewer must open that evidence and confirm that it supports the exact wording. A link without that check does not satisfy this rule. A generalized example must be labelled as illustrative, must not describe or imply specific completed CodeVolt work, and never substitutes for the evidence link required above. + +Ordinary fork synchronization is not a CodeVolt contribution. A contribution may be described only when its public issue, pull request, commit or release supports the description. Recheck changeable facts immediately before publication. -When classification is uncertain, do not publish. Route the candidate to the maintainer for a decision. +When classification, accuracy or wording is uncertain, do not publish. Route the candidate to the maintainer for a decision. diff --git a/PUBLIC_COMMUNICATION_STANDARD.md b/PUBLIC_COMMUNICATION_STANDARD.md new file mode 100644 index 0000000..7f13033 --- /dev/null +++ b/PUBLIC_COMMUNICATION_STANDARD.md @@ -0,0 +1,54 @@ +# Public communication standard + +Public work carries CodeVolt's name. When accuracy and speed conflict, accuracy wins. + +## Check the facts + +Before publication, the author and reviewer must: + +1. Match every claim about completed work to an exact public issue, pull request, commit, release or file. +2. Open the source and confirm that it says what the draft claims. A link alone is not proof. +3. Recheck details that can change, including issue state, merge state, versions, dates, counts and maintainer decisions. +4. Run any command, test or example presented as working. Record the actual result. +5. Separate observed facts from CodeVolt's interpretation and from future intent. +6. State limits and uncertainty in plain language. +7. Remove a claim when the evidence is incomplete or ambiguous. + +The independent reviewer reads the evidence, not just the draft. Numbers and declared totals are checked programmatically where possible. A merge confirms the upstream outcome only. It does not prove every conclusion CodeVolt may draw from it. + +## Write like a person + +The final copy should sound like a capable person explaining real work to another person. + +Use ordinary words and specific details. Vary sentence length naturally. Match the tone of the channel and the maintainer. Keep technical terms when they are accurate and useful. + +Remove common signs of generated copy before publication. These include chatbot greetings, canned introductions, inflated claims, vague authority, promotional language, artificial three part lists, repeated bold labels, decorative emojis, generic conclusions and rhetorical questions that answer themselves. + +Do not use em dashes in public copy. Do not use dash led fragments to manufacture rhythm. Use a normal list only when it helps the reader follow instructions or compare facts. Keep required hyphens inside technical identifiers, commands and established compound terms. + +These style rules apply to CodeVolt's own words. Reproduce quoted upstream text, command output, code and identifiers exactly, including punctuation from the source. Never edit a quotation to satisfy a style rule. If a quotation cannot be reproduced exactly, paraphrase it and remove the quotation marks. + +Humanising does not mean adding fake mistakes, invented opinions, personal history or forced quirks. A named representative may use an approved personal voice without claiming work or experience they did not have. + +Read the copy aloud. Rewrite any sentence that sounds generated, assembled, theatrical or more confident than the evidence. + +## Review before posting + +Consequential means any public copy that claims completed work or contribution credit, names another project, maintainer or person, states a number, date, version, count or state, describes CodeVolt's capability, security, customers or future direction, or is published outside this repository. Anything uncertain is treated as consequential. + +One model family may draft or revise the copy. A different model family must check factual support, omissions, tone and generated writing patterns. The accountable human approves consequential public claims and any material about CodeVolt's identity, capability, security, customers or future direction. + +The review record must name: + +1. The evidence checked. +2. The authoring model or person. +3. The independent reviewer. +4. Corrections made after review. +5. Claims removed or limited. +6. The person who approved publication. + +If the independent review is unavailable, consequential public copy waits. Passing `scripts/validate_public_content.py` does not mean the copy has been reviewed. + +## Correct mistakes openly + +If published copy is wrong, the accountable human owns the correction and makes it within one working day of confirming the error. Correct the public source in place where the channel allows editing. Where it does not, publish a visible correction that links the original and leave the original in place unless it is harmful. Do not delete silently. Record the correction and its cause in `CHANGELOG.md`, and update any dependent Field Note or social copy. Do not quietly preserve a stronger claim after its evidence has changed. diff --git a/README.md b/README.md index c039c9f..c6dc149 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,7 @@ It is not a live operations feed, a complete description of CodeVolt, a customer - [`checklists/one-file-fix.md`](checklists/one-file-fix.md): keep a genuinely contained fix contained. - [`checklists/small-technical-handover.md`](checklists/small-technical-handover.md): hand over what changed, how it was checked and how to undo it. - [`templates/public-work-note.md`](templates/public-work-note.md): prepare a restrained public note backed by public evidence. +- [`PUBLIC_COMMUNICATION_STANDARD.md`](PUBLIC_COMMUNICATION_STANDARD.md): verify facts and remove generated writing patterns before publication. ## Use diff --git a/scripts/validate_public_content.py b/scripts/validate_public_content.py index 8679a9b..8cca620 100644 --- a/scripts/validate_public_content.py +++ b/scripts/validate_public_content.py @@ -11,14 +11,16 @@ REQUIRED = { "README.md", "PUBLICATION_POLICY.md", + "PUBLIC_COMMUNICATION_STANDARD.md", "MAINTENANCE.md", "CONTRIBUTING.md", "SECURITY.md", "SUPPORT.md", "CHANGELOG.md", "LICENSE", + "templates/public-work-note.md", } -FORBIDDEN = { +SAFETY_FORBIDDEN = { "BEGIN PRIVATE KEY": "private-key material", "BEGIN OPENSSH PRIVATE KEY": "private-key material", "/Users/": "local macOS home path", @@ -28,13 +30,30 @@ "external contractor": "internal staffing disclosure", "external agent": "internal staffing disclosure", "CONTRACTOR_X_BRIEF": "internal publishing-operations reference", +} +STYLE_FORBIDDEN = { "I hope this helps": "chatbot carry-over", "Let me know if you'd like": "chatbot carry-over", "Let's dive in": "formulaic introduction", "Here's what you need to know": "formulaic introduction", "As an AI": "chatbot self-reference", + "—": "em dash associated with generated public copy", + "–": "en dash used as an em dash substitute", + "―": "horizontal bar used as an em dash substitute", + "—": "escaped em dash", + "—": "escaped em dash", } LINK_RE = re.compile(r"!?\[[^\]]*\]\(([^)]+)\)") +FENCE_RE = re.compile(r"^```.*?^```", re.MULTILINE | re.DOTALL) +INLINE_RE = re.compile(r"`[^`\n]+`") +BLOCKQUOTE_RE = re.compile(r"^\s*>.*$", re.MULTILINE) + + +def own_prose(text: str) -> str: + """Return CodeVolt prose without quoted evidence, code or identifiers.""" + text = FENCE_RE.sub("\n", text) + text = INLINE_RE.sub(" ", text) + return BLOCKQUOTE_RE.sub("", text) def main() -> int: @@ -54,9 +73,13 @@ def main() -> int: errors.append(f"empty public file: {rel}") continue if rel != Path("scripts/validate_public_content.py"): - for token, label in FORBIDDEN.items(): + prose = own_prose(text) + for token, label in SAFETY_FORBIDDEN.items(): if token in text: errors.append(f"{rel}: contains {label}") + for token, label in STYLE_FORBIDDEN.items(): + if token in prose: + errors.append(f"{rel}: contains {label}") if path.suffix == ".md": for target in LINK_RE.findall(text): target = target.split("#", 1)[0] @@ -71,6 +94,33 @@ def main() -> int: if not resolved.exists(): errors.append(f"{rel}: broken relative link: {target}") + marker_sets = { + "PUBLIC_COMMUNICATION_STANDARD.md": [ + "## Check the facts", + "## Write like a person", + "## Review before posting", + "## Correct mistakes openly", + ], + "PUBLICATION_POLICY.md": [ + "## Correctness review", + "PUBLIC_COMMUNICATION_STANDARD.md", + ], + "templates/public-work-note.md": [ + "## Source check", + "## Final public copy", + "## Review record", + "Independent editorial and factual review completed", + ], + } + for name, markers in marker_sets.items(): + path = ROOT / name + if not path.is_file(): + continue + text = path.read_text(encoding="utf-8") + for marker in markers: + if marker not in text: + errors.append(f"{name}: missing publication marker: {marker}") + if errors: for error in errors: print(f"ERROR: {error}") diff --git a/templates/public-work-note.md b/templates/public-work-note.md index 8a77e75..91790a3 100644 --- a/templates/public-work-note.md +++ b/templates/public-work-note.md @@ -10,6 +10,10 @@ One sentence explaining what a reader can learn or use. Exact public file, issue, pull request, commit or release URL: +## Source check + +For each factual statement, record the exact source and what it proves. Recheck issue state, merge state, version, date, count and maintainer decision immediately before publication when applicable. + ## What was done A bounded factual description. Do not imply broader completion than the evidence supports. @@ -22,15 +26,40 @@ What a reader can inspect, run or compare: What this does not prove or cover: +## Final public copy + +Write the approved text here after the evidence and natural language reviews. Do not use em dashes or dash led fragments for rhythm. Keep technical identifiers exact. + ## Suggested X draft -Useful observation first. Evidence link second. Optional work-enquiry route last. +Useful observation first. Evidence link second. Add a work enquiry only when it belongs naturally. + +## Review record + +Authoring person or model: + +Independent reviewer: + +Evidence opened and checked: + +Corrections made: + +Claims removed or limited: + +Publication approval: ## Publication check - [ ] No customer, personal, credential, infrastructure, recovery or private repository information - [ ] No unresolved security finding - [ ] No unsupported price, metric, timeline or future capability -- [ ] Contribution claim is backed by an exact public link +- [ ] Contribution claim is backed by an exact public link that the reviewer opened and checked +- [ ] Changeable facts were rechecked immediately before publication +- [ ] Commands, tests, examples, dates, versions, counts and states are correct where used +- [ ] Fact, interpretation and future intent are clearly separated +- [ ] Limits and uncertainty are stated plainly +- [ ] Natural language review removed common generated writing patterns, including em dashes and dash led fragments +- [ ] Independent editorial and factual review completed +- [ ] Consequential claims have accountable human approval - [ ] GitHub is supporting evidence rather than the whole CodeVolt story - [ ] Approval obtained if the subject is customer-derived, security-related or otherwise uncertain