docs: resolve markdownlint issues and finalize workflows

- Fix .markdownlint.jsonc configuration structure
- Clean up .github/CodeQL-README.md formatting
- Resolve repo-wide markdownlint issues (MD001, MD012, MD024, MD060, etc.)
- Add 'md' file type detection to detect-relevant-changes action
- Enable workflow_call support in markdown-fix.yaml
- Pin actions to SHAs with full semantic version annotations (e.g., # v1.1.0)
- Support @<repo>bot format command in markdown-fix.yaml

Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com>

Author: google-labs-jules[bot]

.github/CodeQL-README.md

@@ -1,4 +1,3 @@
-```markdown
 # CodeQL scanning for this repository
 
 This repository uses C++ (C++20 / moving to C++23) built with CMake under the phlex-src directory, plus some Python and CI bits (Bash). The repository includes a CodeQL GitHub Actions workflow on branch `copilot/codeql-workflow` that:
@@ -9,22 +8,26 @@ This repository uses C++ (C++20 / moving to C++23) built with CMake under the ph
 - Uses RelWithDebInfo build type in CI so debug symbols are present while keeping realistic optimization.
 
 Important workflow-specific notes
+
 - The workflow sets `autobuild: false` during the CodeQL init so the repository's own configure / build steps run. This is intentional: the Phlex build actions are used to build exactly what you ship.
 - The workflow tries to locate and copy a compile_commands.json (from `phlex-src/build/` or `phlex-build/`) to the workspace root so diagnostic tools and manual inspection have a predictable path.
 - The workflow runs inside the repository container image (if provided) so it uses the same toolchain and environment your CI expects.
 
 How the workflow is targeted at phlex-src
+
 - The CMake configure & build steps are run with `-S phlex-src -B phlex-src/build` (or your Phlex-specific helpers are invoked in that context) so compile units, compiler flags, and generated compile_commands reference files under `phlex-src`.
 - The CodeQL config (`.github/codeql/codeql-config.yml`) contains an explicit `paths.include: - phlex-src/**` entry and excludes common vendor/build directories. This ensures CodeQL focuses on the intended code and not third-party or generated artifacts.
 
 Recommended build type for CodeQL runs
+
 - Use RelWithDebInfo (the workflow is already set to use this). Rationale:
   - RelWithDebInfo produces debug symbols (required for better mapping of findings to source/stack traces) while compiling with optimizations closer to production.
   - Pure Debug (-O0 -g) can be used for local triage of tricky alerts but is slower and sometimes produces analysis results that differ from optimized builds.
   - Release (no debug info) is not recommended for CodeQL because missing debug symbols reduce the quality of evidence and traces in findings.
 
 How to run CodeQL locally (examples)
-1. Install the CodeQL CLI: https://codeql.github.com/docs/codeql-cli/getting-started/
+
+1. Install the CodeQL CLI: <https://codeql.github.com/docs/codeql-cli/getting-started/>
 2. Create a C++ database for the phlex-src tree (example):
    - From repository root:
      codeql database create codeql-db --language=cpp --command="cmake -S phlex-src -B phlex-src/build -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_EXPORT_COMPILE_COMMANDS=ON && cmake --build phlex-src/build -- -j$(nproc)"
@@ -36,17 +39,20 @@ How to run CodeQL locally (examples)
 5. Open the SARIF in VS Code via the CodeQL extension or upload results via the GitHub UI.
 
 Triage tips and workflows
+
 - Start with high-confidence, high-severity alerts.
 - Use the evidence shown in the CodeQL alert to locate the vulnerable trace. RelWithDebInfo gives better evidence than Release.
 - When marking false positives, add a short rationale in the Code Scanning UI (this helps future auditors).
 - If the repo has many historical findings, consider a triage sprint to baseline or create a SARIF baseline to ignore existing alerts temporarily while blocking new ones.
 
 How to add or change query packs
+
 - The repository currently selects the language security-and-quality packs for C++ and Python. That is a good default.
 - If you want to add additional packs (experimental or specialized) you can:
   - Edit `.github/codeql/codeql-config.yml` and add additional packs there (use the canonical pack name), or
   - Add them to the init step in the workflow (`with: queries:`).
 - Example of adding packs in the workflow init:
+
   ```yaml
   uses: github/codeql-action/init@v4
   with:
@@ -59,12 +65,14 @@ How to add or change query packs
   ```
 
 Action-specific / workflow scanning
+
 - There are CodeQL query packs that specifically analyze GitHub Actions workflow files (YAML) to find insecure patterns (for example: unsafe use of secrets, untrusted inputs in workflow run steps, usage of unpinned actions, etc.). If you rely on custom workflows or pass secrets/inputs to actions, consider enabling the GitHub Actions query pack if it is available in your CodeQL pack index.
 - To discover whether an official GitHub Actions pack exists or to find its exact name, see the CodeQL packs index (the canonical source) or search the public CodeQL repository:
-  - https://github.com/github/codeql/tree/main/packs
+  - <https://github.com/github/codeql/tree/main/packs>
   - Search for "github-actions" or "actions" in the CodeQL repo to find action-related packs and their exact pack names.
 
 Recommended query packs for this repository (starting point)
+
 - github/codeql/cpp-security-and-quality
   - Purpose: Core security and quality queries for C and C++ codebases. Good coverage of common memory safety, API misuse, and typical C/C++ pitfalls.
   - Why: Phlex is primarily C++, so this pack is the most important starting point.
@@ -73,6 +81,7 @@ Recommended query packs for this repository (starting point)
   - Why: Phlex contains some Python; include this pack so those files are analyzed.
 
 Other useful pack categories to consider
+
 - Language experimental packs (e.g., "cpp-experimental" / "python-experimental")
   - These provide newer/experimental queries that are not yet in the stable security-and-quality pack. Use cautiously: they can produce more findings and more false positives.
 - Action/workflow packs (GitHub Actions specific)
@@ -81,15 +90,17 @@ Other useful pack categories to consider
   - If Phlex heavily uses a certain third-party library that has its own pack, consider enabling it to get library-specific rules.
 
 How to find the exact pack names and descriptions
+
 - Official source: the GitHub CodeQL packs and QL repos:
-  - https://github.com/github/codeql/tree/main/packs
-  - https://github.com/github/codeql/tree/main/ql
+  - <https://github.com/github/codeql/tree/main/packs>
+  - <https://github.com/github/codeql/tree/main/ql>
 - CodeQL CLI (partial support for pack discovery):
   - You can use `codeql pack` and `codeql resolve` commands to inspect installed packs. The CodeQL CLI documentation shows usage for installing and listing packs.
 - GitHub docs:
   - Code scanning docs and the CodeQL repo README often list recommended packs and query categories.
 
 Suggested immediate next steps
+
 1. Keep the current packs (cpp-security-and-quality and python-security-and-quality) enabled in `.github/codeql/codeql-config.yml` — they are the right baseline.
 2. Search the CodeQL packs index for any GitHub Actions pack and enable it if you want workflow-level checks.
 3. If you want more thorough coverage, enable the experimental packs temporarily in a non-blocking run, review the alerts, then decide whether to include them in CI permanently.
@@ -125,4 +136,3 @@ When a PR is opened from a fork, the `GITHUB_TOKEN` does not have permission to
 ## Contact / Ownership
 
 - Consider adding a CODEOWNERS file for the phlex-src tree so triage notifications reach the most appropriate maintainers.
-```

.github/REUSABLE_WORKFLOWS.md

@@ -28,13 +28,13 @@ Once you have done this, you can trigger the auto-fix workflows by commenting on
 For workflows that automatically commit fixes to pull requests (e.g., formatters), you must create a Personal Access Token (PAT) and add it as a secret to your repository.
 
 1. **Create a PAT:** Follow the GitHub documentation to [create a fine-grained personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token).
-   -  Give it a descriptive name (e.g., `WORKFLOW_FIXES_PAT`).
-   -  Grant it the following repository permissions:
-      -  `Contents`: `Read and write`
-      -  `Pull requests`: `Read and write`
+   - Give it a descriptive name (e.g., `WORKFLOW_FIXES_PAT`).
+   - Grant it the following repository permissions:
+      - `Contents`: `Read and write`
+      - `Pull requests`: `Read and write`
 2. **Add the PAT as a Repository Secret:**
-   -  In your repository, go to `Settings` > `Secrets and variables` > `Actions`.
-   -  Create a new repository secret named `WORKFLOW_PAT` and paste your PAT as the value.
+   - In your repository, go to `Settings` > `Secrets and variables` > `Actions`.
+   - Create a new repository secret named `WORKFLOW_PAT` and paste your PAT as the value.
 
 ### Calling a Reusable Workflow from a Different Repository
 
@@ -80,14 +80,14 @@ jobs:
 
 #### All Inputs
 
--  `checkout-path` (string, optional): Path to check out code to.
--  `build-path` (string, optional): Path for build artifacts.
--  `skip-relevance-check` (boolean, optional, default: `false`): Bypass the check that only runs the build if C++ or CMake files have changed.
--  `build-combinations` (string, optional): A space-separated list of build combinations to run.
--  `ref` (string, optional): The branch or ref to check out.
--  `repo` (string, optional): The repository to check out from (e.g., `my-org/my-repo`).
--  `pr-base-sha` (string, optional): Base SHA of the PR for relevance check.
--  `pr-head-sha` (string, optional): Head SHA of the PR for relevance check.
+- `checkout-path` (string, optional): Path to check out code to.
+- `build-path` (string, optional): Path for build artifacts.
+- `skip-relevance-check` (boolean, optional, default: `false`): Bypass the check that only runs the build if C++ or CMake files have changed.
+- `build-combinations` (string, optional): A space-separated list of build combinations to run.
+- `ref` (string, optional): The branch or ref to check out.
+- `repo` (string, optional): The repository to check out from (e.g., `my-org/my-repo`).
+- `pr-base-sha` (string, optional): Base SHA of the PR for relevance check.
+- `pr-head-sha` (string, optional): Head SHA of the PR for relevance check.
 
 ### 2. `python-check.yaml`
 
@@ -103,10 +103,10 @@ jobs:
 
 #### All Inputs
 
--  `checkout-path` (string, optional): Path to check out code to.
--  `skip-relevance-check` (boolean, optional, default: `false`): Bypass the check that only runs if Python files have changed.
--  `pr-base-sha` (string, optional): Base SHA of the PR for relevance check.
--  `pr-head-sha` (string, optional): Head SHA of the PR for relevance check.
+- `checkout-path` (string, optional): Path to check out code to.
+- `skip-relevance-check` (boolean, optional, default: `false`): Bypass the check that only runs if Python files have changed.
+- `pr-base-sha` (string, optional): Base SHA of the PR for relevance check.
+- `pr-head-sha` (string, optional): Head SHA of the PR for relevance check.
 
 ### 3. `cmake-format-fix.yaml`
 
@@ -140,9 +140,9 @@ jobs:
 
 #### All Inputs
 
--  `checkout-path` (string, optional): Path to check out code to.
--  `ref` (string, **required**): The branch or ref to check out.
--  `repo` (string, **required**): The repository to check out from.
+- `checkout-path` (string, optional): Path to check out code to.
+- `ref` (string, **required**): The branch or ref to check out.
+- `repo` (string, **required**): The repository to check out from.
 
 ### 4. `python-fix.yaml`
 
@@ -154,23 +154,23 @@ Automatically formats and fixes Python code using `ruff` and commits the changes
 
 #### All Inputs
 
--  `checkout-path` (string, optional): Path to check out code to.
--  `ref` (string, **required**): The branch or ref to check out.
--  `repo` (string, **required**): The repository to check out from.
+- `checkout-path` (string, optional): Path to check out code to.
+- `ref` (string, **required**): The branch or ref to check out.
+- `repo` (string, **required**): The repository to check out from.
 
 ### 5. `markdown-fix.yaml`
 
 Automatically formats Markdown files using `markdownlint` and commits the changes. Typically triggered by an `issue_comment`.
 
-#### Usage Example (in a workflow triggered by `issue_comment`)
+#### Usage Example: `markdown-fix.yaml` (in a workflow triggered by `issue_comment`)
 
 *Similar to `cmake-format-fix.yaml`, but triggered by a command like `@<repo>bot markdown-fix`.*
 
-#### All Inputs
+#### All Inputs: `markdown-fix.yaml`
 
--  `checkout-path` (string, optional): Path to check out code to.
--  `ref` (string, **required**): The branch or ref to check out.
--  `repo` (string, **required**): The repository to check out from.
+- `checkout-path` (string, optional): Path to check out code to.
+- `ref` (string, **required**): The branch or ref to check out.
+- `repo` (string, **required**): The repository to check out from.
 
 ### Other Workflows
 

.github/actions/detect-relevant-changes/action.yaml

@@ -53,6 +53,7 @@ runs:
         DEFAULT_TYPE_PATTERNS[cpp]=$'*.cpp\n*.hpp'
         DEFAULT_TYPE_PATTERNS[cmake]=$'CMakeLists.txt\n*.cmake'
         DEFAULT_TYPE_PATTERNS[python]=$'*.py'
+        DEFAULT_TYPE_PATTERNS[md]=$'*.md'
 
         parse_list() {
           local input="$1"

.github/copilot-instructions.md

@@ -94,7 +94,7 @@ If the workspace root contains a `srcs/` directory, it may contain symbolic link
 
 ## Text Formatting Standards
 
-**CRITICAL: Apply to ALL files you create or edit (bash scripts, Python, C++, YAML, Markdown, etc.)**
+### CRITICAL: Apply to ALL files you create or edit (bash scripts, Python, C++, YAML, Markdown, etc.)
 
 - All text files must have their final line be non-empty and terminated with a single newline character, leaving no trailing blank lines
 - **Never add trailing whitespace on any line** (spaces or tabs at end of lines)

.github/workflows/markdown-check.yaml

@@ -70,10 +70,10 @@ jobs:
         path: phlex-src
 
     - name: Add problem matcher
-      uses: xt0rted/markdownlint-problem-matcher@v1
+      uses: xt0rted/markdownlint-problem-matcher@b643b0751c371f357690337d4549221347c0e1bc # v1.1.0
 
     - name: Run markdownlint
-      uses: DavidAnson/markdownlint-cli2-action@v11
+      uses: DavidAnson/markdownlint-cli2-action@8f3516061301755c97ff833a8e933f09282cc5b5 # v11.0.0
       with:
         globs: |
           phlex-src/**/*.md

.github/workflows/markdown-fix.yaml

@@ -5,6 +5,20 @@ on:
   issue_comment:
     types:
       - created
+  workflow_call:
+    inputs:
+      checkout-path:
+        description: "Path to check out code to"
+        required: false
+        type: string
+      ref:
+        description: "The branch or ref to checkout"
+        required: true
+        type: string
+      repo:
+        description: "The repository to checkout from"
+        required: true
+        type: string
   workflow_dispatch:
     inputs:
       ref:
@@ -16,18 +30,23 @@ permissions:
   pull-requests: write
   contents: write
 
+env:
+  local_checkout_path: ${{ (github.event_name == 'workflow_call' && inputs.checkout-path) || format('{0}-src', github.event.repository.name) }}
+
 jobs:
-  pre-check:
+  parse-command:
     runs-on: ubuntu-latest
-    name: Parse command
+    name: Parse bot command
     if: >
       github.event_name == 'workflow_dispatch' ||
       (
         github.event_name == 'issue_comment' &&
         github.event.issue.pull_request &&
         (
           startsWith(github.event.comment.body, '@phlexbot format') ||
-          startsWith(github.event.comment.body, '@phlexbot markdown-fix')
+          startsWith(github.event.comment.body, '@phlexbot markdown-fix') ||
+          startsWith(github.event.comment.body, format('@{0}bot format', github.event.repository.name)) ||
+          startsWith(github.event.comment.body, format('@{0}bot markdown-fix', github.event.repository.name))
         )
       )
     outputs:
@@ -43,29 +62,29 @@ jobs:
   apply_fixes:
     runs-on: ubuntu-latest
     name: Apply fixes
-    needs: pre-check
-    if: ${{ needs.pre-check.result == 'success' }}
+    needs: parse-command
+    if: github.event_name == 'workflow_call' || needs.parse-command.result == 'success'
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
-          path: phlex-src
-          ref: ${{ needs.pre-check.outputs.ref }}
-          repository: ${{ needs.pre-check.outputs.repo }}
+          path: ${{ env.local_checkout_path }}
+          ref: ${{ (github.event_name == 'workflow_call' && inputs.ref) || needs.parse-command.outputs.ref }}
+          repository: ${{ (github.event_name == 'workflow_call' && inputs.repo) || needs.parse-command.outputs.repo }}
           token: ${{ secrets.WORKFLOW_PAT }}
 
       - name: Run markdownlint
-        uses: DavidAnson/markdownlint-cli2-action@v11
+        uses: DavidAnson/markdownlint-cli2-action@8f3516061301755c97ff833a8e933f09282cc5b5 # v11.0.0
         with:
           globs: |
-            phlex-src/**/*.md
-            !phlex-src/**/CHANGELOG.md
+            ${{ env.local_checkout_path }}/**/*.md
+            !${{ env.local_checkout_path }}/**/CHANGELOG.md
           fix: true
 
       - name: Handle fix commit
-        uses: ./phlex-src/.github/actions/handle-fix-commit
+        uses: Framework-R-D/phlex/.github/actions/handle-fix-commit@main
         with:
           tool: markdownlint
-          working-directory: phlex-src
+          working-directory: ${{ env.local_checkout_path }}
           token: ${{ secrets.WORKFLOW_PAT }}
-          pr-info-ref: ${{ needs.pre-check.outputs.ref }}
-          pr-info-repo: ${{ needs.pre-check.outputs.repo }}
+          pr-info-ref: ${{ (github.event_name == 'workflow_call' && inputs.ref) || needs.parse-command.outputs.ref }}
+          pr-info-repo: ${{ (github.event_name == 'workflow_call' && inputs.repo) || needs.parse-command.outputs.repo }}

.markdownlint.jsonc

@@ -1,15 +1,13 @@
 {
-  "config": {
-    "default": true,
-    "MD012": true,
-    "MD013": false,
-    "MD022": true,
-    "MD031": true,
-    "MD032": true,
-    "MD034": true,
-    "MD036": {
-      "punctuation": ".,;:!?"
-    },
-    "MD040": true
-  }
+  "default": true,
+  "MD012": true,
+  "MD013": false,
+  "MD022": true,
+  "MD031": true,
+  "MD032": true,
+  "MD034": true,
+  "MD036": {
+    "punctuation": ".,;:!?"
+  },
+  "MD040": true
 }

DEVELOPING.md

@@ -114,7 +114,6 @@ The project automatically runs coverage analysis on every PR and push to main/de
 
 Coverage reports are uploaded to Codecov for tracking and PR integration, with automatic comments on PRs showing coverage changes.
 
-
 ## On GitHub Copilot
 
 The `.github/copilot-instructions.md` contains various "ground rules" to be observed by GitHub Copilot for every session. They are intended to be useful for everyone, but you can override or augment them yourself by creating a `<workspace>/.github/copilot-instructions.md` file. If this file exists, its contents will be merged with—but take precedence over—the repository level instructions.