You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Community Markdown receives reliable pull request validation - #12
Contributors to MSXOrg/.github receive a named, read-only check for applicable source changes, including Markdown-only updates and PRs retargeted to main. PR descriptions use canonical guidance only; this validator does not require, copy, generate, or compare a PR template. Ordinary repositories need no validator installation or copied policy files.
Correct reported Markdown violations even if a file contains a markdownlint disable/configuration directive. Every selected .md file is read literally and linted with unchanged shared rules and noInlineConfig: true from an isolated temporary configuration. Inline directives, local ignores/configuration, and glob-like filenames cannot hide selected Markdown; valid directive examples still pass. Explicit opened, synchronize, reopened, and edited activities cover updates and retargeting to main without a new commit.
Use PowerShell 7.4+, Git, and Node.js/npm in this source repository. Fetch the intended base and commit the content being checked. The native runner discovers .github/tests without a Path override, and CI exercises that default. Pinned tooling is restored when needed:
Intentional template absence/deletion is valid. Removed paths come from the committed diff with case-sensitive identity and are not counted as linted content. Empty/unsupported-only inputs and zero-file Markdown scans fail. Test discovery cannot pass when no test passes, including skipped-only suites; summary and exit use the same success condition. The obsolete scaffold fixture/comparison is removed, not replaced.
Absence is not record-quality proof. Actual titles/descriptions still need canonical PR Format's boundary, ordered results, complete consumer actions, scoped evidence, and release decisions only on applicable release-managed routes. Other defaults and product-integration templates are distinct. #8 owns central removal at 990bfcbfd1275f80d58b3a9c51781f3873e22876; this PR does not edit its paths, forms, consumer copies, hooks, release contracts, or live governance.
Technical details
Verified head:a6c4484fa197f44bf45e244e17480cb40deafd3e, merge base 0c67251812ea306543f3a14ab473ae357cfb76ac. Run 41248565958 completed successfully at this exact head. Its job/check completed actual-head/source validation, literal Markdown lint, all 44 tests, and the remaining PowerShell/YAML/Actions/security routes. The earlier cancelled run is not used as validation evidence.
Exact check/source:Organization defaults validation, GitHub Actions integration/app 15368, from .github/workflows/Organization-Defaults-Validation.yml. Default-deny permissions, only contents read, actual-head verification, and disabled persisted credentials/language-status writes/PR-summary comments are preserved. Literal Markdown precedes other include-only Super-Linter routes. No publication, tag/label mutation, rules/access change, merge, or auto-merge was performed.
Case reproduced before correction
Observed defect
Verified correction
Malformed Markdown behind whole-file disable
Released hosted parser exits 0 although plain malformed text exits 1
Anonymous controller passes and distinguishes deletion from linted content
Edited retarget to main
Default activities exclude edited
Explicit activity coverage passes; no production retarget experiment is claimed
Mixed linter flags
Actual hosted initialization fails
Include-only regression and subsequent hosted routes pass
PowerShell wildcard path plus unchanged match
Path invocation analyzes the wrong file; literal changed content produces its warning
Surviving wildcard-bearing PowerShell inputs fail before counting lint inputs
Native runner default
Root test-directory lookup fails
.github/tests default, anonymous/full default invocation, and CI default execution pass
Case-only rename
Deleted path is hidden
Case-sensitive committed deletion/live lists report one of each
Skipped-only discovery
Exit 0 with no passed regressions
Zero-passed-test guard exits 1 with explicit diagnostic
Skipped-only summary
Failure exit still writes success heading
One Pester success decision controls summary/exit; regression verifies both
Every listed defect was demonstrated before correction. All 44 local and hosted tests pass in two suites, with zero failed/skipped/not-run tests. Source/head/containment, nonempty checks, literal paths, valid examples, links, staged/unstaged consistency, and control/backslash/finder-pruned guards remain intact.
Actual checked input scope
Result
Existing applicable changed files
13
Changed Markdown actually linted
1: .github/VALIDATION.md
Checked deletions in this PR's base-to-head diff
0; #8 owns central removal and the removed fixture has no net base-to-head file
Shared configuration sources verified
4
Required template/scaffold files
None
Deletion-only anonymous inputs report one checked deletion and zero linted Markdown, verify sources, and skip only inapplicable other-language lint. This is not an empty-input or Markdown pass. The isolated skipped-only suite is rejected and its summary is failure, not executed-regression proof.
#8 compatibility: Actual head 990bfcbfd1275f80d58b3a9c51781f3873e22876 versus base 0c67251812ea306543f3a14ab473ae357cfb76ac changes only two guides and central deletion. Both changed contents pass this literal/no-inline checker. The complete inventory has 42 files and zero PR templates. This is local source compatibility, not a hosted #8 check, record-quality approval, or merged-deletion claim; its checkout was untouched.
Metadata pins configuration Git blobs from MSXOrg/docs 36da9154aa55d2052345fb2f28b812b29daf8bc9 and Super-Linter 4ce20838b8ab83717e78138c5b3a1407148e0918, not a scaffold fingerprint. The shared Pester helper has the documented source-local default and unified real-success adaptations. External SHA pins and permissions are unchanged.
Ownership:Repository Standard owns no-file policy; PR Format owns record quality. This ready, unmerged source is authoring context, not a runtime dependency. Absence does not certify coverage, actions, markers, sections, or evidence.
Complete review disposition:The exact-head review completed with no new inline findings; all nine threads are resolved and pagination completed. The entire summary was read. Its remaining concern cited a superseded cancelled CI run; the newer completed actual-head run above independently resolves that evidence gap. No zero-inline count was used to dismiss code or summary concerns. Every actionable finding in this work was reproduced and corrected.
Separate follow-up, not consumer policy-copy enforcement
Plan/convergence: Seven ordinary commits complete the user-directed no-template revision, demonstrated Markdown/retarget fixes, and tightly coupled full-review corrections. #11 closes through this PR; #8/#10 and the hook follow-up remain separate. No forms, consumer copies, release signals, or live check requirements are changed.
Operational state: The repository owner externally marked this PR ready at 22:38:19Z; this session did not change readiness. Independent native read-back confirms Agent merge maintenance enabled, review/CI/conflict actions enabled, merge_pr=false, and GitHub autoMergeRequest=null. No merge or enqueue was performed. Inherited main rules still name no required status checks: requiring exactly Organization defaults validation from GitHub Actions/app 15368 remains a separately unapproved governance action. The visible ready state does not waive that governance boundary. This source route delivers public community files, not versioned artifacts, so no release-decision block or release label applies.
The reason will be displayed to describe this comment to others. Learn more.
🟡 Changes recommended
The changed-file filter can select unrelated Markdown and skip filenames containing tabs or form feeds, while the documented non-Windows command cannot load its configuration.
Adds read-only pull request validation for organization community defaults, addressing #11 without changing the inherited template or README. Fallback-format delivery and local pre-commit hooks remain separate work.
Changes:
Adds an exact-head workflow for changed-input validation, Pester tests, and selected linters.
Validates changed fallback scaffolds against a pinned source fingerprint, with malformed-content and file-selection regression tests.
Documents local validation and adds shared lint configurations and Dependabot updates.
The reason will be displayed to describe this comment to others. Learn more.
🟡 Changes recommended
Critical validation gaps omit supported template locations, allow symlinks to bypass linting and scaffold checks, and can report success for malformed committed content by validating uncommitted working-tree changes.
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
Path handling and linter discovery can silently skip selected files with backslashes or files in pruned directories, allowing validation to pass without checking all applicable changes.
No open issues 🎉
2 previously missed issues
In code that hasn't changed since last review
Reject backslashes in input paths to avoid skipping Markdown files
.github/scripts/PullRequestValidation.psm1:196
On Linux, Join-Path treats a literal backslash in a filename as a directory separator, so a committed file such as changed\file.md can be silently omitted from MarkdownFiles and the linter filter. When another ordinary applicable file changes, validation can therefore pass without checking that Markdown file. Reject backslash-containing input paths before this selection and add a filename regression.
Ensure linter-pruned files are not counted as validated inputs
The pinned Super-Linter finder prunes directories such as node_modules, .venv, and __pycache__, but Get-ValidationInput still counts supported files there as applicable inputs. A malformed node_modules/broken.md alongside a valid ordinary Markdown change is therefore reported as an input but never linted, allowing an incomplete check to pass. Use discovery that includes every selected file, or reject excluded inputs explicitly, and add a regression for this case.
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
Human assessment is needed because a critical validation bypass can let changed Markdown pass without being linted, alongside missing checks when PRs are retargeted.
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
Human assessment is needed because case-only renames can bypass deletion validation on Ubuntu, and this moderate finding was omitted from the published review.
The reason will be displayed to describe this comment to others. Learn more.
🟡 Changes recommended
Skipped-only runs receive a success heading before the zero-passed-test guard exits with failure, so the summary verdict must use the same pass conditions as the exit decision.
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
The cited CI run was cancelled before other-language lint completed, so a completed hosted result for the actual head is still needed before landing the validation gate.
Write MSX pull request descriptions from canonical PR-format guidance
instead of an automatically populated organization template. This change
removes the central PR template without creating a replacement and links
the contribution guide to the complete actual-record example. The README
identifies the maintainers and contributors who use these defaults and
instructions.
Other community defaults and issue forms remain unchanged. Existing PR
descriptions are not erased or rewritten; no runtime, configuration, or
intermediate-upgrade action is required.
<!-- ANNOUNCEMENT STOP -->
## Removed: Organization PR-template distribution
The organization no longer supplies a GitHub PR-template file. Authors
write the actual title and description using [canonical MSX PR Format
instructions](https://msx.no/docs/Ways-of-Working/PR-Format/) and its
complete description example. Do not replace the removed fallback with
root, `.github`, or `docs` template files or a `PULL_REQUEST_TEMPLATE`
directory. [Repository
Standard](https://github.com/MSXOrg/docs/blob/bc03a5992615f65d1d5346dc48e7506e80b8b6ca/src/docs/Ways-of-Working/Repository-Standard.md#no-pr-template-files)
owns the file policy; PR Format owns the actual record's structure,
source coverage, consumer actions, and evidence.
The sole actual template in this candidate was
`.github/pull_request_template.md`, and it is deleted. README and
contribution links point to the file policy and authoring instructions.
The README now names MSX repository maintainers and contributors:
maintainers use GitHub's community-file fallback to share organization
guidance, and contributors use canonical MSX instructions to write PR
descriptions on GitHub. The public-visibility requirement and local-file
precedence statements are unchanged. Other community defaults, issue
forms, media, client routes, repository-specific contribution
instructions, and product integration templates are unaffected.
To verify adoption, inspect the candidate tree for zero GitHub
PR-template files and write a new PR description from canonical
guidance. No consumer configuration or code edit is required. Existing
open descriptions remain intact.
<details>
<summary>Technical details</summary>
**Exact candidate and scope:**
[3f3ce97](3f3ce97),
compared with base `0c67251812ea306543f3a14ab473ae357cfb76ac`. The full
diff contains only the template deletion and the two directly coupled
guides. Accepted shared-media content, attributes, other defaults, and
issue forms remain unchanged. Earlier template-distribution commits
remain in history, but no replacement template, generator, or copied
scaffold exists in the candidate.
**Canonical no-file authority:**
[MSXOrg/docs#209](MSXOrg/docs#209), source
`bc03a5992615f65d1d5346dc48e7506e80b8b6ca`, is now merged; its native
Task MSXOrg/docs#226 is closed. The exact source remains the no-file
correspondence:
- [Repository
Standard](https://github.com/MSXOrg/docs/blob/bc03a5992615f65d1d5346dc48e7506e80b8b6ca/src/docs/Ways-of-Working/Repository-Standard.md#no-pr-template-files)
owns the prohibition on GitHub PR-template files.
- [Organization
Standard](https://github.com/MSXOrg/docs/blob/bc03a5992615f65d1d5346dc48e7506e80b8b6ca/src/docs/Ways-of-Working/Organization-Standard.md#community-files-are-organization-defaults)
and [defaults-source
governance](https://github.com/MSXOrg/docs/blob/bc03a5992615f65d1d5346dc48e7506e80b8b6ca/src/docs/Capabilities/repository-governance/design.md#organization-defaults-repository)
preserve the other defaults and product integration templates.
- [PR Format's complete description
example](https://github.com/MSXOrg/docs/blob/bc03a5992615f65d1d5346dc48e7506e80b8b6ca/src/docs/Ways-of-Working/PR-Format.md#complete-description-example)
owns the actual record. Its [release-coverage-first
analysis](https://github.com/MSXOrg/docs/blob/bc03a5992615f65d1d5346dc48e7506e80b8b6ca/src/docs/Ways-of-Working/PR-Format.md#resolve-release-coverage-first),
one marker, ordered results, scoped evidence, consumer actions,
effective defaults, and Task/Bug planning remain intact.
**README writing-alignment evidence:** This revision adds only four
lines to `README.md` after candidate
`990bfcbfd1275f80d58b3a9c51781f3873e22876`. Before, the text explained
fallback behavior and canonical PR guidance but did not explicitly
identify its audience, jobs, or supported interfaces. After, it names
maintainers and contributors and connects their jobs to GitHub
community-file fallback and canonical-instruction PR authoring. Removing
only the new paragraph reproduces all prior README text after
line-ending normalization. This preserves the verified
public/default-file statements, links, media paragraph, and no-template
policy without a broader rewrite.
The fixed campaign evidence is [README target
audience](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/Readme-Driven-Context.md#target-audience),
[Natural
Language](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Natural-Language.md),
and the [Technical Writing
Guide](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Writing-Guide.md).
The official [STE
explanation](https://www.asd-ste100.org/about_STE.html),
[FAQ](https://www.asd-ste100.org/STE_faq.html), and [Issue 9
record](https://doi.org/10.5281/zenodo.23666006) were read for short
active sentences, en-US, and technical terminology. This is a scoped
clarity review, not a claim of full dictionary-level STE conformance.
| Changed surface | Standards checked | Framework docs checked | Result
|
| --- | --- | --- | --- |
| Deleted `.github/pull_request_template.md` | User-confirmed
no-template decision and immutable Repository Standard | Organization
Standard and defaults-source governance | Aligned |
| `README.md` | Campaign-pinned target-audience requirement, Natural
Language, Markdown, Technical Writing Guide, and official STE
explanations | None (no framework-specific docs) | Aligned |
| `.github/CONTRIBUTING.md` | Repository Standard file policy and
actual-record PR Format | None (no framework-specific docs) | Aligned;
unchanged by the audience clarification |
**Local verification:** The explicit-audience assertion fails at the
prior candidate and passes after the README addition. The
preserved-content assertion passes, and the incremental changed-file
inventory contains only `README.md`. The shared Markdown rules fetched
at campaign commit `1b0d4893c8fefabe604d04393068a8ff6f848082` validate
the changed README and finalized PR body with zero issues. The
no-template outcome, current-base diff check, and clean worktree are
verified. No new toolchain or validation-owner file is added.
**Implementation plan and convergence:** The existing #10
record retains the campaign's before/after evidence and completed
README-only step. The no-template implementation remains the same
deliverable; this revision creates no extra issue or assignment. It
closes only that Task. Separate validation, pre-commit, and
feature-intake work is not delivered or closed by this diff.
**Current-head review:** The explicit [Copilot
round](#8 (review))
at `3f3ce97f29da19d5fe3ad3cc540fa906cda8589b` exited `0` and submitted
`APPROVED`. The full summary reports no active review issues; there are
zero inline comments and zero unresolved threads. This is the
current-head automated review result, not a claim that missing
code-validation or governance gates passed. Earlier reviews and the
previous head's source-bound local compatibility remain historical
evidence only.
**State and separate gates:** **HISTORICAL - README-clarification
checkpoint:** The PR was already open and ready before this README
clarification; its draft state and merge settings are unchanged. GitHub
`autoMergeRequest` is null. The canonical no-file source prerequisite
has landed. #12 is still open and unmerged, and the live
main ruleset names no required-status-check rule. This README update
does not claim that hosted code validation or required enforcement is
complete. Local Markdown checks and the successful reviewer job are not
substitutes for those gates. No merge, Agent merge settings change,
publication, label, ruleset, or live enforcement action is included.
**CURRENT:** The PR is open and ready. Maintenance Agent merge is
enabled with `merge_pr=false`; GitHub auto-merge is off. Root has
operationally accepted the freshly documented exact-head static,
native-rendering, link, and interface evidence under the new live user
direction. Hosted code-validation CI remains absent, not passed; this
implies no policy or bypass change. Any merge still requires root's
not-yet-granted exclusive global slot, normal protected exact-head
checks, and native prerequisites.
**Release applicability:** This community-default route does not publish
a versioned artifact. It has no release-decision block or release labels
and does not invent a consumer-publication baseline. The current-base
comparison is scoped implementation evidence, not substituted release
coverage.
</details>
<details>
<summary>Related references</summary>
- Resolves#10
- References MSXOrg/docs#226
- References [MSXOrg/docs#209](MSXOrg/docs#209)
- References #11
- References
[#12](#12)
</details>
---------
Co-authored-by: Marius Storhaug <Marius.Storhaug@dnb.no>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
<!-- Lead with one concise paragraph describing the user-facing outcome.
-->
Feature requesters describe their need, motivation, and expected result
without choosing an implementation or learning a special scenario
format. The shared form keeps its feature identity, routing, and one
required free-text field.
<!-- ANNOUNCEMENT STOP -->
<!-- Add user-facing sections for breaking, new, changed, or fixed
behavior when needed. -->
## Changed: Consumer-focused feature intake
The **Describe the need** field requests who benefits, the problem or
opportunity, and a situation/action/result example. A failure or limit
example is conditional. The introduction uses direct requests and states
the feedback/internal-planning boundary as current fact. Technical
Task/Bug plans, existing labels, native-type selection, and minimum
submission requirements are unchanged.
## Adopting this release
After merge, repositories that use this organization-owned form receive
the prompts without consumer-local copies. No configuration, code, or
invocation change is required. Local issue forms retain precedence and
are not changed here. This public defaults repository does not publish a
versioned release.
## Release impact
This is a compatible, patch-level intake improvement. No versioned
publisher applies and no version is produced. No live labels, release
configuration, permissions, rulesets, or merge settings change.
---
<details>
<summary>Technical details</summary>
<!-- Record the implementation approach, issue-plan progress, standards
alignment, and convergence sweep. -->
### Consumer change record
| Surface | Before | After | Consumer action / verification |
| --- | --- | --- | --- |
| Organization feature form | Required Description asks for
implementation suggestions and alternatives. | The same `description`
field asks for consumer need, motivation, and observable examples. Name,
title, labels, native-type absence, and required-field contract remain.
| No consumer edit. One-time YAML/interface, native rendering, and
actual link checks are recorded below. |
### Template baseline
Head `9a4da3a0dacf7cfc68cad80270884886bcdc1ad9` targets `main` at
`0c67251812ea306543f3a14ab473ae357cfb76ac`. The final PR diff is **one
modified feature form: 17 additions, 7 deletions**. No added test or
validator remains.
The form is byte-for-byte equal to candidate
`589285cfb6c2ecc761c5308de4527d2dd2c54bd4`, with blob
`19d6abbbf5b1a4a5b48ce5710be9f7e79f0be742`. The latest commit removes
only the 119-line added test suite; it changes no form content or
behavior and no other source file.
The consumer guidance is published:
[MSXOrg/docs#230](MSXOrg/docs#230) merged on
2026-11-03 at `8c9d9353eb154d6072b3ed1d825a78d58a4665d3`. The fixed
[writing
baseline](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Natural-Language.md)
and official STE guidance govern the unchanged prose. Shipped links use
the current canonical planning/routing pages, not an immutable review
snapshot.
### Maintainer evidence
**Test-policy correction.** The whole `FeatureIntake.Tests.ps1` file was
added by this PR. Its 12 cases froze checked-in YAML metadata, shape,
phrases, URLs, or blank configuration; built-in Markdown conversion
exercised no owned runtime. The [current Testing
rule](https://github.com/MSXOrg/docs/blob/f9b335d0b78a3eead0b7efa573936e86cb1e7265/src/docs/Coding-Standards/Testing.md#test-supported-behavior)
prohibits those source-string and snapshot assertions. The user-directed
review supersedes the earlier campaign limit on removing them. All 12
passed immediately before removal: this is conformance, not hiding a
failing test. No owned-runtime coverage or conflicting content decision
was found. There is no replacement test, validator, simulation, tooling,
or configuration. **No runtime suite remains and no current test pass is
claimed.** Earlier suite results and reviews are historical evidence for
their stated commits only.
**Fresh one-time checks.** Configuration/reference results stay outside
source. With `$configuration` naming the published default snapshot and
`$target.Path` each named input:
| Actual command / operation | Result |
| --- | --- |
| `python -` (inline PyYAML interface and raw-byte inspection) | 20
nodes, 6 mappings, 2 body elements, 1 required `description` textarea.
All non-prose keys/order/types/values and blank configuration match the
original base. The current form bytes exactly match `589285c`. |
| `yamllint --format parsable --config-file $configuration
$target.Path`; repeat with `--strict` | All 6 runs (original `0c6725`,
prior `589285c`, and current form; normal and strict) return exit 0 with
0 diagnostics. No baseline formatting change or weakened rule. |
| `gh api --method POST markdown --input -` with actual introduction,
`mode=gfm`, `context=MSXOrg/.github` | Native GitHub HTML renders
exactly 2 canonical links. |
| `python -` (inline unauthenticated HTTPS/actual HTML inspection) | 2
targets return HTTP 200:
[planning](https://msx.no/docs/Ways-of-Working/Issues/Process/Planning/)
contains `issue-planning`;
[routing](https://msx.no/docs/Ways-of-Working/Issues/Types/Hierarchy/)
contains `issue-hierarchy`. Neither form link has a fragment. |
| `git diff --name-status origin/main...HEAD`; `git diff --check` |
Exactly one modified feature form; whitespace check passes. |
YAML-default provenance: [current
Docs.yml](https://github.com/MSXOrg/docs/blob/f9b335d0b78a3eead0b7efa573936e86cb1e7265/.github/workflows/Docs.yml)
selects Super-Linter `4ce20838b8ab83717e78138c5b3a1407148e0918` without
a YAML override. Its [published
default](https://github.com/super-linter/super-linter/blob/4ce20838b8ab83717e78138c5b3a1407148e0918/TEMPLATES/.yaml-lint.yml),
blob `2aa49bd1867e24acdea4172191922df6135b69c6`, is used locally only.
It is not installed repository CI or a nonexistent MSX YAML override.
The configuration bytes match that source exactly. Its [yamllint
dependency
pin](https://github.com/super-linter/super-linter/blob/4ce20838b8ab83717e78138c5b3a1407148e0918/dependencies/python/yamllint.txt)
is `yamllint==1.38.0`, matching the local tool.
These observations establish static interface preservation, rendered
links, and actual page/anchor availability. They are **not owned-runtime
tests, GitHub form-submission end-to-end coverage, or hosted CI**.
| Changed surface | Guidance / result |
| --- | --- |
| Feature form | YAML, Natural Language, canonical planning/routing, and
GitHub form schema checked; consumer content and routing preserved. |
| Removed added suite | Current Testing prohibition applied by deletion;
no source-shape test or replacement remains. |
The existing Task plan and evidence are updated. Scoped convergence
finds no additional fully delivered issue: #10 concerns
community PR templates, #11/#12 hosted validation,
#13 hooks, and #16/#17/#18 other campaign
surfaces. Only #14 closes here. No new issue, CI/toolchain
work, rule, or label is introduced.
**Final review and native state.** The explicitly requested
[current-head Copilot
review](#15 (review))
is `APPROVED` at `9a4da3a0dacf7cfc68cad80270884886bcdc1ad9`, with no
active code issues or inline comments. All 5 submitted reviews were
read: 4 historical `COMMENTED` reviews and this approval. Complete
thread pagination reports 0 threads. GitHub now reports
`MERGEABLE/CLEAN` and review decision `APPROVED` for the exact head/base
above. The only check run is the successful
`copilot-pull-request-reviewer`; there are 0 commit statuses, and the
GraphQL rollup remains empty. No actually failing or named required
check is reported. **Organization defaults validation has not executed
at this head**: a successful reviewer check is not hosted form
validation. Separate
[#12](#12) remains
unmerged and is not revived here. Absent execution is not a pass.
Effective organization rules preserve squash-only integration,
stale-review dismissal, code-owner review, last-push approval, and
resolved threads. No named required-status-check rule is present. Those
review/approval prerequisites are not waived by local checks or a
Copilot run.
The PR remains open/non-draft. GitHub auto-merge and merge-queue entry
are null. Agent merge remains enabled for review/CI/conflict maintenance
with `merge_pr=false`; no settings changed. Root holds an exclusive
global merge slot elsewhere. **No merge is authorized in this session
until that slot is handed off.** No content decision is unresolved.
</details>
<details>
<summary>Relevant issues (or links)</summary>
<!-- Use fully qualified repository references for closing and related
work. -->
- Resolves#14
### Related work
- References
[MSXOrg/docs#228](MSXOrg/docs#228) and merged
[MSXOrg/docs#230](MSXOrg/docs#230) for canonical
consumer guidance.
- References
[#11](#11) and
[#12](#12) for
separate hosted validation.
- References
[#13](#13) for
separate local hooks.
</details>
…19)
<!-- Lead with one concise paragraph describing the user-facing outcome.
-->
Private vulnerability reporting instructions give the availability
condition before the command to use the repository's Security tab. The
email fallback and reporting policies stay unchanged.
<!-- ANNOUNCEMENT STOP -->
<!-- Add user-facing sections for breaking, new, changed, or fixed
behavior when needed. -->
## Fixed: The private-reporting condition comes first
Reporters read the availability prerequisite before the instruction. The
sentence keeps its direct imperative form. No reporting route, policy,
or required reporter action changes.
---
<details>
<summary>Technical details</summary>
<!-- Record the implementation approach, issue-plan progress, standards
alignment, and convergence sweep. -->
The diff changes only `.github/SECURITY.md:15-16`: two insertions and
two deletions in one small commit. Baseline:
`0c67251812ea306543f3a14ab473ae357cfb76ac`. Candidate:
`a45e33912b4fc594e090dd291271946ed6ce9dcb`. The remote PR file list and
local/upstream commit identities match.
| Evidence | First sentence |
| --- | --- |
| Before | `Use the affected repository's **Security** tab to report the
vulnerability privately when private vulnerability reporting is
available.` |
| After | `When private vulnerability reporting is available, use the
affected repository's **Security** tab to report the vulnerability
privately.` |
The existing clause moves before the command. The comma separates the
condition from the imperative. The email fallback is unchanged.
The [pre-edit evidence and complete policy-preservation
checklist](#18 (comment))
were recorded before editing. The [full verification
record](#18 (comment))
records exact policy, heading, link, and scope commands with results.
The comparison confirms that all other text is unchanged:
supported-release/default-branch policy and precedence;
public-disclosure prohibitions; private routes and addresses; sensitive
information, credentials, secrets, and weak controls; all requested
reporter evidence; private investigation and coordinated
remediation/disclosure. No service level, deadline, reporting channel,
feature enablement, or enforcement claim is added.
`.github/SUPPORT.md` is reviewed and unchanged. It already gives ordered
public-help steps, sanitized-evidence instructions, private support, and
security, conduct, and contribution routes. It tells reporters to remove
credentials, personal information, and other secrets before posting. Its
Git blob remains `18cdd55b35a3c0bd87165bbc96f131bf9f8ec83d`. Headings
and all five link targets are unchanged; three relative targets resolve
and the two email targets retain their exact addresses. No test report
or email was sent, and mailbox delivery is not asserted. Contributor
Covenant text and all other owned campaign paths remain untouched.
The source review uses MSXOrg/docs commit
`1b0d4893c8fefabe604d04393068a8ff6f848082`: [Documentation
Model](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/Documentation-Model.md),
[Natural
Language](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Natural-Language.md),
[Writing
Guide](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Writing-Guide.md),
[Markdown](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Markdown.md),
[Documentation](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Documentation.md),
and applicable implementation, contribution, PR, commit, branching, and
readiness guidance.
The [official overview](https://www.asd-ste100.org/about_STE.html),
[FAQ](https://www.asd-ste100.org/STE_faq.html), and [Issue
9](https://doi.org/10.5281/zenodo.23666006), Part 1, rule 5.4 (page
1-5-4), support the condition-first change. The reference PDF MD5
matches the official record: `9c720341c350ed77943b2c73d01c716f`.
Reference copies stay local. This is a focused rule review, not a claim
of full STE conformance. [GitHub's reporting
guide](https://docs.github.com/en/code-security/how-tos/report-and-fix-vulnerabilities/report-privately)
confirms that private vulnerability reporting depends on repository
enablement; the policy remains conditional.
### Verification
Exact test-first command:
```powershell
$policy = (Get-Content -LiteralPath '.github\SECURITY.md' -Raw) -replace '\s+', ' '; $expected = "When private vulnerability reporting is available, use the affected repository's **Security** tab to report the vulnerability privately."; if (-not $policy.Contains($expected)) { Write-Output 'FAIL (expected baseline): The availability prerequisite does not precede the Security tab instruction.'; exit 1 }; Write-Output 'PASS: The availability prerequisite precedes the Security tab instruction.'
```
Result: expected failure before editing, exit `1`; passed after editing,
exit `0`.
Exact full-policy and scope command:
```powershell
$ErrorActionPreference = 'Stop'
$base = '0c67251812ea306543f3a14ab473ae357cfb76ac'
$before = (git show "${base}:.github/SECURITY.md") -join "`n"
if ($LASTEXITCODE -ne 0) { throw 'Could not read the security baseline.' }
$old = "Use the affected repository's **Security** tab to report the vulnerability`nprivately when private vulnerability reporting is available. If that option is"
$new = "When private vulnerability reporting is available, use the affected repository's`n**Security** tab to report the vulnerability privately. If that option is"
if ([regex]::Matches($before, [regex]::Escape($old)).Count -ne 1) { throw 'The baseline instruction is not unique.' }
$after = (Get-Content -LiteralPath '.github\SECURITY.md') -join "`n"
if ($after -cne $before.Replace($old, $new)) { throw 'Unexpected security policy change.' }
Write-Output 'PASS: SECURITY.md is identical to the baseline except for the approved condition-order replacement.'
$beforeSupport = (git show "${base}:.github/SUPPORT.md") -join "`n"
if ($LASTEXITCODE -ne 0) { throw 'Could not read the support baseline.' }
$afterSupport = (Get-Content -LiteralPath '.github\SUPPORT.md') -join "`n"
if ($afterSupport -cne $beforeSupport) { throw 'Unexpected support policy change.' }
Write-Output 'PASS: SUPPORT.md is identical to the baseline.'
$changedPaths = @(git diff --name-only $base)
if ($LASTEXITCODE -ne 0 -or $changedPaths.Count -ne 1 -or $changedPaths[0] -cne '.github/SECURITY.md') { throw 'Unexpected changed paths.' }
Write-Output 'PASS: The only changed path is .github/SECURITY.md.'
git --no-pager diff --check $base
if ($LASTEXITCODE -ne 0) { throw 'Whitespace validation failed.' }
Write-Output 'PASS: git diff --check 0c67251.'
```
Result: passed, exit `0`; all four PASS messages were produced. This
proves that the approved clause-order replacement is the only
security-policy change and that support is unchanged.
Compact direct-link command:
```powershell
'.github\SECURITY.md', '.github\CODE_OF_CONDUCT.md', '.github\CONTRIBUTING.md' | ForEach-Object { if (-not (Test-Path -LiteralPath $_ -PathType Leaf)) { throw "Missing link target: $_" }; "PASS: $_" }; Select-String -LiteralPath '.github\SECURITY.md', '.github\SUPPORT.md' -Pattern '\[[^\]]+\]\([^)]+\)'
```
Result: passed, exit `0`; three relative targets exist and all five
original links are listed. The full link/heading comparison in the issue
record also passed, exit `0`.
| Exact command | Result |
| --- | --- |
| `git --no-pager diff --check
0c67251..HEAD` | Passed, exit `0`. |
| `git --no-pager diff --cached --check` | Passed before commit, exit
`0`. |
| `git --no-pager diff --exit-code
0c67251 -- .github\SUPPORT.md` |
Passed, exit `0`; no support diff. |
| `git hash-object .github\SUPPORT.md` | Matched the baseline support
blob above. |
| `gh api
repos/MSXOrg/.github/commits/a45e33912b4fc594e090dd291271946ed6ce9dcb/check-runs
--jq '{total_count, check_runs: [.check_runs[] \| {name, status,
conclusion}]}'` | Succeeded; the final snapshot contains one completed,
successful `copilot-pull-request-reviewer` check. This is not a
Markdown/link CI result. |
This base has no Markdown/link validation scripts, linter configuration,
package manifest, or workflow. No checks from unmerged #12
are installed or claimed. The successful review check does not fill that
separate readiness gap. No linter, dependency, validation file, or
release metadata is added.
### Alignment and plan progress
| Changed surface | Standards checked | Framework docs checked | Result
|
| --- | --- | --- | --- |
| `.github/SECURITY.md` | Pinned MSX documentation, natural-language,
Markdown, implementation, and PR guidance; official Issue 9 rule 5.4 |
None (no framework-specific docs); GitHub private-reporting behavior
checked | Fixed in this PR |
Source review, pre-edit evidence, implementation, full-policy
comparison, direct link verification, whitespace checks, and direct
self-review are complete. The issue plan is updated as those steps
finish. The draft was opened after the first small commit. The native
Task has no blocked-by edges or recorded parent.
Scoped convergence searches used `gh issue list --repo MSXOrg/.github
--state open --search '"SECURITY.md" in:body' --limit 30 --json
number,title,body,url` and the same command with `"SUPPORT.md"`. Each
returned only #18. No other issue converges or is added to
the closing references.
A review was explicitly requested with `gh pr edit 19 --repo
MSXOrg/.github --add-reviewer '@copilot'`; the request succeeded. The
[submitted
review](#19 (review))
is `APPROVED` at candidate `a45e33912b4fc594e090dd291271946ed6ce9dcb`,
with no inline comments or open review issues. An independent acceptance
review at the same candidate also found no blocking scope or policy
issue. The final metadata check confirms that every original PR-template
comment and heading is preserved in order, and that only the delivery
leaf is closed by this PR.
**HISTORICAL - original draft-delivery checkpoint:** This PR was left in
draft; no merge, auto-merge, or Agent merge action was taken. No
implementation blocker remained for that reviewed-draft handoff; hosted
Markdown/link CI was unavailable. **Current lifecycle:** This PR is open
and ready for review. Maintenance Agent merge is enabled with
`merge_pr=false`, and GitHub auto-merge is off. The user directs merges
as changes become ready, subject to root's not-yet-granted exclusive
global merge slot and the normal protected exact-head and native
prerequisites. Do not merge until that slot is granted and those
prerequisites are met. Hosted Markdown/link CI remains unavailable, not
passed.
</details>
<details>
<summary>Relevant issues (or links)</summary>
<!-- Use fully qualified repository references for closing and related
work. -->
Resolves#18.
References #12 for the separate validation work; its
unmerged files are not part of this PR.
</details>
<!-- Lead with one concise paragraph describing the user-facing outcome.
-->
The public MSX profile identifies the shared guidance and GitHub
community-default context. The agent entry point describes its source
documents without an enforcement claim.
<!-- ANNOUNCEMENT STOP -->
<!-- Add user-facing sections for breaking, new, changed, or fixed
behavior when needed. -->
## Changed: Entry points describe their linked guidance
The profile links MSX documentation and the community-defaults
repository. Agent instructions keep the README-then-CONTRIBUTING
sequence and describe what those files contain. The brand heading and
both wrapper routes remain unchanged. No reader or agent configuration
change is required.
---
<details>
<summary>Technical details</summary>
<!-- Record the implementation approach, issue-plan progress, standards
alignment, and convergence sweep. -->
**Scope and persistent source**
The comparison is
`0c67251812ea306543f3a14ab473ae357cfb76ac...e90ab70`.
The PR contains only `profile/README.md` and `AGENTS.md`: nine added
lines and two removed lines. The worktree is clean.
Three small commits retain the implementation sequence:
- `ce0a2f3c7646fcbe4d06cb0fa5c857034ba164eb`: add profile context and
links; open this draft before the agent edit.
- `5b6191d042d48503124cdfcad9a062182be546db`: correct both agent
read-order descriptions.
- `e90ab70966ccfa12f7c20a486fb40f5846062c9a`: use `file of that type`
for the default-file explanation after the source-vocabulary review.
The root README, contribution guide, PR template, forms, and
SECURITY/SUPPORT policies are not changed. Root README audience
clarification remains with its existing owner. No tooling, dependency,
generated output, or documentation structure is added.
**Source and factual review**
The fixed authority is MSXOrg/docs commit
`1b0d4893c8fefabe604d04393068a8ff6f848082`, under `src/docs/`. The
source review covers Documentation Model, Natural Language, Writing
Guide, Markdown, Documentation, README-Driven Context, and the
applicable workflow, contribution, PR, commit, branching, and completion
guidance.
| Changed statement | Verified evidence |
| --- | --- |
| MSX documentation contains shared standards and ways of working for
humans and agents. | The pinned [MSX home
page](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/index.md),
especially its scope and documentation map. |
| The community-defaults repository contains shared GitHub files; GitHub
uses a default when a repository has no file of that type. | The
[baseline root
README](https://github.com/MSXOrg/.github/blob/0c67251812ea306543f3a14ab473ae357cfb76ac/README.md)
and actual tracked community files. |
| The root README covers community defaults, MSX documentation, and
shared media. | The same baseline README, inspected in the worktree and
through GitHub. |
| CONTRIBUTING links MSX contribution guidance. | The [baseline
contribution
guide](https://github.com/MSXOrg/.github/blob/0c67251812ea306543f3a14ab473ae357cfb76ac/.github/CONTRIBUTING.md),
which points to central MSX documentation. |
The [official STE
description](https://www.asd-ste100.org/about_STE.html),
[FAQ](https://www.asd-ste100.org/STE_faq.html), and [Issue 9 DOI
record](https://doi.org/10.5281/zenodo.23666006) are available. The
local Issue 9 PDF has MD5 `9c720341c350ed77943b2c73d01c716f`, which
matches the official record. The review uses the relevant verb,
instruction, descriptive-writing, and dictionary guidance. The manual
and extraction remain local.
The added prose uses en-US, present tense, active voice, and short
sentences. Its plain-text sentence lengths are 14, 8, and 15 words.
`Read in this order:` remains imperative. `Ways of working` retains the
source's technical term. The existing slogan is an accepted branding
difference, not a claimed STE-compliant technical statement. Neither
these checks nor a word count establish full STE conformance.
All required pinned MSX and official STE sources are available. The
custom instruction's literal parent `..\AGENTS.md` path is absent. The
repository root `AGENTS.md` is available, was read, and is the verified
destination of both actual wrappers. No source or access blocker
prevents this delivery.
**Before and after acceptance evidence**
[The pre-edit
record](#17 (comment))
retains the baseline failures. The same 12 acceptance checks return
seven passes and five expected failures before editing, then 12 passes
and no failures after editing. The final wording is included in the
passing run.
| Check | Before | After |
| --- | --- | --- |
| Profile orientation | Missing; only the slogan exists. | Shared
guidance and its human/agent audience are stated. |
| Canonical documentation link | Missing. | `https://msx.no/docs/` is
present and returns HTTP 200. |
| Community-default context and link | Missing. | The repository link
and default-file explanation are present; the link returns HTTP 200. |
| README description | Claims that the README describes enforcement. |
Describes community defaults, MSX documentation, and shared media. |
| Contribution-guide description | Claims that the guide describes
change and review steps. | Describes the link to MSX contribution
guidance. |
| Remaining seven route/format/no-change checks | Pass. | Pass without
changing the instructions, headings, targets, or protected files. |
The exact read order remains `README.md`, then
`.github/CONTRIBUTING.md`. Both target files exist. Both H1 texts are
identical to the baseline, so their existing heading anchors remain
stable. No heading or fragment is added.
| No-change wrapper | Exact syntax | Resolved target |
| --- | --- | --- |
| `.claude/CLAUDE.md` | `@../AGENTS.md` | Root `AGENTS.md` |
| `.github/copilot-instructions.md` | `Follow the instructions in
[AGENTS.md](../AGENTS.md).` | Root `AGENTS.md` |
**Exact acceptance check**
This PowerShell block was run before and after the edit. The baseline
exits `1` with five expected failures. The final source exits `0` with
`12/12 passed; 0 failed`. The text assertions verify explicit content
and invariant routes; the source table above supplies the factual
review.
```powershell
$baseline = '0c67251812ea306543f3a14ab473ae357cfb76ac'
$profile = Get-Content -LiteralPath 'profile\README.md' -Raw
$agents = Get-Content -LiteralPath 'AGENTS.md' -Raw
$readOrder = @([regex]::Matches($agents, '(?m)^\d+\. \[[^\]]+\]\(([^)]+)\)') | ForEach-Object { $_.Groups[1].Value })
$profileHeading = [regex]::Match($profile, '(?m)^# .+').Value.TrimEnd()
$baselineProfileHeading = (git show "${baseline}:profile/README.md" | Select-Object -First 1).TrimEnd()
$agentHeading = [regex]::Match($agents, '(?m)^# .+').Value.TrimEnd()
$baselineAgentHeading = (git show "${baseline}:AGENTS.md" | Select-Object -First 1).TrimEnd()
git diff --quiet $baseline -- README.md .github\CONTRIBUTING.md .github\pull_request_template.md .claude\CLAUDE.md .github\copilot-instructions.md
$protectedFilesUnchanged = $LASTEXITCODE -eq 0
$agentPath = (Resolve-Path -LiteralPath 'AGENTS.md').Path
$checks = [ordered]@{
ProfileOrientation = ($profile -match 'shared standards' -and $profile -match 'ways\s+of working' -and $profile -match '(humans|people) and agents')
CanonicalDocumentationLink = $profile.Contains('https://msx.no/docs/')
CommunityDefaultContext = ($profile.Contains('https://github.com/MSXOrg/.github') -and $profile -match 'GitHub uses a default file')
NoEnforcementClaim = $agents -notmatch '\benforc'
ContributionPointerDescription = ($agents -match 'link to MSX contribution guidance' -and $agents -notmatch 'made and reviewed')
ExactReadOrder = (($readOrder -join '|') -ceq 'README.md|.github/CONTRIBUTING.md')
ReadTargetsResolve = ((Test-Path -LiteralPath 'README.md' -PathType Leaf) -and (Test-Path -LiteralPath '.github\CONTRIBUTING.md' -PathType Leaf))
ImperativeInstruction = $agents.Contains('Read in this order:')
HeadingStability = ($profileHeading -ceq $baselineProfileHeading -and $agentHeading -ceq $baselineAgentHeading)
ThinPointerSyntax = ((Get-Content -LiteralPath '.claude\CLAUDE.md' -Raw).Trim() -ceq '@../AGENTS.md' -and (Get-Content -LiteralPath '.github\copilot-instructions.md' -Raw).Trim() -ceq 'Follow the instructions in [AGENTS.md](../AGENTS.md).')
WrapperResolution = ((Resolve-Path -LiteralPath '.claude\..\AGENTS.md').Path -ceq $agentPath -and (Resolve-Path -LiteralPath '.github\..\AGENTS.md').Path -ceq $agentPath)
ProtectedFilesUnchanged = $protectedFilesUnchanged
}
$checks.GetEnumerator() | ForEach-Object { '{0}: {1}' -f $_.Key, $(if ($_.Value) { 'PASS' } else { 'FAIL' }) }
$failed = @($checks.Values | Where-Object { -not $_ }).Count
'{0}/{1} passed; {2} failed' -f ($checks.Count - $failed), $checks.Count, $failed
if ($failed -gt 0) { exit 1 }
```
**Other checks and results**
| Exact command | Result |
| --- | --- |
| `git diff --check 0c67251` | Passed
after both edits and after the final wording change. |
| `git diff --cached --check` | Passed before each of the three commits.
|
| `git diff --check 0c67251...HEAD` |
Passed for final commit `e90ab70966ccfa12f7c20a486fb40f5846062c9a`. |
| `git diff --name-only 0c67251` |
Returned exactly `AGENTS.md` and `profile/README.md`. |
| `git diff --exit-code 0c67251...HEAD
-- .claude\CLAUDE.md .github\copilot-instructions.md README.md
.github\CONTRIBUTING.md .github\pull_request_template.md` | Passed with
no diff. |
| `curl.exe --fail --location --silent --show-error --max-time 60
--output NUL --write-out 'HTTP %{http_code}; URL %{url_effective}\n'
'https://msx.no/docs/'` | Passed; HTTP 200 at that canonical URL. |
| `curl.exe --fail --location --silent --show-error --max-time 60
--output NUL --write-out 'HTTP %{http_code}; URL %{url_effective}\n'
'https://github.com/MSXOrg/.github'` | Passed; HTTP 200 at that
repository URL. |
| `git --no-pager status --short` | Passed with no output; the worktree
is clean. |
Both HTTP destinations were also read to confirm the expected content,
not only a successful status. The profile uses an absolute repository
link so it reaches the same context from both the organization profile
and the repository view.
The following GitHub GFM render commands succeed for the final source.
Shape assertions confirm one H1, two paragraphs, and two canonical links
for the profile; one H1 and one two-step ordered list for `AGENTS.md`.
The wrapper-resolution command returns the same root `AGENTS.md` for
both paths.
```powershell
$profile = Get-Content -LiteralPath 'profile\README.md' -Raw
$profileHtml = (@{ text = $profile; mode = 'gfm'; context = 'MSXOrg/.github' } | ConvertTo-Json -Compress | gh api --method POST markdown --input -) -join "`n"
$agents = Get-Content -LiteralPath 'AGENTS.md' -Raw
$agentsHtml = (@{ text = $agents; mode = 'gfm'; context = 'MSXOrg/.github' } | ConvertTo-Json -Compress | gh api --method POST markdown --input -) -join "`n"
Resolve-Path -LiteralPath '.claude\..\AGENTS.md', '.github\..\AGENTS.md' | Select-Object -ExpandProperty Path
```
Markdown/link lint was **not run**: the baseline has no corresponding
scripts, shared Markdown configuration, package manifest, or workflow
directory. The availability probe finds no installed
`markdownlint-cli2`, `markdownlint`, or `pymarkdown` command. No
dependency is installed. Unmerged #12 is not treated as
installed or enforced validation.
```powershell
foreach ($name in @('markdownlint-cli2', 'markdownlint', 'pymarkdown')) { $command = Get-Command -Name $name -ErrorAction SilentlyContinue; if ($null -eq $command) { '{0}: unavailable' -f $name } else { '{0}: {1}' -f $name, $command.Source } }
git ls-files -- '*.ps1' '.github/workflows/*' '*markdownlint*' '*markdown-lint*' 'package.json' 'pyproject.toml'
```
The probe reports all three commands unavailable. The tracked-file query
returns no matches. The local/manual checks above are evidence for this
delivery, not installed CI enforcement.
**Standards and framework alignment**
The final pass checks the applicable pinned process and writing sources
against the whole diff. No mission, guarantee, policy, enforcement
mechanism, or response promise is added.
| Changed surface | Standards checked | Framework docs checked | Result
|
| --- | --- | --- | --- |
| `profile/README.md` | Documentation Model, Natural Language, Writing
Guide, Markdown, Documentation, README-Driven Context; relevant Issue 9
rules | None (no framework-specific docs). Facts match the pinned MSX
home page and repository README. | Aligned; the brand heading is the
accepted branding difference in the delivery leaf. |
| `AGENTS.md` | Natural Language, Writing Guide, Markdown; ordered and
verifiable agent instructions | None (no framework-specific docs).
Descriptions match README and CONTRIBUTING. | Fixed in this PR; exact
instruction order and paths are preserved. |
**Convergence, plan, and review**
The scoped convergence command is:
```powershell
gh issue list --repo MSXOrg/.github --state open --search 'documentation-writing-alignment in:title' --limit 25 --json number,title,body,url
```
It returns delivery leaves #16, #17, and
#18. The two-file diff satisfies only #17.
The form and reporting-policy asks are not satisfied by this change, so
no additional closing reference is added. The native blocked-by query
returns an empty list.
The issue plan records source review, small commits, early draft
creation, factual and route checks, and validation evidence. This PR
carries the final alignment, convergence, and review record.
The explicit command `gh pr edit 20 --repo MSXOrg/.github --add-reviewer
'@copilot'` succeeds after the final push. The [final-source
review](#20 (review))
is **APPROVED** for `e90ab70966ccfa12f7c20a486fb40f5846062c9a`, with
zero inline comments and no active review issues. Its remote review
check completed with `success`. This is a review result, not a
Markdown/link CI result.
**Historical original draft-delivery checkpoint:** The PR was open and
draft, assigned to its author. GitHub auto-merge was `null`; Agent merge
was disabled and its merge action was false. No merge or
merge-automation change was made at that checkpoint. **Current
lifecycle:** The PR is open and ready for review. Maintenance Agent
merge is enabled with `merge_pr=false`; GitHub auto-merge remains
`null`. The user's direction is to merge changes as they are ready. The
exclusive global merge slot is not yet granted. Merge remains on hold
until root grants that slot and normal protected exact-head and native
prerequisites are met. The repository has no versioned producer route in
this source tree, so no release decision block or release label is
added.
</details>
<details>
<summary>Relevant issues (or links)</summary>
<!-- Use fully qualified repository references for closing and related
work. -->
Resolves#17.
References
[#12](#12) for the
separate, unmerged Markdown validation work. Its check is not installed
on this PR's baseline.
</details>
<!-- Lead with one concise paragraph describing the user-facing outcome.
-->
The bug, patch, and general issue forms name the information that
reporters give. Their prompts use direct instructions without filler or
a promise of a fast response. Existing fields and submission
requirements do not change.
<!-- ANNOUNCEMENT STOP -->
<!-- Add user-facing sections for breaking, new, changed, or fixed
behavior when needed. -->
## Changed: Issue forms use direct input instructions
The bug form identifies expected and actual behavior, the environment,
reproduction steps, related information, and evidence. The patch form
asks for the existing content or behavior and the desired change. The
general form asks for the issue subject and related information.
All three forms retain their names, titles, labels, field IDs, field
order, types, and required flags. The bug form keeps three required and
two optional textareas. The patch and general forms each keep one
required textarea. Repositories that use these shared forms need no
configuration change.
---
<details>
<summary>Technical details</summary>
<!-- Record the implementation approach, issue-plan progress, standards
alignment, and convergence sweep. -->
**Source and plan:** Fresh preparation on 2026-11-11 verifies head
`deb2e80d65c1334a140c2f8c15eae738329542fb` against live `main` base and
merge base `0c67251812ea306543f3a14ab473ae357cfb76ac`. Remote refs
match. No source changes occur during this preparation; the worktree is
clean. The draft opened after bug-form commit
`e3e59ac00134eaec301506e2f01492d90faead9b`; the second small commit
completes patch and general intake. All five delivery-plan steps are
complete. #16 stays open until merge.
**Before and after:** All three introductions asked for "as much
information as possible" and promised quick help. Each now states the
information its form records. The field wording also becomes specific:
| Field | Before | After |
| --- | --- | --- |
| Bug description | A clear and concise description of what the bug is
vs. what you expected to happen. | Give the expected behavior and the
actual behavior. |
| Bug environment | What version, commit, platform, or configuration
were you using when the problem occurred? | Give the version, commit,
platform, or configuration in use when the problem occurred. |
| Patch description | A clear and concise description of what you would
want to change. | Give the existing content or behavior and the change
you want. |
| General description | A clear and concise description. | Give the
subject of the issue and the related information. |
The original pre-edit, one-time wording checks reported 3 values passing
and 7 failing; all 10 passed after implementation. Fresh manual review
covers all three forms, all 10 changed prose values, and the complete
diff. It confirms the accepted requested-information meaning and direct
en-US instructions. The environment prompt retains `or`; it does not
require every listed environment value. No content decision remains.
**Fresh lint provenance:** This repository has no YAML lint
configuration or installed hosted validation. Both fixed MSX docs source
`1b0d4893c8fefabe604d04393068a8ff6f848082` and current source
`f9b335d0b78a3eead0b7efa573936e86cb1e7265` use Docs workflow blob
`de01a42b4c230de8b2c7540089cc15b945529a5b`, with super-linter
`4ce20838b8ab83717e78138c5b3a1407148e0918` and no YAML override. Its
[published default
configuration](https://github.com/super-linter/super-linter/blob/4ce20838b8ab83717e78138c5b3a1407148e0918/TEMPLATES/.yaml-lint.yml),
blob `2aa49bd1867e24acdea4172191922df6135b69c6`, is saved unmodified
outside source. Its [dependency
pin](https://github.com/super-linter/super-linter/blob/4ce20838b8ab83717e78138c5b3a1407148e0918/dependencies/python/yamllint.txt),
blob `7ce0eabce1e3283119086a7ae179f2373fc00e13`, matches installed
yamllint 1.38.0. This is a pinned shared-validator default for local
checks, not this repository's CI configuration. The installed default
also matches upstream commit `cba56bcde1fdd01c1deb3f945e69764c291a6530`,
blob `b082e228469dd5909a6f58dd2466882e16d4ea87`.
For each of the three base blobs and corresponding candidate files, the
exact commands receive the original input bytes through stdin:
```powershell
$shared = "$env:USERPROFILE\.copilot\session-state\73d907e5-c9b5-46c2-ab63-6404c149f36f\files\super-linter-4ce20838-yaml-default.yml"
python -m yamllint --config-file $shared -
python -m yamllint --strict --config-file $shared -
python -m yamllint --strict --config-data 'extends: default' -
```
| Fresh verification | Result |
| --- | --- |
| Pinned shared-validator default, normal and strict | All 3 base and
all 3 candidate files pass in both modes: 12 runs, exit 0, zero
diagnostics. No published rule is weakened. |
| Explicit installed default, strict | All 3 base and all 3 candidate
files pass: 6 runs, exit 0, zero diagnostics. |
| PyYAML 6.0.3 complete contract comparison | All 3 actual-base
contracts match across 28 mappings, 6 sequences, and 122 scalar nodes.
Exactly 10 prose values differ; all 112 other scalar nodes, key/field
order, tags, styles, and comments are preserved. |
| Full input and routing contract | All 7 textarea IDs, types, labels,
and required flags match: 5 required and 2 optional. Form names, titles,
top-level descriptions, labels, and routing match. |
| `git diff --check` | Passed, exit 0. |
| `git diff
0c67251...deb2e80
--check` | Passed, exit 0. |
| `git diff --name-only
0c67251...deb2e80`
| Exactly the three owned forms: `01-bug.yml`, `02-patch.yml`, and
`99-general.yml`, under `.github/ISSUE_TEMPLATE`. |
**Native rendering and links:** `gh api --include --method POST markdown
-H 'Accept: text/html' --input -` sends each parsed introduction to
GitHub with JSON `mode: gfm` and `context: MSXOrg/.github`. All 6
requests, covering 3 baseline and 3 candidate introductions, return HTTP
200. Each renders as one paragraph with complete visible text. The
candidate bug and general introductions each contain one native `<br>`;
patch has none. This is real Markdown rendering, not a simulated form or
an issue-submission test. All 48 scalar string values across the
candidate forms contain zero link targets, and native output contains
zero links or images. Link verification is inapplicable, not a passing
empty scan.
**Standards and scope:** The writing review uses the fixed MSX
Documentation Model, Natural Language, Writing Guide, Markdown,
Documentation, YAML, Testing, and applicable delivery guidance. The
[Writing
Guide](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Writing-Guide.md),
official STE overview/FAQ, and locally verified Issue 9 support the
review without a full STE-conformance claim. The native issue-form
format remains intact.
| Changed surface | Standards checked | Framework docs checked | Result
|
| --- | --- | --- | --- |
| `.github/ISSUE_TEMPLATE/01-bug.yml` | Direct en-US prompts, preserved
meaning, YAML | Native GitHub issue-form format | Fixed in this PR |
| `.github/ISSUE_TEMPLATE/02-patch.yml` | Direct en-US prompts,
preserved meaning, YAML | Native GitHub issue-form format | Fixed in
this PR |
| `.github/ISSUE_TEMPLATE/99-general.yml` | Direct en-US prompts,
preserved meaning, YAML | Native GitHub issue-form format | Fixed in
this PR |
The feature form, `config.yml`, tests, validation tooling, README,
contribution guidance, PR template, agent instructions, profile,
security, and support files remain unchanged. The repository's fallback
role and central-standards link remain correct. No maintained
phrase/snapshot test, linter, dependency, workflow, label, ruleset,
scheduler, or policy change is added. The original scoped convergence
sweep found #16 and feature Task #14; the
latter is not satisfied by this diff. Only #16 receives a
closing reference.
**Current reviews and protections:** The [current-head Copilot
approval](#21 (review))
remains `APPROVED`. Fully paginated inspection finds zero inline
comments, zero review threads, and no new PR comments. GitHub reports
`APPROVED`, `MERGEABLE`, and `CLEAN`. `gh pr checks` reports no checks;
the exact-head REST endpoint retains one successful historical review
check and zero commit statuses. No hosted repository-validation result
exists; the review check is not one.
Inherited active ruleset `19735160` requires squash-only PRs,
stale-review dismissal, code-owner review, last-push approval, extra
approval for unattributed changes, and thread resolution. No
required-status-check rule is present. The classic protection endpoint's
HTTP 404 does not remove these rules. No `CODEOWNERS` file exists at a
supported location in the actual base. Copilot is the only approving
account and its collaborator-permission response is `none`; native
readiness metadata is not used as proof of an independently eligible
last-push approval or as permission to bypass protection.
**Lifecycle:** The PR is open and non-draft under the later
user-directed lifecycle change. GitHub auto-merge is null. Agent merge
readback is enabled with `merge_pr=false`. The exclusive global merge
slot remains with the root coordinator; no merge is attempted. Missing
hosted CI remains disclosed. Operational exact-head local evidence does
not install CI or waive an actual failing check.
The [fresh issue
evidence](#16 (comment))
records the exact provenance, commands, results, and remaining
authorization boundary. Full diagnostics, configuration bytes,
ordered-tree comparison, and native HTML responses remain in local
session artifacts, not in the repository. There is no source or access
blocker.
</details>
<details>
<summary>Relevant issues (or links)</summary>
<!-- Use fully qualified repository references for closing and related
work. -->
- Resolves#16
- References #12 for separate validation work, not an
installed check or dependency.
- References #15 for the separately owned feature form.
</details>
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
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.
Contributors to
MSXOrg/.githubreceive a named, read-only check for applicable source changes, including Markdown-only updates and PRs retargeted tomain. PR descriptions use canonical guidance only; this validator does not require, copy, generate, or compare a PR template. Ordinary repositories need no validator installation or copied policy files.Fixed: Changed source files receive complete, source-bound validation
Correct reported Markdown violations even if a file contains a markdownlint disable/configuration directive. Every selected
.mdfile is read literally and linted with unchanged shared rules andnoInlineConfig: truefrom an isolated temporary configuration. Inline directives, local ignores/configuration, and glob-like filenames cannot hide selected Markdown; valid directive examples still pass. Explicitopened,synchronize,reopened, andeditedactivities cover updates and retargeting tomainwithout a new commit.Use PowerShell 7.4+, Git, and Node.js/npm in this source repository. Fetch the intended base and commit the content being checked. The native runner discovers
.github/testswithout a Path override, and CI exercises that default. Pinned tooling is restored when needed:Intentional template absence/deletion is valid. Removed paths come from the committed diff with case-sensitive identity and are not counted as linted content. Empty/unsupported-only inputs and zero-file Markdown scans fail. Test discovery cannot pass when no test passes, including skipped-only suites; summary and exit use the same success condition. The obsolete scaffold fixture/comparison is removed, not replaced.
Absence is not record-quality proof. Actual titles/descriptions still need canonical PR Format's boundary, ordered results, complete consumer actions, scoped evidence, and release decisions only on applicable release-managed routes. Other defaults and product-integration templates are distinct. #8 owns central removal at
990bfcbfd1275f80d58b3a9c51781f3873e22876; this PR does not edit its paths, forms, consumer copies, hooks, release contracts, or live governance.Technical details
Verified head:
a6c4484fa197f44bf45e244e17480cb40deafd3e, merge base0c67251812ea306543f3a14ab473ae357cfb76ac. Run 41248565958 completed successfully at this exact head. Its job/check completed actual-head/source validation, literal Markdown lint, all 44 tests, and the remaining PowerShell/YAML/Actions/security routes. The earlier cancelled run is not used as validation evidence.Exact check/source:
Organization defaults validation, GitHub Actions integration/app15368, from.github/workflows/Organization-Defaults-Validation.yml. Default-deny permissions, only contents read, actual-head verification, and disabled persisted credentials/language-status writes/PR-summary comments are preserved. Literal Markdown precedes other include-only Super-Linter routes. No publication, tag/label mutation, rules/access change, merge, or auto-merge was performed..github/testsdefault, anonymous/full default invocation, and CI default execution passEvery listed defect was demonstrated before correction. All 44 local and hosted tests pass in two suites, with zero failed/skipped/not-run tests. Source/head/containment, nonempty checks, literal paths, valid examples, links, staged/unstaged consistency, and control/backslash/finder-pruned guards remain intact.
.github/VALIDATION.mdDeletion-only anonymous inputs report one checked deletion and zero linted Markdown, verify sources, and skip only inapplicable other-language lint. This is not an empty-input or Markdown pass. The isolated skipped-only suite is rejected and its summary is failure, not executed-regression proof.
#8 compatibility: Actual head
990bfcbfd1275f80d58b3a9c51781f3873e22876versus base0c67251812ea306543f3a14ab473ae357cfb76acchanges only two guides and central deletion. Both changed contents pass this literal/no-inline checker. The complete inventory has 42 files and zero PR templates. This is local source compatibility, not a hosted #8 check, record-quality approval, or merged-deletion claim; its checkout was untouched.pwsh -NoProfile -File .github\scripts\Invoke-PesterSuite.ps1 -RequiredVersion 6.1.0pwsh -NoProfile -File .github\scripts\Test-OrganizationDefaults.ps1 -BaseRevision origin/main -ExpectedHead (git rev-parse HEAD)Invoke-ScriptAnalyzer -Path .github -Recurse -Settings .github\linters\.powershell-psscriptanalyzer.psd1.github\workflows\Organization-Defaults-Validation.ymlyamllint -c .github\linters\.yaml-lint.yml .github\workflows\Organization-Defaults-Validation.ymlzizmor --offline --no-progress -c .github\linters\zizmor.yml .github\workflows\Organization-Defaults-Validation.ymlgit --no-pager diff --check origin/main...HEADMetadata pins configuration Git blobs from MSXOrg/docs
36da9154aa55d2052345fb2f28b812b29daf8bc9and Super-Linter4ce20838b8ab83717e78138c5b3a1407148e0918, not a scaffold fingerprint. The shared Pester helper has the documented source-local default and unified real-success adaptations. External SHA pins and permissions are unchanged.Ownership: Repository Standard owns no-file policy; PR Format owns record quality. This ready, unmerged source is authoring context, not a runtime dependency. Absence does not certify coverage, actions, markers, sections, or evidence.
Complete review disposition: The exact-head review completed with no new inline findings; all nine threads are resolved and pagination completed. The entire summary was read. Its remaining concern cited a superseded cancelled CI run; the newer completed actual-head run above independently resolves that evidence gap. No zero-inline count was used to dismiss code or summary concerns. Every actionable finding in this work was reproduced and corrected.
Plan/convergence: Seven ordinary commits complete the user-directed no-template revision, demonstrated Markdown/retarget fixes, and tightly coupled full-review corrections. #11 closes through this PR; #8/#10 and the hook follow-up remain separate. No forms, consumer copies, release signals, or live check requirements are changed.
Operational state: The repository owner externally marked this PR ready at 22:38:19Z; this session did not change readiness. Independent native read-back confirms Agent merge maintenance enabled, review/CI/conflict actions enabled,
merge_pr=false, and GitHubautoMergeRequest=null. No merge or enqueue was performed. Inherited main rules still name no required status checks: requiring exactlyOrganization defaults validationfrom GitHub Actions/app15368remains a separately unapproved governance action. The visible ready state does not waive that governance boundary. This source route delivers public community files, not versioned artifacts, so no release-decision block or release label applies.Related references