Authoring-assist: promote to first-class tool with non-blocking PR advisory - #121
Draft
dayland wants to merge 2 commits into
Draft
Authoring-assist: promote to first-class tool with non-blocking PR advisory#121dayland wants to merge 2 commits into
dayland wants to merge 2 commits into
Conversation
…visory
Promotes the authoring-assist prototype to a first-class BCQuality feature that
reviews knowledge-article front-matter and proposes missing routing `signals:`
(raise triggers and `effect: suppress` suppressors). The suggestion is ADVISORY
ONLY: it never fails a build; authors apply it via a normal PR under existing
R29 + CI + CODEOWNERS review.
Feature:
- tools/Suggest-ArticleSignals.ps1: suggestion engine hardened with a stable JSON
contract (schemaVersion/toolVersion) and a deterministic, effect-sensitive
per-proposal suggestionId, plus -ChangedFiles scoping for PR-diff runs. Runs
self-contained: the routing seed is now OPTIONAL (built-in domain map), so this
does not depend on the separate routing-index tuning thread.
- tools/New-AuthoringAssistComment.ps1: renders one upsertable, feedback-instrumented
advisory comment (stable anchor + aa:meta/aa:article markers carrying suggestionIds
+ reaction footer) for the downstream acceptance-measurement work.
- .github/workflows/authoring-assist*.yml: unprivileged pull_request intake +
trusted workflow_run runner (review/publish split) + in-repo self-test.
- tools/Test-SuggestArticleSignals.ps1: 23-check smoke test (contract, determinism,
scoping, suppressor/prohibition, renderer markers, seed-free graceful degradation).
Dormant schema support:
- .github/scripts/validate_frontmatter.py: adds R29, validating the optional
`signals` block shape (bare token or mapping with token + optional
pattern/domain/effect in {raise,suppress}). Reserved & dormant — no production
pipeline consumes it; the existing PR Reviewer only reads `effect: suppress`
behind its BCQ_INDEX_V2 flag and falls back safely when absent. Existing rules
(incl. R24 skill-id uniqueness, R27, R28) are unchanged.
Excludes the routing-index tuning thread entirely (separate work).
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 75d852d6-18a6-4c58-986f-ed5ab16618fa
The review and publish jobs run in the same workflow_run; the artifact is intra-run. Downloading with run-id set to the intake run (github.event.workflow_run.id) looked in the wrong run and failed with 'Artifact not found'. Drop run-id/github-token so download-artifact resolves the artifact uploaded earlier in this run. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 75d852d6-18a6-4c58-986f-ed5ab16618fa
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Promotes the authoring-assist prototype to a first-class BCQuality feature: it reviews knowledge-article front-matter and proposes missing routing
signals:(raise triggers +effect: suppresssuppressors), then posts a non-blocking, feedback-instrumented advisory comment on PRs that touch**/knowledge/**/*.md.The advisory is ADVISORY ONLY — it never fails a build. Authors apply suggestions via a normal PR under existing
R29+ CI + CODEOWNERS review.What's included
suggestionId,-ChangedFilesscoping, optional seed)tools/Suggest-ArticleSignals.ps1aa:meta/aa:articlemarkers + reaction footer)tools/New-AuthoringAssistComment.ps1.github/workflows/authoring-assist{,-runner,-selftest}.ymltools/Test-SuggestArticleSignals.ps1tools/authoring-assist.mdR29validates the optionalsignalsblock shape.github/scripts/validate_frontmatter.pyDormant schema — safe by design
The
signals/effectkeys are present but dormant. No production pipeline consumes them:effect: suppressbehind itsBCQ_INDEX_V2flag (off in prod) and falls back safely when absent.validate_frontmatter.py.R24skill-id uniqueness,R27,R28) are unchanged;R29is purely additive.Explicitly out of scope
Validation
Rollout note for reviewers
Draft pending: confirm workflow permissions posture (unprivileged
pull_requestintake + trustedworkflow_runpublish) and whether to pin actions to SHAs (repo currently uses@vNtags).