ci/docs: restore CodeQL and clarify documentation hierarchy#301
ci/docs: restore CodeQL and clarify documentation hierarchy#301flyingrobots merged 4 commits intomainfrom
Conversation
|
Warning Rate limit exceeded
⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (1)
WalkthroughAdds a CodeQL GitHub Actions workflow and applies widespread documentation updates: product reframing (README, ROADMAP, VISION), canonicalization of docs (docs/README.md, docs/design/git-mind.md, ADR/readme), minor policy docs (CONTRIBUTING.md, AGENTS.md, CLAUDE.md), and many historical-note inserts across docs and notes. Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3 | ❌ 2❌ Failed checks (2 warnings)
✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.github/workflows/codeql.yml:
- Line 19: Change the workflow's runs-on value from the generic runner to a
pinned Ubuntu image to improve reproducibility: locate the runs-on key in the
codeql.yml workflow (the line currently set to "runs-on: ubuntu-latest") and
replace it with a specific release such as "runs-on: ubuntu-22.04" or "runs-on:
ubuntu-24.04"; ensure any downstream actions or matrix entries remain compatible
with the chosen pinned Ubuntu version.
- Around line 34-37: The CodeQL init step (uses: github/codeql-action/init@v4)
currently sets languages and build-mode but doesn’t enable extended query
suites; update the init step to add a queries parameter (e.g., include
"security-extended" or "security-and-quality") so CodeQL runs the extended rule
packs in addition to defaults—modify the with block that contains languages and
build-mode to include queries and list the desired extended suites to increase
coverage.
- Line 34: The workflow currently pins the CodeQL actions by major version
(uses: github/codeql-action/init@v4 and uses: github/codeql-action/analyze@v4),
which is insufficient for supply-chain security; update both references to
immutable commit SHAs (replace the `@v4` suffix with the provided commit SHA
3869755a72c61dae88e42c0cb8f85ac22b7f9c5d for both init and analyze) so the
actions are pinned to a specific commit; ensure both occurrences
(github/codeql-action/init and github/codeql-action/analyze) are updated to the
same SHA and commit the change.
- Line 31: Replace the three workflow action version tags with immutable commit
SHAs: change actions/checkout@v4 to actions/checkout@<full-sha>,
github/codeql-action/init@v4 to github/codeql-action/init@<full-sha>, and
github/codeql-action/analyze@v4 to github/codeql-action/analyze@<full-sha>;
locate the usages of actions/checkout, github/codeql-action/init, and
github/codeql-action/analyze in the codeql.yml and update each ref to the
specific commit SHA (retrieved from the respective GitHub action repository) so
the workflow pins to exact commits rather than major-version tags.
- Around line 17-19: The "analyze" job in the CodeQL workflow lacks timeout
protection; add a timeout-minutes key under the analyze job definition (the job
named "analyze" / runs-on: ubuntu-latest) to prevent runaway runs—set a
reasonable value (for example 60) so the analyze job will be terminated if it
exceeds that duration.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 1993a2c7-9a4d-4638-90ae-96d4ea07a414
📒 Files selected for processing (1)
.github/workflows/codeql.yml
flyingrobots
changed the title
There was a problem hiding this comment.
Actionable comments posted: 8
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@AGENTS.md`:
- Line 29: Update the strict commit-message rule that currently reads "**YOU
MUST** reference a GitHub issue in every commit message" to be less onerous:
change the wording to require an issue reference only for "significant" or
"user-facing" commits (e.g., features, bug fixes, breaking changes) and add a
short lightweight convention for housekeeping commits (examples: "chore/docs/ci:
no-issue-needed" or create a single tracking issue to reference for minor
bumps). Modify AGENTS.md to replace the absolute MUST with this relaxed rule and
include the lightweight convention note so contributors know when an issue is
required and how to handle routine commits.
- Line 93: Update the AGENTS.md line describing the core dependency
`@git-stunts/git-warp` to include the precise local path or where the mapping is
defined; either change the text to a concrete relative path (for example
"file:../git-warp" or "../git-warp") or add a note pointing readers to the
package.json (or workspace configuration) that contains the file/path mapping so
consumers know exactly where to find the local dependency.
In `@docs/design/git-mind.md`:
- Around line 248-276: The doc notes identify specific stale artifacts
(GUIDE.md, TECH-PLAN.md, docs/RISK_REGISTER.md, docs/RISK_REVIEW_CHECKLIST.md)
but give no concrete disposition; fix by choosing and applying a consistent
treatment: add a top-level deprecation/status header to each stale file stating
"Historic — reference only" with a short rationale and the date, move copies of
truly obsolete files into an /archive or /docs/archive folder and replace
originals with a one-line pointer to the archive, update ROADMAP.md and this
design doc (git-mind.md) to explicitly list which files are archival vs
canonical and add cross-links to the archived versions, and add a short note in
README.md explaining where to find archived milestone-era docs and the
authoritative product sources (ROADMAP.md, Hills, Playbacks, and GitHub issues).
- Line 3: The document git-mind.md is marked "Status: draft for review" but is
already included in the project's canonical docs list in the README; either
remove or change the draft status or remove it from the README canonical list.
Open git-mind.md and update the status field to a non-draft state (e.g.,
"Status: canonical" or "Status: ready") if it should be canonical, or else edit
the README's canonical docs list to remove git-mind.md until the draft is
finalized; ensure the change is consistent by verifying the README canonical
docs section and the status line inside git-mind.md.
In `@docs/RISK_REGISTER.md`:
- Around line 7-11: The "Historical note:" paragraph is ambiguous about whether
the register should be consulted; update that paragraph (the "Historical note:"
block) to state a single, unambiguous usage: either mark it explicitly as
"Historical archive — do not use for current planning" or "Reference for
workflow-adoption planning — consult when planning future work"; pick one and
revise the sentence to reflect that choice (e.g., "This register is a historical
archive and should not be used for current planning." OR "This register should
be consulted when planning workflow-adoption work as a reference for future
roadmap decisions."), keeping the "Historical note:" heading to locate the
change.
In `@GRAPH_SCHEMA.md`:
- Around line 7-8: Update the phrasing that currently says "remain supported" to
accurately reflect runtime behavior: replace that phrase with text stating
legacy/non-canonical prefixes are treated as "unknown" by runtime validators and
will emit warnings rather than being treated as fully supported; update the
surrounding sentence in GRAPH_SCHEMA.md and any example/prefix sections to
explicitly document the validator behavior and recommended migration path so
readers/tools won’t assume these prefixes are authoritative.
In `@README.md`:
- Around line 133-142: The README's canonical docs list currently includes
docs/design/git-mind.md which is still marked "Status: draft for review"; either
remove docs/design/git-mind.md from the canonical list in README.md or update
the git-mind.md frontmatter/status to a non-draft state and reflect that change
in the README entry (e.g., add “[draft]” or move it to a non-canonical section).
Locate the canonical list block in README.md and update the entry for
docs/design/git-mind.md accordingly, ensuring the README only lists finalized
canonical references.
In `@ROADMAP.md`:
- Line 141: Replace the lowercase term "markdown" in the phrase "markdown docs"
with the proper noun "Markdown" so the text reads "Markdown docs"; locate the
exact occurrence of the string "markdown docs" in the document and update only
the capitalization to "Markdown" to correct the proper noun usage.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: e445dafa-0a3f-4e61-9395-827500f3bced
📒 Files selected for processing (19)
AGENTS.mdCHANGELOG.mdCLAUDE.mdCONTRIBUTING.mdGRAPH_SCHEMA.mdGUIDE.mdREADME.mdROADMAP.mdTECH-PLAN.mddocs/ARCHITECTURE.mddocs/README.mddocs/REVIEW_RUBRIC.mddocs/RISK_REGISTER.mddocs/RISK_REVIEW_CHECKLIST.mddocs/VISION_NORTH_STAR.mddocs/adr/README.mddocs/design/git-mind.mddocs/notes/Git Mind Strategic Conversation Summary.mddocs/notes/dogfood-session.md
| - **YOU MUST** tag all memories saved to your memory banks with at least `#git-mind` | ||
| - **YOU MUST** include the POSIX timestamp (via `$(date +%s)`) in memory file names | ||
| - **YOU MUST** document significant decisions or events | ||
| - **YOU MUST** reference a GitHub issue in every commit message |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Absolute commit-message requirement will cause friction.
Requiring a GitHub issue reference in every commit message is ideal discipline but will conflict with common commit patterns like chore: update dependencies, docs: fix typo, or ci: bump node version where creating an issue would be pure overhead.
Either relax the requirement to "significant commits" or establish a lightweight issue-creation convention for housekeeping commits.
Suggested revision
-- **YOU MUST** reference a GitHub issue in every commit message
+- **YOU MUST** reference a GitHub issue in every commit message for feature work and bug fixes (trivial chores may use conventional commit format without an issue)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - **YOU MUST** reference a GitHub issue in every commit message | |
| - **YOU MUST** reference a GitHub issue in every commit message for feature work and bug fixes (trivial chores may use conventional commit format without an issue) |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@AGENTS.md` at line 29, Update the strict commit-message rule that currently
reads "**YOU MUST** reference a GitHub issue in every commit message" to be less
onerous: change the wording to require an issue reference only for "significant"
or "user-facing" commits (e.g., features, bug fixes, breaking changes) and add a
short lightweight convention for housekeeping commits (examples: "chore/docs/ci:
no-issue-needed" or create a single tracking issue to reference for minor
bumps). Modify AGENTS.md to replace the absolute MUST with this relaxed rule and
include the lightweight convention note so contributors know when an issue is
required and how to handle routine commits.
| ## 5. TECH STACK REFERENCE | ||
|
|
||
| - **Runtime**: Node.js >= 20, ES modules | ||
| - **Core dependency**: `@git-stunts/git-warp` (local path, CRDT graph on Git) |
There was a problem hiding this comment.
Incomplete local path specification for git-warp dependency.
The tech stack reference states @git-stunts/git-warp is a "(local path, CRDT graph on Git)" but doesn't specify which local path. An agent following these instructions would not know where to find or how to configure this dependency.
Either provide the actual relative path (e.g., ../git-warp or file:../git-warp) or state where the path is configured (e.g., "see package.json for path mapping").
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@AGENTS.md` at line 93, Update the AGENTS.md line describing the core
dependency `@git-stunts/git-warp` to include the precise local path or where the
mapping is defined; either change the text to a concrete relative path (for
example "file:../git-warp" or "../git-warp") or add a note pointing readers to
the package.json (or workspace configuration) that contains the file/path
mapping so consumers know exactly where to find the local dependency.
| @@ -0,0 +1,386 @@ | |||
| # Git Mind Product Frame | |||
|
|
|||
| Status: draft for review | |||
There was a problem hiding this comment.
Status contradiction: document marked draft but already canonical.
This document is marked Status: draft for review but README.md line 140 already lists docs/design/git-mind.md as part of the canonical docs set. Either remove the draft status or remove it from the canonical list until review is complete.
Proposed resolution
-Status: draft for review
+Status: canonicalOr defer adding it to README.md's canonical docs list until this draft status is resolved.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Status: draft for review | |
| Status: canonical |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/design/git-mind.md` at line 3, The document git-mind.md is marked
"Status: draft for review" but is already included in the project's canonical
docs list in the README; either remove or change the draft status or remove it
from the README canonical list. Open git-mind.md and update the status field to
a non-draft state (e.g., "Status: canonical" or "Status: ready") if it should be
canonical, or else edit the README's canonical docs list to remove git-mind.md
until the draft is finalized; ensure the change is consistent by verifying the
README canonical docs section and the status line inside git-mind.md.
| - `README.md`, `ROADMAP.md`, `docs/VISION_NORTH_STAR.md`, and this design doc now describe the clarified product frame. | ||
| - `GUIDE.md` still reflects an earlier manual graph-authoring story. | ||
| - `TECH-PLAN.md`, `docs/RISK_REGISTER.md`, and `docs/RISK_REVIEW_CHECKLIST.md` still reflect the older milestone-driven platform and bridge roadmap. | ||
| - Historical notes remain useful, but they should not compete with active product planning. | ||
|
|
||
| 4. The backlog and the product strategy were being mixed together. | ||
| - Open issues contain useful implementation work. | ||
| - Old milestones were pretending to be the product strategy. | ||
| - IBM Design Thinking works better here if strategy is expressed as Hills and evaluated through Playbacks, while GitHub issues remain the unit of execution. | ||
|
|
||
| ## Recommended Operating Model | ||
|
|
||
| `git-mind` should no longer use GitHub milestones as its primary planning system. | ||
|
|
||
| Recommended split: | ||
|
|
||
| - IBM Hills define the product outcomes that matter. | ||
| - Playbacks review whether recent work actually moved one of those Hills. | ||
| - GitHub issues track concrete work items. | ||
| - Docs capture the current product frame and playback conclusions. | ||
|
|
||
| In practice: | ||
|
|
||
| - Keep a small set of active Hills in `ROADMAP.md` and this design doc. | ||
| - Use GitHub issues for implementation and bug work. | ||
| - Triage issues by Hill or lane, not by faux-release milestone. | ||
| - Record playback outcomes in issue comments, PRs, or doc updates rather than reopening milestone theater. | ||
| - Treat historical milestone-era docs as references, not control planes. | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Incomplete disposition of competing/stale documentation.
Lines 248-251 identify specific stale docs (GUIDE.md, TECH-PLAN.md, docs/RISK_REGISTER.md, docs/RISK_REVIEW_CHECKLIST.md) that "should not compete with active product planning" and represent "earlier manual graph-authoring story" or "older milestone-driven platform and bridge roadmap." Line 275 says to "treat historical milestone-era docs as references, not control planes."
However, the document provides no concrete disposition:
- Should these files be moved to an archive directory?
- Should they have deprecation notices added at the top?
- Should they be deleted?
- How will future readers know they are historical vs. canonical?
The recommended operating model section would be strengthened by adding explicit next actions for these identified competing artifacts.
🧰 Tools
🪛 LanguageTool
[style] ~253-~253: ‘mixed together’ might be wordy. Consider a shorter alternative.
Context: ...log and the product strategy were being mixed together. - Open issues contain useful implem...
(EN_WORDINESS_PREMIUM_MIXED_TOGETHER)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/design/git-mind.md` around lines 248 - 276, The doc notes identify
specific stale artifacts (GUIDE.md, TECH-PLAN.md, docs/RISK_REGISTER.md,
docs/RISK_REVIEW_CHECKLIST.md) but give no concrete disposition; fix by choosing
and applying a consistent treatment: add a top-level deprecation/status header
to each stale file stating "Historic — reference only" with a short rationale
and the date, move copies of truly obsolete files into an /archive or
/docs/archive folder and replace originals with a one-line pointer to the
archive, update ROADMAP.md and this design doc (git-mind.md) to explicitly list
which files are archival vs canonical and add cross-links to the archived
versions, and add a short note in README.md explaining where to find archived
milestone-era docs and the authoritative product sources (ROADMAP.md, Hills,
Playbacks, and GitHub issues).
| > Historical note: | ||
| > | ||
| > This register was written for the earlier bridge/platform roadmap. | ||
| > It remains useful as a reference for future workflow-adoption layers, but it is not the active planning control plane for the current Hills. | ||
|
|
There was a problem hiding this comment.
Inconsistent guidance on document usage.
Lines 7-11 state the register is "not the active planning control plane" but then immediately say it "remains useful as a reference for future workflow-adoption layers." This is contradictory - either it's dormant/historical or it's an active reference for future work. The guidance should be unambiguous.
Recommend clarifying whether this document:
- Should be consulted when planning workflow-adoption work (reference)
- Should NOT be used at all (historical archive)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/RISK_REGISTER.md` around lines 7 - 11, The "Historical note:" paragraph
is ambiguous about whether the register should be consulted; update that
paragraph (the "Historical note:" block) to state a single, unambiguous usage:
either mark it explicitly as "Historical archive — do not use for current
planning" or "Reference for workflow-adoption planning — consult when planning
future work"; pick one and revise the sentence to reflect that choice (e.g.,
"This register is a historical archive and should not be used for current
planning." OR "This register should be consulted when planning workflow-adoption
work as a reference for future roadmap decisions."), keeping the "Historical
note:" heading to locate the change.
| > This document is the graph contract, not the canonical product narrative. | ||
| > Some prefixes and examples reflect legacy manual-authoring and roadmap-oriented workflows that remain supported, but they are not the current center of the product story. |
There was a problem hiding this comment.
“Remain supported” overstates actual prefix semantics in runtime validators.
Current implementation treats non-canonical legacy prefixes as unknown with warnings, not as explicitly supported classes. In an authoritative schema doc, this phrasing is too strong and risks contract drift for users/tools.
Proposed wording fix
- Some prefixes and examples reflect legacy manual-authoring and roadmap-oriented workflows that remain supported, but they are not the current center of the product story.
+ Some prefixes and examples reflect legacy manual-authoring and roadmap-oriented workflows that remain accepted by validation (typically as unknown-prefix warnings), but they are not the current center of the product story.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| > This document is the graph contract, not the canonical product narrative. | |
| > Some prefixes and examples reflect legacy manual-authoring and roadmap-oriented workflows that remain supported, but they are not the current center of the product story. | |
| > This document is the graph contract, not the canonical product narrative. | |
| > Some prefixes and examples reflect legacy manual-authoring and roadmap-oriented workflows that remain accepted by validation (typically as unknown-prefix warnings), but they are not the current center of the product story. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@GRAPH_SCHEMA.md` around lines 7 - 8, Update the phrasing that currently says
"remain supported" to accurately reflect runtime behavior: replace that phrase
with text stating legacy/non-canonical prefixes are treated as "unknown" by
runtime validators and will emit warnings rather than being treated as fully
supported; update the surrounding sentence in GRAPH_SCHEMA.md and any
example/prefix sections to explicitly document the validator behavior and
recommended migration path so readers/tools won’t assume these prefixes are
authoritative.
| Canonical docs: | ||
|
|
||
| --- | ||
|
|
||
| ## Status | ||
|
|
||
| **v3.2.0** — M1–M10 shipped. 461 tests. JSON schema contracts on all `--json` outputs. | ||
|
|
||
| The API is stabilising. Breaking changes will be noted in [CHANGELOG.md](CHANGELOG.md). | ||
|
|
||
| --- | ||
| - [docs/README.md](docs/README.md) | ||
| - [GUIDE.md](GUIDE.md) | ||
| - [GRAPH_SCHEMA.md](GRAPH_SCHEMA.md) | ||
| - [ROADMAP.md](ROADMAP.md) | ||
| - [docs/VISION_NORTH_STAR.md](docs/VISION_NORTH_STAR.md) | ||
| - [docs/design/git-mind.md](docs/design/git-mind.md) | ||
| - [docs/adr/](docs/adr/) | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check if GUIDE.md exists and inspect its framing
if [ -f "GUIDE.md" ]; then
echo "=== GUIDE.md exists ==="
echo "First 50 lines:"
head -n 50 GUIDE.md
echo ""
echo "=== Checking for manual authoring/graph-authoring language ==="
rg -i -C 2 'manual|author|create.*edge|create.*node|build.*graph' GUIDE.md | head -n 30
else
echo "GUIDE.md does not exist"
fi
echo ""
echo "=== Checking git-mind.md assessment of GUIDE.md ==="
rg -A 3 -B 3 'GUIDE.md' docs/design/git-mind.mdRepository: flyingrobots/git-mind
Length of output: 4844
🏁 Script executed:
#!/bin/bash
# Check docs/design/git-mind.md status and verify all canonical docs exist
echo "=== Checking docs/design/git-mind.md draft status (line 3) ==="
head -n 5 docs/design/git-mind.md
echo ""
echo "=== Verifying all canonical docs from README.md lines 133-142 exist ==="
DOCS=(
"docs/README.md"
"GUIDE.md"
"GRAPH_SCHEMA.md"
"ROADMAP.md"
"docs/VISION_NORTH_STAR.md"
"docs/design/git-mind.md"
"docs/adr/"
)
for doc in "${DOCS[@]}"; do
if [ -e "$doc" ]; then
echo "✓ $doc exists"
else
echo "✗ $doc MISSING"
fi
done
echo ""
echo "=== Check package.json for version 5.0.0 claim ==="
if [ -f "package.json" ]; then
jq .version package.json 2>/dev/null || grep -i '"version"' package.json | head -1
else
echo "package.json not found"
fiRepository: flyingrobots/git-mind
Length of output: 497
Remove draft doc from canonical docs list or update its status.
The canonical docs list includes docs/design/git-mind.md (line 140), which is marked "Status: draft for review" at line 3. Either update the file's status or remove it from the canonical list—don't ship draft documents as canonical references.
GUIDE.md is correctly positioned. It's marked "transitional" with explicit self-aware status, directs readers to current planning docs, and serves a distinct CLI reference role. No action needed there.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` around lines 133 - 142, The README's canonical docs list currently
includes docs/design/git-mind.md which is still marked "Status: draft for
review"; either remove docs/design/git-mind.md from the canonical list in
README.md or update the git-mind.md frontmatter/status to a non-draft state and
reflect that change in the README entry (e.g., add “[draft]” or move it to a
non-canonical section). Locate the canonical list block in README.md and update
the entry for docs/design/git-mind.md accordingly, ensuring the README only
lists finalized canonical references.
| - *In:* Edge syntax extension, remote qualifiers, local storage of remote edges | ||
| - *Out:* Remote graph queries, cross-repo graph merge, federated views | ||
| - code files and module/package structure | ||
| - markdown docs |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Use proper noun capitalization for Markdown.
Line 141 uses lowercase "markdown" when referring to the markup language. The proper noun is "Markdown."
📝 Proposed fix
-- markdown docs
+- Markdown docs📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - markdown docs | |
| - Markdown docs |
🧰 Tools
🪛 LanguageTool
[uncategorized] ~141-~141: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ...de files and module/package structure - markdown docs - ADRs - commit history - issue an...
(MARKDOWN_NNP)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@ROADMAP.md` at line 141, Replace the lowercase term "markdown" in the phrase
"markdown docs" with the proper noun "Markdown" so the text reads "Markdown
docs"; locate the exact occurrence of the string "markdown docs" in the document
and update only the capitalization to "Markdown" to correct the proper noun
usage.
1 participant
PR Title
ci/docs: restore CodeQL and clarify documentation hierarchy
Summary
main, pull requests targetingmain, and a weekly scheduledocs/README.mdas the documentation map and define canonical vs transitional vs historical docsProblem Statement
The repository had two separate sources of drift. First, CodeQL scanning had been removed, so GitHub could not recompute stale security alerts even after the vulnerable
src/context.jsshell-construction path had already been fixed onmain. Second, the documentation stack was carrying multiple competing product narratives and outdated milestone-era planning artifacts, which made the repo harder to reason about and harder to plan against.ADR Compliance (Required)
Relevant ADR(s)
Compliance Declaration
Exception Request (Required if deviating)
Architecture Laws Checklist (Hard Gates)
Canonical Truth & Context
--at,--observer,--trust) or deterministically defaulted.Determinism & Provenance
Artifact Hygiene
Contracts & Compatibility
Extension/Effects Safety (if applicable)
Scope Control
Backward Compatibility
Test Plan (Required)
Unit
npm testIntegration
# No dedicated integration test changes; existing PR CI covers this change set.Determinism
# Not applicable for this workflow/docs change.Contract/Schema
ruby -e "require 'yaml'; YAML.load_file('.github/workflows/codeql.yml')"Policy Gates
npm testSecurity / Trust Impact
Performance Impact
Observability / Debuggability
Operational Notes
Linked Issues / Milestones
Reviewer Quick Verdict Block (for maintainers)
MUST (Hard Gates)
SHOULD (Quality)
Verdict