Skip to content

M1 foundations: roadmap governance + smoke scripts + deterministic graph commit digest #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
flyingrobots merged 47 commits into from
Dec 31, 2025
Merged

M1 foundations: roadmap governance + smoke scripts + deterministic graph commit digest #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
47 commits
Select commit Hold shift + click to select a range
cd3769b
chore: save progress before starting milestone-1 tex build
flyingrobots Dec 29, 2025
5e2089e
branch: initialize milestone-1 tex build development
flyingrobots Dec 29, 2025
b9ada84
test: reproduce failing milestone-1 TeX build
flyingrobots Dec 29, 2025
8e8927e
fix(tex): make milestone-1 report buildable
flyingrobots Dec 29, 2025
cfc999d
chore: save progress (WarpNode id uses NodeId)
flyingrobots Dec 30, 2025
6f85477
docs: refine M1 kernel alpha roadmap
flyingrobots Dec 30, 2025
a9616ba
branch: initialize a5 page size development
flyingrobots Dec 30, 2025
e4f6aab
docs(tex): switch book styles to a5paper
flyingrobots Dec 30, 2025
38a938a
docs: inline Milestone 1 task checklist
flyingrobots Dec 30, 2025
e86ff33
docs: remove M1 TASKS.md after inlining
flyingrobots Dec 30, 2025
c75e136
docs: tighten M1 semantics for determinism
flyingrobots Dec 30, 2025
8c4cf1e
docs: lock M1 API contract in SPEC-NET-0001
flyingrobots Dec 30, 2025
807804d
docs: codify M1 error mapping and op validation
flyingrobots Dec 30, 2025
b8a768d
docs: add M2–M7 milestone plans
flyingrobots Dec 30, 2025
11abd9d
docs: add ROADMAP milestone MOC
flyingrobots Dec 30, 2025
786b766
docs: describe per-milestone user capabilities
flyingrobots Dec 30, 2025
364ba43
docs: add M2 task dependency DAG
flyingrobots Dec 30, 2025
f853ec4
docs: add milestone dependency DAG to roadmap
flyingrobots Dec 30, 2025
ad03a04
docs: add M1 task DAG and milestone status styling
flyingrobots Dec 30, 2025
225e16b
docs: auto-style milestone DAGs and add M1 task DAG
flyingrobots Dec 30, 2025
dd9717c
chore: add script to update roadmap DAG statuses
flyingrobots Dec 30, 2025
b0e95be
docs: add phase DAGs for M3–M7
flyingrobots Dec 30, 2025
6a4c741
branch: initialize roadmap dag hooks development
flyingrobots Dec 30, 2025
105ec9d
chore: add conditional pre-commit hook for roadmap dags
flyingrobots Dec 30, 2025
1a2cbdb
chore: add xtask wrapper and docs for roadmap dag automation
flyingrobots Dec 30, 2025
c9891cc
branch: initialize docs tour development
flyingrobots Dec 30, 2025
e66f400
docs: add docs tour map for theory specs roadmap
flyingrobots Dec 30, 2025
13abb5f
docs: link docs tour and milestone roadmap from root readme
flyingrobots Dec 30, 2025
2a9054d
docs: expand docs tour with code map by crate and file
flyingrobots Dec 30, 2025
9226f56
branch: initialize warp graph hashing spec development
flyingrobots Dec 30, 2025
a2cb7a7
docs: add WARP graph digest specs and link from M1
flyingrobots Dec 30, 2025
c6c6285
docs: link deterministic id spec to graph commit digest spec
flyingrobots Dec 30, 2025
9c3749d
branch: initialize docs bookkeeping development
flyingrobots Dec 30, 2025
73715f6
docs: define docs governance and source-of-truth hierarchy
flyingrobots Dec 30, 2025
6893422
docs: add docs index moc
flyingrobots Dec 30, 2025
f7fa74c
docs: reframe ARCH-0000 integrated spec as directional overview
flyingrobots Dec 30, 2025
b2cc335
docs: add governance/index entrypoints and link ARCH-0000 overview
flyingrobots Dec 30, 2025
72d1d47
docs: add vision pillars and traceability to roadmap moc
flyingrobots Dec 30, 2025
8a0c978
docs: expand roadmap pillars into milestone feature matrix
flyingrobots Dec 30, 2025
4fa251b
docs: add pillar proof hooks and smoke scripts to roadmap
flyingrobots Dec 30, 2025
6beba86
chore: add runnable M1 GraphQL smoke proof script
flyingrobots Dec 30, 2025
22039be
branch: initialize graph commit digest development
flyingrobots Dec 30, 2025
76b8ce4
chore: ignore python __pycache__ artifacts
flyingrobots Dec 30, 2025
6f5b3d4
chore: make jitos-planner a valid crate target
flyingrobots Dec 30, 2025
2583a5b
test: add failing cases for deterministic graph commit digest
flyingrobots Dec 30, 2025
336f354
feat: implement deterministic graph commit digest hashing
flyingrobots Dec 30, 2025
de232d5
style: cargo fmt
flyingrobots Dec 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions .githooks/pre-commit
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
#!/bin/sh
set -eu

# Only run the roadmap DAG updater when a ROADMAP README is staged.
#
# Rationale:
# - Updating Mermaid styling is derived output; avoid paying the cost on commits
# that don't touch roadmap docs.
# - When roadmap docs *do* change, we want DAG styling to match checkbox reality.

staged_files="$(git diff --cached --name-only --diff-filter=ACMR)"

echo "$staged_files" | grep -E -q '^(docs/ROADMAP/README\.md|docs/ROADMAP/M[0-9]+-[^/]+/README\.md)$' || exit 0

echo "pre-commit: updating ROADMAP DAG statuses from checkboxes..."

python3 scripts/update_roadmap_dags.py

# Stage any updates produced by the script.
git add -u docs/ROADMAP
Comment on lines +15 to +20
Copy link

@coderabbitai coderabbitai bot Dec 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

CRITICAL: Auto-staging generated changes bypasses user review.

This pre-commit hook automatically stages generated DAG updates (git add -u docs/ROADMAP) without user review or confirmation. This is problematic because:

  1. Security/Compliance Risk: Per project learnings, pre-commit hooks are part of security and compliance. Auto-staging untrusted generated output could introduce malicious or incorrect content.

  2. Bug Amplification: If update_roadmap_dags.py has a bug, corrupted changes are silently committed.

  3. Audit Trail: Users may not notice what was auto-generated, making it harder to debug issues later.

  4. Unexpected Behavior: Users expect pre-commit hooks to validate, not modify their commits.

Based on learnings: "Treat pre-commit hooks as part of security and compliance; fix underlying issues rather than bypassing hooks with --no-verify"

🔎 Recommended approaches (pick one)

Option 1: Fail instead of auto-stage (force explicit user action)

 python3 scripts/update_roadmap_dags.py
 
-# Stage any updates produced by the script.
-git add -u docs/ROADMAP
+# Check if any files were modified
+if ! git diff --quiet docs/ROADMAP; then
+  echo "ERROR: ROADMAP DAG updates required but not staged." >&2
+  echo "Run: python3 scripts/update_roadmap_dags.py && git add docs/ROADMAP" >&2
+  exit 1
+fi

Option 2: Prompt for confirmation (requires tty)

 python3 scripts/update_roadmap_dags.py
 
+# Check if updater made changes
+if ! git diff --quiet docs/ROADMAP; then
+  echo "ROADMAP DAG updates were generated. Review changes:"
+  git diff docs/ROADMAP
+  printf "Stage these changes? [y/N] "
+  read -r response
+  if [ "$response" = "y" ] || [ "$response" = "Y" ]; then
+    git add -u docs/ROADMAP
+  else
+    echo "Aborting commit. Stage changes manually when ready." >&2
+    exit 1
+  fi
+fi
+
-# Stage any updates produced by the script.
-git add -u docs/ROADMAP

Option 3: Document and accept risk (least recommended)
Add prominent comment explaining the auto-staging behavior and rationale.

📝 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.

Suggested change
echo "pre-commit: updating ROADMAP DAG statuses from checkboxes..."
python3 scripts/update_roadmap_dags.py
# Stage any updates produced by the script.
git add -u docs/ROADMAP
echo "pre-commit: updating ROADMAP DAG statuses from checkboxes..."
python3 scripts/update_roadmap_dags.py
# Check if any files were modified
if ! git diff --quiet docs/ROADMAP; then
echo "ERROR: ROADMAP DAG updates required but not staged." >&2
echo "Run: python3 scripts/update_roadmap_dags.py && git add docs/ROADMAP" >&2
exit 1
fi
🤖 Prompt for AI Agents 
.githooks/pre-commit around lines 15-20: the hook currently runs
scripts/update_roadmap_dags.py and then auto-stages its output with "git add -u
docs/ROADMAP", which silently modifies commits and bypasses user review; remove
the automatic git add and instead either (a) make the hook fail when changes are
detected and print a clear message instructing the user to inspect and stage the
generated changes manually, or (b) if interactive shells are available, prompt
the user to confirm staging before running git add; implement one of these
behaviors and document the chosen approach in a comment at the top of the hook.


# Sanity check: ensure the updater is now clean.
python3 scripts/update_roadmap_dags.py --check >/dev/null
Comment on lines +22 to +23
Copy link

@coderabbitai coderabbitai bot Dec 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Sanity check runs AFTER staging, allowing inconsistent state.

The --check validation runs after git add -u docs/ROADMAP, meaning if the check fails, the repository is left with staged changes that don't pass validation. This violates the principle of atomic commits.

🔎 Fix: Validate before staging 
 python3 scripts/update_roadmap_dags.py
 
+# Sanity check: ensure the updater produced valid output
+python3 scripts/update_roadmap_dags.py --check >/dev/null
+
 # Stage any updates produced by the script.
 git add -u docs/ROADMAP
-
-# Sanity check: ensure the updater is now clean.
-python3 scripts/update_roadmap_dags.py --check >/dev/null

This ensures validation passes before modifying the staging area.

📝 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.

Suggested change
# Sanity check: ensure the updater is now clean.
python3 scripts/update_roadmap_dags.py --check >/dev/null
python3 scripts/update_roadmap_dags.py
# Sanity check: ensure the updater produced valid output
python3 scripts/update_roadmap_dags.py --check >/dev/null
# Stage any updates produced by the script.
git add -u docs/ROADMAP
🤖 Prompt for AI Agents 
.githooks/pre-commit around lines 22-23: the script currently runs the updater
check after staging which can leave invalid changes staged; move the sanity
check to run before any git add -u docs/ROADMAP invocation, ensure the hook
executes python3 scripts/update_roadmap_dags.py --check and exits non-zero on
failure so staging is only performed when validation passes, then proceed to run
git add -u docs/ROADMAP.


4 changes: 4 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@

# macOS cruft
.DS_Store
__pycache__/
.AppleDouble
.LSOverride
Icon\r
Expand Down Expand Up @@ -43,6 +44,9 @@ xcuserdata/
*.fdb_latexmk
*.synctex.gz

# Generated PDFs (built by docs/tex Makefile targets)
*.pdf
Comment on lines +47 to +48
Copy link

@coderabbitai coderabbitai bot Dec 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

CRITICAL: Overly broad PDF ignore pattern will hide potentially important files.

The pattern *.pdf ignores ALL PDF files repository-wide, not just those generated by docs/tex/Makefile. This is dangerous because:

  1. Documentation assets: Reference PDFs, diagrams, or specification documents that should be committed will be silently ignored
  2. Silent failures: Contributors won't see warnings when they try to commit legitimate PDFs
  3. Comment mismatch: The comment says "built by docs/tex Makefile targets" but the pattern isn't scoped to that directory
🔎 Proposed fix: Scope PDF ignore to build output directories 
-# Generated PDFs (built by docs/tex Makefile targets)
-*.pdf
+# Generated PDFs (built by docs/tex Makefile targets)
+/docs/tex/**/*.pdf
+/target/**/*.pdf

If you need to ignore PDFs in additional specific locations, add them explicitly. Never use a root-level wildcard for common file extensions that might be legitimate documentation assets.

📝 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.

Suggested change
# Generated PDFs (built by docs/tex Makefile targets)
*.pdf
# Generated PDFs (built by docs/tex Makefile targets)
/docs/tex/**/*.pdf
/target/**/*.pdf
🤖 Prompt for AI Agents 
In .gitignore around lines 47-48 the entry "*.pdf" is too broad and contradicts
the comment about PDFs generated by docs/tex/Makefile; replace the
repository-wide wildcard with a scoped ignore (e.g., the specific build output
path(s) used by the Makefile such as docs/tex/output/ or docs/build/**/*.pdf) or
list explicit paths for generated PDFs only, and remove the global "*.pdf" so
legitimate documentation PDFs in other locations are no longer ignored.


# Rust build artifacts
target/
**/*.rs.bk
Expand Down
17 changes: 17 additions & 0 deletions Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 1 addition & 3 deletions Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,8 @@ members = [
"crates/jitos-graph",
"crates/jitos-scheduler",
"crates/jitos-views", # Phase 0.5.4
"crates/jitos-planner", # Phase 3.1
# TODO: Add remaining crates as they are created per NEXT-MOVES.md:
# "crates/jitos-inversion", # Phase 1.3
# "crates/jitos-policy", # Phase 2.1
# "crates/jitos-planner", # Phase 3.1
# "crates/jitos-provenance", # Phase 4.1
# "crates/jitos-resilience", # Phase 2.2
# "crates/jitos-io", # Phase 4.2
Expand Down
Loading