From 90b606aa7b4ab8a4e30bb1f54ec38e674b7c1172 Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Sun, 14 Sep 2025 21:41:12 -0700 Subject: [PATCH 01/42] build(changelog): add tools/changelog/add_entry.py and Make target; hardening(cache): replace strcpy ZERO oid with gm_snprintf --- Makefile | 7 +- core/src/cache/builder.c | 3 +- core/src/cache/query.c | 6 +- docs/CI_STRATEGY.md | 10 ++ docs/DEV_SETUP.md | 10 ++ docs/PRDs/PRD-co-thought-mcp-service.md | 10 ++ ...it-mind-semantics-time-travel-prototype.md | 10 ++ docs/README.md | 10 ++ docs/adr/0001-first-class-semantics.md | 10 ++ docs/adr/0002-docs-reorganization.md | 10 ++ docs/api/gitmind-api-reference.md | 10 ++ docs/architecture/MIGRATION_PHILOSOPHY.md | 9 ++ docs/architecture/MODULAR_RESTRUCTURE_PLAN.md | 9 ++ docs/architecture/README.md | 9 ++ docs/architecture/System_Architecture.md | 10 ++ .../attribution-integration-guide.md | 9 ++ docs/architecture/attribution-system.md | 9 ++ docs/architecture/attribution-use-cases.md | 9 ++ docs/architecture/augments-system.md | 10 ++ docs/architecture/bitmap-cache-design.md | 10 ++ docs/architecture/cache-migration-oid-only.md | 10 ++ .../deprecations/legacy-sha-fields.md | 10 ++ .../journal-architecture-pivot.md | 10 ++ docs/architecture/tombstone-visual.md | 10 ++ docs/charter/Project_Charter.md | 10 ++ docs/cli/README.md | 9 ++ docs/cli/combined_markdown.md | 10 ++ docs/cli/gitmind-cache-rebuild.md | 9 ++ docs/cli/gitmind-install-hooks.md | 9 ++ docs/cli/gitmind-link.md | 9 ++ docs/cli/gitmind-list.md | 9 ++ docs/cli/gitmind.md | 10 ++ docs/deployment/Deployment.md | 10 ++ docs/operations/Environment_Variables.md | 10 ++ docs/quality/Markdown_Style_Guide.md | 10 ++ docs/quality/SOLID_DRY_REPORT.md | 10 ++ docs/quality/TIDY_CLANG_CRUSADE.md | 10 ++ docs/quality/local-ci-parity.md | 10 ++ docs/quality/static-analysis-guide.md | 10 ++ docs/quality/tools-vs-custom-checks.md | 10 ++ docs/requirements/Requirements.md | 10 ++ docs/specs/Technical_Specifications.md | 10 ++ docs/testing/Test_Plan.md | 10 ++ tools/changelog/add_entry.py | 78 ++++++++++ tools/docs/check_frontmatter.py | 147 ++++++++++++++++++ 45 files changed, 626 insertions(+), 4 deletions(-) create mode 100644 tools/changelog/add_entry.py create mode 100644 tools/docs/check_frontmatter.py diff --git a/Makefile b/Makefile index 9966e31f..2d9259c1 100644 --- a/Makefile +++ b/Makefile @@ -24,4 +24,9 @@ md-lint: md-fix: @npx --yes -p markdownlint-cli2 markdownlint-cli2 --fix "**/*.md" "#.git" "#build" -.PHONY: all test clean docker-clean md-lint md-fix +# Changelog helpers +.PHONY: changelog-add +changelog-add: + @python3 tools/changelog/add_entry.py -m "$(m)" $(if $(n),-n "$(n)") + +.PHONY: all test clean docker-clean md-lint md-fix changelog-add diff --git a/core/src/cache/builder.c b/core/src/cache/builder.c index 607e764c..233df0a3 100644 --- a/core/src/cache/builder.c +++ b/core/src/cache/builder.c @@ -322,7 +322,8 @@ static int cache_get_journal_tip(git_repository *repo, const char *branch, git_reference_free(journal_ref); } else { /* No journal yet */ - strcpy(meta->journal_tip_oid, ZERO_SHA_STRING); + (void)gm_snprintf(meta->journal_tip_oid, sizeof meta->journal_tip_oid, + "%s", ZERO_SHA_STRING); } return GM_OK; diff --git a/core/src/cache/query.c b/core/src/cache/query.c index 6912bf91..515258ab 100644 --- a/core/src/cache/query.c +++ b/core/src/cache/query.c @@ -146,11 +146,13 @@ int gm_cache_load_meta(gm_context_t *ctx, const char *branch, gm_cache_meta_t *m if (tip_oid) { git_oid_tostr(meta->journal_tip_oid, sizeof(meta->journal_tip_oid), tip_oid); } else { - strcpy(meta->journal_tip_oid, ZERO_SHA_STRING); + (void)gm_snprintf(meta->journal_tip_oid, sizeof meta->journal_tip_oid, + "%s", ZERO_SHA_STRING); } git_reference_free(journal_ref); } else { - strcpy(meta->journal_tip_oid, ZERO_SHA_STRING); + (void)gm_snprintf(meta->journal_tip_oid, sizeof meta->journal_tip_oid, + "%s", ZERO_SHA_STRING); } /* edge_count and build_time_ms unavailable without dedicated storage */ diff --git a/docs/CI_STRATEGY.md b/docs/CI_STRATEGY.md index b77196c8..bef55b54 100644 --- a/docs/CI_STRATEGY.md +++ b/docs/CI_STRATEGY.md @@ -1,3 +1,13 @@ +--- +title: CI/CD Strategy +description: Strategy, matrices, and gating for continuous integration. +audience: [contributors, developers] +domain: [quality] +tags: [ci, matrices] +status: stable +last_updated: 2025-09-15 +--- + # CI/CD Strategy ## Overview diff --git a/docs/DEV_SETUP.md b/docs/DEV_SETUP.md index 88fb97fc..494fc3bb 100644 --- a/docs/DEV_SETUP.md +++ b/docs/DEV_SETUP.md @@ -1,3 +1,13 @@ +--- +title: Developer Setup Guide +description: Required tools and environment configuration for contributors. +audience: [contributors, developers] +domain: [operations] +tags: [dev-setup, clang-tidy] +status: stable +last_updated: 2025-09-15 +--- + # Developer Setup Guide ## Required Tools diff --git a/docs/PRDs/PRD-co-thought-mcp-service.md b/docs/PRDs/PRD-co-thought-mcp-service.md index 559860ad..9e5a5357 100644 --- a/docs/PRDs/PRD-co-thought-mcp-service.md +++ b/docs/PRDs/PRD-co-thought-mcp-service.md @@ -1,3 +1,13 @@ +--- +title: PRD — Co‑Thought MCP Service (Local Tools Integration) +description: Local-only service for tools/agents to read/write edges and query journal/cache. +audience: [contributors, developers] +domain: [project] +tags: [PRD, MCP, AI] +status: draft +last_updated: 2025-09-15 +--- + # PRD: Co‑Thought MCP Service (Local Tools Integration) Table of Contents diff --git a/docs/PRDs/PRD-git-mind-semantics-time-travel-prototype.md b/docs/PRDs/PRD-git-mind-semantics-time-travel-prototype.md index d3e64673..70321393 100644 --- a/docs/PRDs/PRD-git-mind-semantics-time-travel-prototype.md +++ b/docs/PRDs/PRD-git-mind-semantics-time-travel-prototype.md @@ -1,3 +1,13 @@ +--- +title: PRD — First‑Class, Time‑Travel‑Safe Semantics +description: Requirements for semantics stored in Git with branch and time-travel correctness. +audience: [contributors, developers] +domain: [project, architecture] +tags: [PRD, semantics] +status: draft +last_updated: 2025-09-15 +--- + # PRD: First‑Class, Time‑Travel‑Safe Semantics for git‑mind Table of Contents diff --git a/docs/README.md b/docs/README.md index f59acdea..cce9e245 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,3 +1,13 @@ +--- +title: Docs Index +description: Index of documentation with stable links and key entry points. +audience: [all] +domain: [project] +tags: [index, docs] +status: stable +last_updated: 2025-09-15 +--- + # docs/ (Index and Structure) Table of Contents diff --git a/docs/adr/0001-first-class-semantics.md b/docs/adr/0001-first-class-semantics.md index d85d16c1..452a62e3 100644 --- a/docs/adr/0001-first-class-semantics.md +++ b/docs/adr/0001-first-class-semantics.md @@ -1,4 +1,14 @@ +--- +title: ADR 0001 — First‑Class, Time‑Travel‑Safe Semantics +description: Treat `type_name` and `lane_name` as authoritative strings; derive IDs only for performance. +audience: [developers] +domain: [architecture] +tags: [ADR, semantics] +status: proposed +last_updated: 2025-09-15 +--- + # ADR 0001: First‑Class, Time‑Travel‑Safe Semantics (Names as Truth) Table of Contents diff --git a/docs/adr/0002-docs-reorganization.md b/docs/adr/0002-docs-reorganization.md index 246cdb44..196caf2f 100644 --- a/docs/adr/0002-docs-reorganization.md +++ b/docs/adr/0002-docs-reorganization.md @@ -1,3 +1,13 @@ +--- +title: ADR 0002 — Documentation Reorganization and Planning Structure +description: Establish stable docs hubs, add indexes, and improve cross-linking. +audience: [contributors] +domain: [project] +tags: [ADR, docs] +status: accepted +last_updated: 2025-09-15 +--- + # ADR 0002: Documentation Reorganization and Planning Structure Table of Contents diff --git a/docs/api/gitmind-api-reference.md b/docs/api/gitmind-api-reference.md index abcf4cd8..4b222b0a 100644 --- a/docs/api/gitmind-api-reference.md +++ b/docs/api/gitmind-api-reference.md @@ -1,3 +1,13 @@ +--- +title: git-mind C API Reference +description: Reference for public C API types and functions. +audience: [developers] +domain: [api] +tags: [api, c] +status: draft +last_updated: 2025-09-15 +--- + # git-mind C API Reference Complete API documentation for the git-mind library (gitmind_lib.h). diff --git a/docs/architecture/MIGRATION_PHILOSOPHY.md b/docs/architecture/MIGRATION_PHILOSOPHY.md index 91173eb3..803e798b 100644 --- a/docs/architecture/MIGRATION_PHILOSOPHY.md +++ b/docs/architecture/MIGRATION_PHILOSOPHY.md @@ -1,5 +1,14 @@ +--- +title: Migration Philosophy +description: Strict-then-sustainable approach to quality during and after migration. +audience: [developers] +domain: [architecture] +tags: [migration, quality] +status: stable +last_updated: 2025-09-15 +--- # Migration Philosophy: From Chaos to Excellence diff --git a/docs/architecture/MODULAR_RESTRUCTURE_PLAN.md b/docs/architecture/MODULAR_RESTRUCTURE_PLAN.md index 8bf6abf4..85b5c3e0 100644 --- a/docs/architecture/MODULAR_RESTRUCTURE_PLAN.md +++ b/docs/architecture/MODULAR_RESTRUCTURE_PLAN.md @@ -1,5 +1,14 @@ +--- +title: Modular Architecture Restructure Plan +description: Plan to evolve toward a modular, library-first system with a single-header API. +audience: [developers] +domain: [architecture] +tags: [modular, library, headers] +status: draft +last_updated: 2025-09-15 +--- # Modular Architecture Restructure Plan diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 2e58c02a..4973badd 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -1,5 +1,14 @@ +--- +title: Architecture Index +description: Entry point to git-mind’s architecture docs and core systems. +audience: [developers] +domain: [architecture] +tags: [architecture, journal, cache, attribution] +status: stable +last_updated: 2025-09-15 +--- # git-mind Architecture Documentation diff --git a/docs/architecture/System_Architecture.md b/docs/architecture/System_Architecture.md index bf6bf46d..2483a560 100644 --- a/docs/architecture/System_Architecture.md +++ b/docs/architecture/System_Architecture.md @@ -1,3 +1,13 @@ +--- +title: System Architecture +description: High-level view of git-mind components and interactions. +audience: [developers] +domain: [architecture] +tags: [system, overview] +status: draft +last_updated: 2025-09-15 +--- + # System Architecture Table of Contents diff --git a/docs/architecture/attribution-integration-guide.md b/docs/architecture/attribution-integration-guide.md index e092e32e..ecfddd1d 100644 --- a/docs/architecture/attribution-integration-guide.md +++ b/docs/architecture/attribution-integration-guide.md @@ -1,5 +1,14 @@ +--- +title: Attribution System Integration Guide +description: How to adopt attribution lanes and metadata in existing modules and CLI commands. +audience: [developers] +domain: [architecture] +tags: [attribution, integration, cli] +status: stable +last_updated: 2025-09-15 +--- # Attribution System Integration Guide diff --git a/docs/architecture/attribution-system.md b/docs/architecture/attribution-system.md index 5c584e50..61c1119d 100644 --- a/docs/architecture/attribution-system.md +++ b/docs/architecture/attribution-system.md @@ -1,5 +1,14 @@ +--- +title: Attribution System Architecture +description: Human + AI attribution model for edges with lanes, filters, and collaboration flows. +audience: [developers] +domain: [architecture] +tags: [attribution, lanes, filters, ai] +status: stable +last_updated: 2025-09-15 +--- # Attribution System Architecture diff --git a/docs/architecture/attribution-use-cases.md b/docs/architecture/attribution-use-cases.md index 471a31f8..469eb65f 100644 --- a/docs/architecture/attribution-use-cases.md +++ b/docs/architecture/attribution-use-cases.md @@ -1,5 +1,14 @@ +--- +title: Attribution System Use Cases +description: Scenarios demonstrating lanes, filters, and human+AI collaboration. +audience: [developers] +domain: [architecture] +tags: [attribution, collaboration] +status: stable +last_updated: 2025-09-15 +--- # Attribution System Use Cases diff --git a/docs/architecture/augments-system.md b/docs/architecture/augments-system.md index 069205ec..05fa9dcf 100644 --- a/docs/architecture/augments-system.md +++ b/docs/architecture/augments-system.md @@ -1,3 +1,13 @@ +--- +title: AUGMENTS System Architecture +description: System for automatically linking content evolution with AUGMENTS edges. +audience: [developers] +domain: [architecture] +tags: [augments, hooks] +status: draft +last_updated: 2025-09-15 +--- + # AUGMENTS System Architecture Table of Contents diff --git a/docs/architecture/bitmap-cache-design.md b/docs/architecture/bitmap-cache-design.md index cfcbb085..90a7fe9c 100644 --- a/docs/architecture/bitmap-cache-design.md +++ b/docs/architecture/bitmap-cache-design.md @@ -1,3 +1,13 @@ +--- +title: Bitmap Cache Design +description: High-performance query layer using Roaring Bitmaps for compressed sets and fast operations. +audience: [developers] +domain: [architecture] +tags: [cache, roaring, performance] +status: stable +last_updated: 2025-09-15 +--- + # Bitmap Cache Design 🦁⚡ ## High-Performance Query Layer for git-mind diff --git a/docs/architecture/cache-migration-oid-only.md b/docs/architecture/cache-migration-oid-only.md index ea814b1e..219caf87 100644 --- a/docs/architecture/cache-migration-oid-only.md +++ b/docs/architecture/cache-migration-oid-only.md @@ -1,3 +1,13 @@ +--- +title: Cache Migration — OID-Only +description: Migration to OID-only cache format with stable ref naming and legacy fallback. +audience: [developers] +domain: [architecture] +tags: [cache, oid, migration] +status: stable +last_updated: 2025-09-15 +--- + # Cache Migration: OID-Only Format and Stable Refs Table of Contents diff --git a/docs/architecture/deprecations/legacy-sha-fields.md b/docs/architecture/deprecations/legacy-sha-fields.md index fd853a88..4f2963ec 100644 --- a/docs/architecture/deprecations/legacy-sha-fields.md +++ b/docs/architecture/deprecations/legacy-sha-fields.md @@ -1,3 +1,13 @@ +--- +title: Deprecation — Legacy SHA-1 Byte Arrays in Edges +description: Plan to remove SHA-1 specific arrays in favor of OID-only APIs and storage. +audience: [developers] +domain: [architecture] +tags: [deprecation, oid] +status: planned +last_updated: 2025-09-15 +--- + # Deprecation Notice: Legacy SHA-1 Byte Arrays in Edges Table of Contents diff --git a/docs/architecture/journal-architecture-pivot.md b/docs/architecture/journal-architecture-pivot.md index 08628325..61f315c9 100644 --- a/docs/architecture/journal-architecture-pivot.md +++ b/docs/architecture/journal-architecture-pivot.md @@ -1,3 +1,13 @@ +--- +title: Journal Architecture Pivot +description: Edge-journal commits with branch-aware graphs; the final architecture for storing semantics in Git. +audience: [developers] +domain: [architecture] +tags: [journal, cbor, refs] +status: stable +last_updated: 2025-09-15 +--- + # Project: No Tux Given 🐧⚡ ## The git-mind Final Architecture diff --git a/docs/architecture/tombstone-visual.md b/docs/architecture/tombstone-visual.md index d9144a66..780df210 100644 --- a/docs/architecture/tombstone-visual.md +++ b/docs/architecture/tombstone-visual.md @@ -1,3 +1,13 @@ +--- +title: Visual Guide — Tombstones +description: Visual explanation for tombstoned edges and why deletions preserve history. +audience: [developers] +domain: [architecture] +tags: [tombstone, semantics] +status: draft +last_updated: 2025-09-15 +--- + # Visual Guide: How Tombstones Work Table of Contents diff --git a/docs/charter/Project_Charter.md b/docs/charter/Project_Charter.md index 4345e0c1..47fcbce7 100644 --- a/docs/charter/Project_Charter.md +++ b/docs/charter/Project_Charter.md @@ -1,3 +1,13 @@ +--- +title: Project Charter +description: Goals, stakeholders, and success metrics for git-mind. +audience: [all] +domain: [project] +tags: [charter] +status: stable +last_updated: 2025-09-15 +--- + # Project Charter Table of Contents diff --git a/docs/cli/README.md b/docs/cli/README.md index 8a092aed..19f147d6 100644 --- a/docs/cli/README.md +++ b/docs/cli/README.md @@ -1,5 +1,14 @@ +--- +title: git-mind CLI Reference +description: Overview and command reference for the git-mind CLI. +audience: [users, developers] +domain: [cli] +tags: [cli] +status: stable +last_updated: 2025-09-15 +--- # git-mind Command Reference diff --git a/docs/cli/combined_markdown.md b/docs/cli/combined_markdown.md index 7feb5d1f..a85c62f9 100644 --- a/docs/cli/combined_markdown.md +++ b/docs/cli/combined_markdown.md @@ -1,3 +1,13 @@ +--- +title: CLI Combined Reference +description: Combined CLI reference content for convenience and offline browsing. +audience: [users, developers] +domain: [cli] +tags: [cli] +status: draft +last_updated: 2025-09-15 +--- + # README.md diff --git a/docs/cli/gitmind-cache-rebuild.md b/docs/cli/gitmind-cache-rebuild.md index 02b4a006..934683db 100644 --- a/docs/cli/gitmind-cache-rebuild.md +++ b/docs/cli/gitmind-cache-rebuild.md @@ -1,5 +1,14 @@ +--- +title: git-mind cache-rebuild +description: Rebuild the on-disk cache from the journal. +audience: [users, developers] +domain: [cli] +tags: [cli, cache] +status: stable +last_updated: 2025-09-15 +--- # git-mind cache-rebuild diff --git a/docs/cli/gitmind-install-hooks.md b/docs/cli/gitmind-install-hooks.md index 242e338b..0db33d8f 100644 --- a/docs/cli/gitmind-install-hooks.md +++ b/docs/cli/gitmind-install-hooks.md @@ -1,5 +1,14 @@ +--- +title: git-mind install-hooks +description: Install Git hooks to automatically capture certain semantic edges. +audience: [users, developers] +domain: [cli] +tags: [cli, hooks] +status: stable +last_updated: 2025-09-15 +--- # git-mind install-hooks diff --git a/docs/cli/gitmind-link.md b/docs/cli/gitmind-link.md index ff771e9b..37f50dac 100644 --- a/docs/cli/gitmind-link.md +++ b/docs/cli/gitmind-link.md @@ -1,5 +1,14 @@ +--- +title: git-mind link +description: Create a semantic connection between two paths. +audience: [users, developers] +domain: [cli] +tags: [cli, link] +status: stable +last_updated: 2025-09-15 +--- # git-mind link diff --git a/docs/cli/gitmind-list.md b/docs/cli/gitmind-list.md index 01d5c05e..7cc99051 100644 --- a/docs/cli/gitmind-list.md +++ b/docs/cli/gitmind-list.md @@ -1,5 +1,14 @@ +--- +title: git-mind list +description: Query and explore semantic connections. +audience: [users, developers] +domain: [cli] +tags: [cli, list] +status: stable +last_updated: 2025-09-15 +--- # git-mind list diff --git a/docs/cli/gitmind.md b/docs/cli/gitmind.md index 68315ebc..f0970c6f 100644 --- a/docs/cli/gitmind.md +++ b/docs/cli/gitmind.md @@ -1,6 +1,16 @@ +--- +title: git-mind (command) +description: Top-level CLI: usage, global flags, and safety guard behavior. +audience: [users, developers] +domain: [cli] +tags: [cli] +status: stable +last_updated: 2025-09-15 +--- + # git-mind > _"Remember who you are."_ - Mufasa diff --git a/docs/deployment/Deployment.md b/docs/deployment/Deployment.md index 42dc0ad5..29dfa70f 100644 --- a/docs/deployment/Deployment.md +++ b/docs/deployment/Deployment.md @@ -1,3 +1,13 @@ +--- +title: Deployment and Operations +description: CI/CD pipeline, environments, rollback, and monitoring. +audience: [contributors, developers] +domain: [operations] +tags: [deployment, ci] +status: draft +last_updated: 2025-09-15 +--- + # Deployment and Operations Table of Contents diff --git a/docs/operations/Environment_Variables.md b/docs/operations/Environment_Variables.md index 4672b42f..173f94c4 100644 --- a/docs/operations/Environment_Variables.md +++ b/docs/operations/Environment_Variables.md @@ -1,3 +1,13 @@ +--- +title: Environment Variables +description: Environment variables affecting build, CI, runtime, and tests. +audience: [developers] +domain: [operations] +tags: [environment, ci, runtime, cli] +status: stable +last_updated: 2025-09-15 +--- + # Environment Variables This page lists environment variables that influence git‑mind builds, tests, and runtime behavior. diff --git a/docs/quality/Markdown_Style_Guide.md b/docs/quality/Markdown_Style_Guide.md index 1d9cdd4e..baa3d195 100644 --- a/docs/quality/Markdown_Style_Guide.md +++ b/docs/quality/Markdown_Style_Guide.md @@ -1,3 +1,13 @@ +--- +title: Markdown Style Guide +description: Project-wide rules for formatting Markdown and using markdownlint. +audience: [contributors] +domain: [quality] +tags: [markdown, lint] +status: stable +last_updated: 2025-09-15 +--- + # Markdown Style Guide Table of Contents diff --git a/docs/quality/SOLID_DRY_REPORT.md b/docs/quality/SOLID_DRY_REPORT.md index aa368acb..a43c1af7 100644 --- a/docs/quality/SOLID_DRY_REPORT.md +++ b/docs/quality/SOLID_DRY_REPORT.md @@ -1,3 +1,13 @@ +--- +title: SOLID/DRY Compliance Report +description: Assessment of the codebase against SOLID and DRY with remediation guidance. +audience: [contributors, developers] +domain: [quality] +tags: [solid, dry] +status: draft +last_updated: 2025-09-15 +--- + # 🚨 SOLID/DRY Compliance Report - CRITICAL SECURITY ASSESSMENT Table of Contents diff --git a/docs/quality/TIDY_CLANG_CRUSADE.md b/docs/quality/TIDY_CLANG_CRUSADE.md index fe7299c7..ad023f34 100644 --- a/docs/quality/TIDY_CLANG_CRUSADE.md +++ b/docs/quality/TIDY_CLANG_CRUSADE.md @@ -1,3 +1,13 @@ +--- +title: The Great Clang-Tidy Crusade +description: Tracking clang-tidy issues and progress toward zero warnings. +audience: [contributors, developers] +domain: [quality] +tags: [clang-tidy] +status: draft +last_updated: 2025-09-15 +--- + # 🚨 The Great Clang-Tidy Crusade Table of Contents diff --git a/docs/quality/local-ci-parity.md b/docs/quality/local-ci-parity.md index 80c7f0c6..4706bf9b 100644 --- a/docs/quality/local-ci-parity.md +++ b/docs/quality/local-ci-parity.md @@ -1,3 +1,13 @@ +--- +title: Local CI Parity (Docker) +description: How to run CI-equivalent builds and lint locally using project Docker images. +audience: [contributors, developers] +domain: [quality] +tags: [docker, ci, clang-tidy] +status: stable +last_updated: 2025-09-15 +--- + # Local CI Parity (Docker) Table of Contents diff --git a/docs/quality/static-analysis-guide.md b/docs/quality/static-analysis-guide.md index 180173bd..209df6f0 100644 --- a/docs/quality/static-analysis-guide.md +++ b/docs/quality/static-analysis-guide.md @@ -1,3 +1,13 @@ +--- +title: Static Analysis Tools for git-mind +description: Overview of clang-tidy and related tools for static analysis in this repo. +audience: [contributors, developers] +domain: [quality] +tags: [clang-tidy, static-analysis] +status: draft +last_updated: 2025-09-15 +--- + # Static Analysis Tools for Git-Mind Table of Contents diff --git a/docs/quality/tools-vs-custom-checks.md b/docs/quality/tools-vs-custom-checks.md index c07f74e6..df073219 100644 --- a/docs/quality/tools-vs-custom-checks.md +++ b/docs/quality/tools-vs-custom-checks.md @@ -1,3 +1,13 @@ +--- +title: Standard Tools vs Custom Checks +description: Replace bespoke linters with robust, configurable standard tools. +audience: [contributors, developers] +domain: [quality] +tags: [lint, tooling] +status: stable +last_updated: 2025-09-15 +--- + # Standard Tools vs Custom Checks Table of Contents diff --git a/docs/requirements/Requirements.md b/docs/requirements/Requirements.md index fd465bb8..c56f1605 100644 --- a/docs/requirements/Requirements.md +++ b/docs/requirements/Requirements.md @@ -1,3 +1,13 @@ +--- +title: Requirements +description: Functional and non-functional requirements for git-mind. +audience: [contributors, developers] +domain: [project] +tags: [requirements] +status: draft +last_updated: 2025-09-15 +--- + # Requirements Table of Contents diff --git a/docs/specs/Technical_Specifications.md b/docs/specs/Technical_Specifications.md index 0d086bea..1cab40a5 100644 --- a/docs/specs/Technical_Specifications.md +++ b/docs/specs/Technical_Specifications.md @@ -1,3 +1,13 @@ +--- +title: Technical Specifications +description: Detailed specifications for semantics, cache integration, and advice. +audience: [developers] +domain: [architecture] +tags: [specs] +status: draft +last_updated: 2025-09-15 +--- + # Technical Specifications Table of Contents diff --git a/docs/testing/Test_Plan.md b/docs/testing/Test_Plan.md index 0b0584fb..519c896a 100644 --- a/docs/testing/Test_Plan.md +++ b/docs/testing/Test_Plan.md @@ -1,3 +1,13 @@ +--- +title: Test Plan +description: Strategy and structure for unit, integration, and E2E testing. +audience: [developers, contributors] +domain: [testing] +tags: [testing] +status: draft +last_updated: 2025-09-15 +--- + # Test Plan Table of Contents diff --git a/tools/changelog/add_entry.py b/tools/changelog/add_entry.py new file mode 100644 index 00000000..41975b07 --- /dev/null +++ b/tools/changelog/add_entry.py @@ -0,0 +1,78 @@ +#!/usr/bin/env python3 +import argparse +import datetime as dt +import os +import subprocess +import sys + +CHANGELOG = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(__file__))), 'CHANGELOG.md') + +def git_short_sha(): + try: + out = subprocess.check_output(['git', 'rev-parse', '--short', 'HEAD'], stderr=subprocess.DEVNULL) + return out.decode().strip() + except Exception: + return 'unknown' + +def ensure_date_section(lines, date_str): + header = f"## {date_str}\n" + if any(l.strip() == header.strip() for l in lines): + return lines + # Insert date header under "## Daily Dev Log" section or append at end + new_lines = [] + inserted = False + in_daily = False + for i, line in enumerate(lines): + new_lines.append(line) + if line.startswith('## Daily Dev Log'): + in_daily = True + continue + if in_daily and not inserted: + # next blank line is a good insertion point + if line.strip() == '' and i + 1 < len(lines): + new_lines.append(header) + new_lines.append('\n') + inserted = True + in_daily = False + if not inserted: + if not new_lines or new_lines[-1].strip() != '': + new_lines.append('\n') + new_lines.append(header) + new_lines.append('\n') + return new_lines + +def main(): + parser = argparse.ArgumentParser(description='Append a daily dev log entry to CHANGELOG.md') + parser.add_argument('-m', '--message', required=True, help='One-liner description') + parser.add_argument('-n', '--note', default=None, help='Optional note block to add') + args = parser.parse_args() + + now = dt.datetime.now() + date_str = now.strftime('%Y-%m-%d') + time_str = now.strftime('%H:%M') + sha = git_short_sha() + + if not os.path.exists(CHANGELOG): + print(f"CHANGELOG not found at {CHANGELOG}", file=sys.stderr) + return 1 + + with open(CHANGELOG, 'r', encoding='utf-8') as f: + lines = f.readlines() + + lines = ensure_date_section(lines, date_str) + + entry = f"- @ {time_str} – `{sha}` {args.message}\n" + lines.append(entry) + if args.note: + lines.append('\n') + lines.append('> [!note]\n') + lines.append(f"> {args.note}\n") + lines.append('\n') + + with open(CHANGELOG, 'w', encoding='utf-8') as f: + f.writelines(lines) + return 0 + +if __name__ == '__main__': + sys.exit(main()) + diff --git a/tools/docs/check_frontmatter.py b/tools/docs/check_frontmatter.py new file mode 100644 index 00000000..1f0e8ecf --- /dev/null +++ b/tools/docs/check_frontmatter.py @@ -0,0 +1,147 @@ +#!/usr/bin/env python3 +""" +Check that selected documentation Markdown files contain a YAML frontmatter block +with required keys. Designed to be simple and fast, matching our repo layout. + +Usage: + python3 tools/docs/check_frontmatter.py [--base docs] + +Exit codes: + 0 = all good + 1 = problems found +""" + +from __future__ import annotations +import argparse +import pathlib +import sys +from typing import List, Tuple + + +REQUIRED_KEYS = [ + "title", + "description", + "audience", + "domain", + "tags", + "status", +] + +# Directories to include for enforcement +INCLUDE_DIRS = { + "docs/architecture": True, + "docs/cli": True, + "docs/operations": True, + "docs/quality": True, + "docs/testing": True, + "docs/PRDs": True, + "docs/adr": True, + "docs/requirements": True, + "docs/deployment": True, + "docs/charter": True, + "docs/api": True, + "docs/risk": True, + "docs/specs": True, +} + +# Specific files to always include (live at docs root) +ALWAYS_INCLUDE = { + "docs/README.md", + "docs/install.md", + "docs/tutorial.md", + "docs/philosophy.md", + "docs/TECHNICAL.md", + "docs/roadmap.md", + "docs/operations/Environment_Variables.md", +} + +# Subtrees to exclude (journals, brainstorming, reviews, etc.) +EXCLUDE_DIR_PREFIXES = ( + "docs/enforcer/", + "docs/sitrep/", + "docs/wish-list-features/", + "docs/talk-shop/", + "docs/audits/", + "docs/code-review/", + "docs/code-reviews/", + "docs/hn-demo/", + "docs/planning/", +) + + +def should_check(path: pathlib.Path) -> bool: + p = str(path).replace("\\", "/") + if not p.endswith(".md"): + return False + for pref in EXCLUDE_DIR_PREFIXES: + if p.startswith(pref): + return False + # Enforce only for included dirs + # Always include select root docs + if p in ALWAYS_INCLUDE: + return True + for inc in INCLUDE_DIRS.keys(): + if p.startswith(inc + "/") or p == inc + ".md": + return True + return False + + +def parse_frontmatter(text: str) -> Tuple[bool, List[str]]: + """Return (ok, missing_keys). Accepts HTML comments or blank lines before frontmatter. + Frontmatter format: + ---\n + key: value\n + ...\n + --- + """ + lines = text.splitlines() + i = 0 + # Skip leading blank and HTML comment lines + while i < len(lines) and (not lines[i].strip() or lines[i].lstrip().startswith(" +--- +title: Adult Swim Notes +description: Informal notes and experimental thoughts captured during exploration phases. +audience: [contributors] +domain: [project] +tags: [notes] +status: archive +last_updated: 2025-09-15 +--- + # 🏊 Adult Swim: Deep End Memory Pool Opportunities _"No floaties allowed - this is where we optimize HARD"_ @@ -102,15 +112,4 @@ For a repository with 100k edges: - Cache efficiency: 5x improvement - Allocation overhead: 90% reduction ---- - _"Come to the deep end... the water's fine!"_ 🏊‍♂️ ---- -title: Adult Swim Notes -description: Informal notes and experimental thoughts captured during exploration phases. -audience: [contributors] -domain: [project] -tags: [notes] -status: archive -last_updated: 2025-09-15 ---- diff --git a/docs/api/gitmind-api-reference.md b/docs/api/gitmind-api-reference.md index 4b222b0a..fef5f292 100644 --- a/docs/api/gitmind-api-reference.md +++ b/docs/api/gitmind-api-reference.md @@ -6,6 +6,7 @@ domain: [api] tags: [api, c] status: draft last_updated: 2025-09-15 +api_version: "1.0.0" --- # git-mind C API Reference diff --git a/docs/architecture/bitmap-cache-design.md b/docs/architecture/bitmap-cache-design.md index 90a7fe9c..227a354a 100644 --- a/docs/architecture/bitmap-cache-design.md +++ b/docs/architecture/bitmap-cache-design.md @@ -20,7 +20,7 @@ Table of Contents - [Query Path](#overview) __Date__: June 2025 -__Status__: IN PROGRESS +__Status__: stable __Goal__: O(log N) queries on millions of edges --- diff --git a/docs/charter/Project_Charter.md b/docs/charter/Project_Charter.md index 47fcbce7..fb72526a 100644 --- a/docs/charter/Project_Charter.md +++ b/docs/charter/Project_Charter.md @@ -10,7 +10,7 @@ last_updated: 2025-09-15 # Project Charter -Table of Contents +## Table of Contents - [Executive Summary](#executive-summary) - [Goals and Objectives](#goals-and-objectives) diff --git a/docs/cli/combined_markdown.md b/docs/cli/combined_markdown.md index a85c62f9..8e9bb3ad 100644 --- a/docs/cli/combined_markdown.md +++ b/docs/cli/combined_markdown.md @@ -6,6 +6,7 @@ domain: [cli] tags: [cli] status: draft last_updated: 2025-09-15 +aggregate: true --- # README.md diff --git a/docs/cli/gitmind-install-hooks.md b/docs/cli/gitmind-install-hooks.md index 0db33d8f..b9f51766 100644 --- a/docs/cli/gitmind-install-hooks.md +++ b/docs/cli/gitmind-install-hooks.md @@ -1,5 +1,3 @@ - - --- title: git-mind install-hooks description: Install Git hooks to automatically capture certain semantic edges. @@ -10,6 +8,9 @@ status: stable last_updated: 2025-09-15 --- + + + # git-mind install-hooks > _"The past can hurt. But the way I see it, you can either run from it or learn from it."_ - Rafiki diff --git a/docs/cli/gitmind-list.md b/docs/cli/gitmind-list.md index 7cc99051..128847b8 100644 --- a/docs/cli/gitmind-list.md +++ b/docs/cli/gitmind-list.md @@ -1,5 +1,3 @@ - - --- title: git-mind list description: Query and explore semantic connections. @@ -10,6 +8,9 @@ status: stable last_updated: 2025-09-15 --- + + + # git-mind list > _"Look beyond what you see."_ - Rafiki diff --git a/docs/code-reviews/PR169/e4f3f906eb454cb103eb8cc6899df8dfbf6e2349.md b/docs/code-reviews/PR169/e4f3f906eb454cb103eb8cc6899df8dfbf6e2349.md index 70a053b5..69e19362 100644 --- a/docs/code-reviews/PR169/e4f3f906eb454cb103eb8cc6899df8dfbf6e2349.md +++ b/docs/code-reviews/PR169/e4f3f906eb454cb103eb8cc6899df8dfbf6e2349.md @@ -25,7 +25,7 @@ Please use the following template to record your acceptance. ```markdown -> [!note]- **Acceepted** +> [!note]- **Accepted** > | Confidence | Remarks | > |------------|---------| > | {confidence_score_out_of_10} | {confidence_rationale} | @@ -100,7 +100,7 @@ optionally followed by .md, e.g. use grep -iqE changelog filename variants. ``` -> [!note]- **Acceepted** +> [!note]- **Accepted** > | Confidence | Remarks | > |------------|---------| > | 9/10 | Regex and quoting are straightforward; covers common variants. | @@ -133,7 +133,7 @@ the declarations and include guards), ensuring the function prototype and any future declarations are enclosed. ``` -> [!note]- **Acceepted** +> [!note]- **Accepted** > | Confidence | Remarks | > |------------|---------| > | 10/10 | Standard public header hygiene. | @@ -170,7 +170,7 @@ silently, and update comments accordingly. Ensure the chosen approach is reflected in the header comments and release notes if SONAME is bumped. ``` -> [!note]- **Acceepted** +> [!note]- **Accepted** > | Confidence | Remarks | > |------------|---------| > | 8/10 | Moving field to tail preserves layout for existing users; internal code updated accordingly. | @@ -203,7 +203,7 @@ core/src/cache/tree_builder.c:180 — char full_path[GM_PATH_MAX * 2]; Replace w No PATH_MAX usages found. The only other large static buffer is test-only: core/tests/unit/test_sha256.c:151 (char large_data[8192]). ``` -> [!note]- **Acceepted** +> [!note]- **Accepted** > | Confidence | Remarks | > |------------|---------| > | 10/10 | Fixed all occurrences; tests pass. | @@ -237,7 +237,7 @@ chosen approach and ensure the function returns GM_INVALID_ARG on overflow instead of performing a truncated copy. ``` -> [!note]- **Acceepted** +> [!note]- **Accepted** > | Confidence | Remarks | > |------------|---------| > | 9/10 | Early return on overflow improves correctness; callers can react. | @@ -268,7 +268,7 @@ buffer sizing, replacing any GM_PATH_MAX*2 instances with GM_PATH_MAX and ensure any related uses/strncpy/strncat calls respect GM_PATH_MAX bounds. ``` -> [!note]- **Acceepted** +> [!note]- **Accepted** > | Confidence | Remarks | > |------------|---------| > | 10/10 | Applied consistently; code compiles and tests pass. | @@ -302,7 +302,7 @@ avoid continuing with truncated paths) so the caller can handle the failure rather than silently proceeding with truncated strings. ``` -> [!note]- **Acceepted** +> [!note]- **Accepted** > | Confidence | Remarks | > |------------|---------| > | 9/10 | Path truncation should fail, not silently proceed. | @@ -333,7 +333,7 @@ conventions and prevent accidental local-header resolution, ensuring the compiler searches system/include paths first. ``` -> [!note]- **Acceepted** +> [!note]- **Accepted** > | Confidence | Remarks | > |------------|---------| > | 10/10 | Style and correctness improvement. | @@ -354,7 +354,7 @@ compiler searches system/include paths first. > > None -### {feedback_item_title} +### Zeroing and error mapping in gm_build_ref ```text In core/src/util/ref.c around lines 18-22 (and similarly for lines 26-31), the @@ -367,9 +367,29 @@ success. Apply the same zeroing-and-snprintf-result-mapping changes to the other function at lines 26-31. ``` -{response} +> [!note]- **Accepted** +> | Confidence | Remarks | +> |------------|---------| +> | 9/10 | Defensive zeroing and precise errno mapping reduce footguns. | +> +> ## Lesson Learned +> +> Always clear outputs on error paths and translate formatting return codes precisely to our error space. +> +> ## What did you do to address this feedback? +> +> - In `core/src/util/ref.c`, set `out[0]='\0'` on entry and before writes. +> - Mapped `gm_snprintf` return values: `<0 => GM_ERR_UNKNOWN`, `>= out_sz => GM_ERR_BUFFER_TOO_SMALL`, else success. +> +> ## Regression Avoidance Strategy +> +> - Keep ref helpers self-contained with strict argument checks; unit test for small buffers can be added alongside ref_utils. +> +> ## Notes +> +> None -### {feedback_item_title} +### Fix misleading comment in test_edge_oid_fallback ```text In core/tests/unit/test_edge_oid_fallback.c around lines 15 to 25, the leading @@ -380,9 +400,28 @@ with zero OIDs the fallback path makes the edges equal, keeping the rest of the code and assertions unchanged. ``` -{response} +> [!note]- **Accepted** +> | Confidence | Remarks | +> |------------|---------| +> | 10/10 | Comment fix matches actual code path. | +> +> ## Lesson Learned +> +> Keep comments synchronized with tests to avoid misreads about intent. +> +> ## What did you do to address this feedback? +> +> - Updated the leading comment to reflect identical legacy bytes and zero OIDs. +> +> ## Regression Avoidance Strategy +> +> - Prefer assertions and helper builders that make test intent explicit. +> +> ## Notes +> +> None -### {feedback_item_title} +### Add api_version to API reference front matter ```text In docs/api/gitmind-api-reference.md around lines 1 to 9, the front matter lacks @@ -393,9 +432,28 @@ the value uses a consistent format and update any downstream docs or release process that should consume this field. ``` -{response} +> [!note]- **Accepted** +> | Confidence | Remarks | +> |------------|---------| +> | 10/10 | Clear versioning signal for tooling. | +> +> ## Lesson Learned +> +> Front matter is a contract for docs tooling; version fields should be explicit. +> +> ## What did you do to address this feedback? +> +> - Added `api_version: "1.0.0"` to `docs/api/gitmind-api-reference.md` front matter. +> +> ## Regression Avoidance Strategy +> +> - Template future API docs with a required api_version field. +> +> ## Notes +> +> None -### {feedback_item_title} +### Align bitmap-cache-design status in front matter and body ```text In docs/architecture/bitmap-cache-design.md around lines 7 to 8, the YAML @@ -406,9 +464,28 @@ PROGRESS"), save the file, and then run make md-lint and the docs checks to verify the change. ``` -{response} +> [!note]- **Accepted** +> | Confidence | Remarks | +> |------------|---------| +> | 10/10 | Simple consistency fix. | +> +> ## Lesson Learned +> +> Duplicate status fields can drift; prefer single source of truth or keep them consistent. +> +> ## What did you do to address this feedback? +> +> - Updated body status to `stable` to match front matter. +> +> ## Regression Avoidance Strategy +> +> - Rely on docs lint to flag mismatches; minimize status duplication. +> +> ## Notes +> +> None -### {feedback_item_title} +### Promote Project Charter TOC heading to H2 ```text In docs/charter/Project_Charter.md around line 13, the plain "Table of Contents" @@ -418,9 +495,28 @@ there's a blank line after the heading, and save the file so the docs tooling recognizes it as a level-2 section. ``` -{response} +> [!note]- **Accepted** +> | Confidence | Remarks | +> |------------|---------| +> | 10/10 | Markdownlint/TOC compliant. | +> +> ## Lesson Learned +> +> Follow site conventions for TOC headings to keep generators happy. +> +> ## What did you do to address this feedback? +> +> - Changed "Table of Contents" to "## Table of Contents". +> +> ## Regression Avoidance Strategy +> +> - Docs lint is wired in CI to enforce. +> +> ## Notes +> +> None -### {feedback_item_title} +### Mark combined CLI page with aggregate flag ```text In docs/cli/combined_markdown.md around lines 1 to 9, this page should be marked @@ -430,9 +526,28 @@ frontmatter block so tools can detect it's a combined/aggregate page while remaining ignored by most parsers. ``` -{response} +> [!note]- **Accepted** +> | Confidence | Remarks | +> |------------|---------| +> | 10/10 | Harmless metadata to guide tooling. | +> +> ## Lesson Learned +> +> Aggregate pages should be declared so that downstream tools can treat them specially. +> +> ## What did you do to address this feedback? +> +> - Added `aggregate: true` to `docs/cli/combined_markdown.md` front matter. +> +> ## Regression Avoidance Strategy +> +> - Documented flag in internal docs tooling. +> +> ## Notes +> +> None -### {feedback_item_title} +### Move license comments below front matter in cli docs ```text In docs/cli/gitmind-install-hooks.md around lines 3 to 11, there are two HTML @@ -445,9 +560,28 @@ docs/cli/gitmind-install-hooks.md) to ensure the front‑matter and links pass validation. ``` -{response} +> [!note]- **Accepted** +> | Confidence | Remarks | +> |------------|---------| +> | 10/10 | Fixes front matter parsing. | +> +> ## Lesson Learned +> +> YAML front matter must be the first block in the file. +> +> ## What did you do to address this feedback? +> +> - Moved HTML license comments below the front matter in `gitmind-install-hooks.md` and `gitmind-list.md`. +> +> ## Regression Avoidance Strategy +> +> - Front matter checker in CI. +> +> ## Notes +> +> None -### {feedback_item_title} +### Align front matter titles with H1s across enforcer/gameplans and specs ```text In docs/cli/gitmind-list.md around lines 1 to 11, the YAML front matter @@ -459,9 +593,34 @@ tools/docs/check_frontmatter.py --base docs to confirm the front-matter rule passes. ``` -{response} +> [!note]- **Accepted** +> | Confidence | Remarks | +> |------------|---------| +> | 9/10 | Improves discoverability and consistency. | +> +> ## Lesson Learned +> +> Titles should be canonical and consistent between front matter and H1. +> +> ## What did you do to address this feedback? +> +> - Updated titles in: +> - `03-observability-built-in.md` +> - `04-testing-infrastructure-uplift.md` +> - `08-devex-internal-cli.md` +> - `09-domain-language-purity.md` +> - `specs/02-domain-types-spec.md` +> - `enforcer/BEFORE_WE_BEGIN.md` +> +> ## Regression Avoidance Strategy +> +> - Docs lint scans title/H1 mismatches where feasible. +> +> ## Notes +> +> None -### {feedback_item_title} +### Technical Specifications: ensure H2 Table of Contents ```text In docs/enforcer/gameplans/03-observability-built-in.md around lines 1 to 9, the @@ -472,9 +631,28 @@ consistent search and discoverability (leave the rest of the front matter unchanged). ``` -{response} +> [!note]- **Accepted** +> | Confidence | Remarks | +> |------------|---------| +> | 10/10 | Consistent heading levels aid generators. | +> +> ## Lesson Learned +> +> Uniform TOC headings prevent subtle lint failures. +> +> ## What did you do to address this feedback? +> +> - Set TOC heading to `## Table of Contents`. +> +> ## Regression Avoidance Strategy +> +> - Keep docs lints on. +> +> ## Notes +> +> None -### {feedback_item_title} +### Wish-list plugins docs: make titles specific and fix duplicate H1 ```text In docs/enforcer/gameplans/04-testing-infrastructure-uplift.md lines 2–9, the @@ -486,9 +664,32 @@ generator uses the front-matter title for navigation so menus/search show the new title. ``` -{response} +> [!note]- **Accepted** +> | Confidence | Remarks | +> |------------|---------| +> | 9/10 | Title clarity and single-H1 rule improve readability. | +> +> ## Lesson Learned +> +> Generic titles harm search; duplicate H1s confuse parsers. +> +> ## What did you do to address this feedback? +> +> - Set specific titles in: +> - `brain-storms/plugins.md` +> - `plugins2.0/02-tech-design.md` +> - `plugins2.0/04-test-plan.md` +> - Removed duplicate H1 from `plugins2.0/03-api.md` and set a specific title. +> +> ## Regression Avoidance Strategy +> +> - Pre-commit docs checks and review. +> +> ## Notes +> +> None -### {feedback_item_title} +### Move adult_swim front matter to the top ```text In docs/enforcer/gameplans/08-devex-internal-cli.md around lines 2 to 9, the @@ -499,7 +700,26 @@ Internal CLI Gameplan"), keep other frontmatter fields intact, and ensure the new title follows existing site/title conventions and capitalization. ``` -{response} +> [!note]- **Accepted** +> | Confidence | Remarks | +> |------------|---------| +> | 10/10 | SSGs require front matter at the top. | +> +> ## Lesson Learned +> +> Keep YAML front matter as the first block so tooling recognizes it. +> +> ## What did you do to address this feedback? +> +> - Moved the YAML block to the top of `docs/adult_swim.md` after SPDX notices and removed the stray trailing blocks. +> +> ## Regression Avoidance Strategy +> +> - Front matter checker runs in CI. +> +> ## Notes +> +> None ### {feedback_item_title} @@ -636,6 +856,6 @@ before it so SSGs and pre-commit checks will recognize it. | Accepted | Rejected | Remarks | |-----------|----------|---------| -| {accepted_count} | {rejected_count} | {remarks} | +| 16 | 0 | All actionable items accepted and implemented. | -{comments} +All feedback items above have been implemented directly or via small surgical changes, and the document updated to reflect the actions and lessons learned. diff --git a/docs/enforcer/BEFORE_WE_BEGIN.md b/docs/enforcer/BEFORE_WE_BEGIN.md index 2d6f7948..17c9cc1c 100644 --- a/docs/enforcer/BEFORE_WE_BEGIN.md +++ b/docs/enforcer/BEFORE_WE_BEGIN.md @@ -1,5 +1,5 @@ --- -title: Enforcer Notes +title: BEFORE WE BEGIN: Clean Slate Strategy description: Historical notes and enforcement-era artifacts. audience: [contributors] domain: [quality] diff --git a/docs/enforcer/gameplans/03-observability-built-in.md b/docs/enforcer/gameplans/03-observability-built-in.md index fee102e2..375bed76 100644 --- a/docs/enforcer/gameplans/03-observability-built-in.md +++ b/docs/enforcer/gameplans/03-observability-built-in.md @@ -1,5 +1,5 @@ --- -title: Enforcer Notes +title: Observability Built-In: Gameplan description: Historical notes and enforcement-era artifacts. audience: [contributors] domain: [quality] diff --git a/docs/enforcer/gameplans/04-testing-infrastructure-uplift.md b/docs/enforcer/gameplans/04-testing-infrastructure-uplift.md index 147076ea..ef477203 100644 --- a/docs/enforcer/gameplans/04-testing-infrastructure-uplift.md +++ b/docs/enforcer/gameplans/04-testing-infrastructure-uplift.md @@ -1,5 +1,5 @@ --- -title: Enforcer Notes +title: Testing Infrastructure Uplift: Gameplan description: Historical notes and enforcement-era artifacts. audience: [contributors] domain: [quality] diff --git a/docs/enforcer/gameplans/08-devex-internal-cli.md b/docs/enforcer/gameplans/08-devex-internal-cli.md index 0e609fff..e8448704 100644 --- a/docs/enforcer/gameplans/08-devex-internal-cli.md +++ b/docs/enforcer/gameplans/08-devex-internal-cli.md @@ -1,5 +1,5 @@ --- -title: Enforcer Notes +title: DevEx Internal CLI — Enforcer Notes description: Historical notes and enforcement-era artifacts. audience: [contributors] domain: [quality] diff --git a/docs/enforcer/gameplans/09-domain-language-purity.md b/docs/enforcer/gameplans/09-domain-language-purity.md index 901625ab..28efefaa 100644 --- a/docs/enforcer/gameplans/09-domain-language-purity.md +++ b/docs/enforcer/gameplans/09-domain-language-purity.md @@ -1,5 +1,5 @@ --- -title: Enforcer Notes +title: Domain Language Purity — Enforcer Notes description: Historical notes and enforcement-era artifacts. audience: [contributors] domain: [quality] diff --git a/docs/enforcer/specs/02-domain-types-spec.md b/docs/enforcer/specs/02-domain-types-spec.md index a82c4a14..3fa54831 100644 --- a/docs/enforcer/specs/02-domain-types-spec.md +++ b/docs/enforcer/specs/02-domain-types-spec.md @@ -1,5 +1,5 @@ --- -title: Enforcer Notes +title: Domain Types and Strong Typedefs description: Historical notes and enforcement-era artifacts. audience: [contributors] domain: [quality] diff --git a/docs/specs/Technical_Specifications.md b/docs/specs/Technical_Specifications.md index 1cab40a5..d96f55df 100644 --- a/docs/specs/Technical_Specifications.md +++ b/docs/specs/Technical_Specifications.md @@ -10,7 +10,7 @@ last_updated: 2025-09-15 # Technical Specifications -Table of Contents +## Table of Contents - [Executive Summary](#executive-summary) - [Implementation Approach](#implementation-approach) diff --git a/docs/wish-list-features/brain-storms/plugins.md b/docs/wish-list-features/brain-storms/plugins.md index 55db7d38..eb994fdd 100644 --- a/docs/wish-list-features/brain-storms/plugins.md +++ b/docs/wish-list-features/brain-storms/plugins.md @@ -1,5 +1,5 @@ --- -title: Wish List +title: Plugin Architecture 2.0 — The Ecosystem Revolution description: Feature brainstorms and design sketches. audience: [contributors] domain: [project] diff --git a/docs/wish-list-features/plugins2.0/02-tech-design.md b/docs/wish-list-features/plugins2.0/02-tech-design.md index b75d792c..466a8a38 100644 --- a/docs/wish-list-features/plugins2.0/02-tech-design.md +++ b/docs/wish-list-features/plugins2.0/02-tech-design.md @@ -1,5 +1,5 @@ --- -title: Wish List +title: Plugin Architecture 2.0 — Tech Design description: Feature brainstorms and design sketches. audience: [contributors] domain: [project] diff --git a/docs/wish-list-features/plugins2.0/03-api.md b/docs/wish-list-features/plugins2.0/03-api.md index 36475535..81ae8dc3 100644 --- a/docs/wish-list-features/plugins2.0/03-api.md +++ b/docs/wish-list-features/plugins2.0/03-api.md @@ -1,5 +1,5 @@ --- -title: Wish List +title: Plugin Architecture 2.0 — API Specification description: Feature brainstorms and design sketches. audience: [contributors] domain: [project] @@ -8,8 +8,6 @@ status: archive last_updated: 2025-09-15 --- -# __API Specification: Plugin Architecture 2.0__ - # API Specification: Plugin Architecture 2.0 ## Summary diff --git a/docs/wish-list-features/plugins2.0/04-test-plan.md b/docs/wish-list-features/plugins2.0/04-test-plan.md index 76050704..0855926d 100644 --- a/docs/wish-list-features/plugins2.0/04-test-plan.md +++ b/docs/wish-list-features/plugins2.0/04-test-plan.md @@ -1,5 +1,5 @@ --- -title: Wish List +title: Test Plan: Plugin Architecture 2.0 description: Feature brainstorms and design sketches. audience: [contributors] domain: [project] From 6cf3aa52be51107e83759eb798bf93c40e38ee5d Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Tue, 16 Sep 2025 05:03:53 -0700 Subject: [PATCH 12/42] feat(review): add PR feedback seeding script; add CodeRabbit config, PR template, and docs-only label workflow --- .coderabbit.yml | 36 ++++++ .github/labeler.yml | 4 + .github/pull_request_template.md | 36 +++--- .github/workflows/label-docs-only.yml | 18 +++ tools/review/seed_feedback_from_github.py | 139 ++++++++++++++++++++++ 5 files changed, 213 insertions(+), 20 deletions(-) create mode 100644 .coderabbit.yml create mode 100644 .github/labeler.yml create mode 100644 .github/workflows/label-docs-only.yml create mode 100755 tools/review/seed_feedback_from_github.py diff --git a/.coderabbit.yml b/.coderabbit.yml new file mode 100644 index 00000000..168d6087 --- /dev/null +++ b/.coderabbit.yml @@ -0,0 +1,36 @@ +version: 1 + +review: + summary_preferred: true + max_total_comments: 50 + max_comments_per_file: 5 + prefer_patch_suggestions: true + tone: "concise, constructive, and action-oriented" + style: + - "Group similar issues together; avoid duplicates" + - "Reference rules/patterns (e.g., markdownlint MD041) over fragile line numbers" + - "Propose concrete fix-it snippets where possible" + - "Avoid inline comments on docs unless correctness is at stake; use summary" + +filters: + paths: + docs/**: summary_only + assets/**: ignore + build/**: ignore + .github/**: summary_only + +labels: + summary_only: + - docs-only + - chore + skip: + - vendored + +rules: + - name: "Front matter required" + paths: ["docs/**/*.md"] + summary: true + - name: "Single H1 per document" + paths: ["docs/**/*.md"] + summary: true + diff --git a/.github/labeler.yml b/.github/labeler.yml new file mode 100644 index 00000000..f4dc3d3d --- /dev/null +++ b/.github/labeler.yml @@ -0,0 +1,4 @@ +docs-only: + - changed-files: + - any-glob-to-any-file: ['docs/**', 'README.md', 'AGENTS.md', 'CONTRIBUTING.md'] + diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 841103ae..174538ae 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,28 +1,24 @@ -## Description +## Summary -Brief description of what this PR does. +Describe the change and why it’s needed. Link issues/PRDs if relevant. -## Related Issue +## Change Areas -Fixes #(issue number) +- [ ] Core (C) +- [ ] CLI / Hooks +- [ ] Docs +- [ ] CI / Tooling -## Type of Change +## Risk -- [ ] Bug fix (non-breaking change which fixes an issue) -- [ ] New feature (non-breaking change which adds functionality) -- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) -- [ ] Documentation update +- [ ] Behavior change +- [ ] Public API change +- [ ] Docs-only -## Testing +## Code Review Guidance (for humans and CodeRabbit) -- [ ] I have added tests that prove my fix is effective or that my feature works -- [ ] New and existing unit tests pass locally with my changes -- [ ] I have added/updated documentation as needed +- Summarize top risks and propose concrete fix-it blocks where needed. +- Prefer rule/pattern references (e.g., markdownlint MD041) over fragile line numbers. +- Group nits into a brief summary; avoid inline comments on docs unless correctness is impacted. +- Provide patch suggestions for repeated issues. -## Checklist - -- [ ] My code follows the style guidelines of this project -- [ ] I have run `make test` in Docker -- [ ] I have made corresponding changes to the documentation -- [ ] My changes generate no new warnings -- [ ] I have added tests that prove my fix is effective or that my feature works diff --git a/.github/workflows/label-docs-only.yml b/.github/workflows/label-docs-only.yml new file mode 100644 index 00000000..1e4b86a4 --- /dev/null +++ b/.github/workflows/label-docs-only.yml @@ -0,0 +1,18 @@ +name: Label docs-only PRs + +on: + pull_request_target: + types: [opened, synchronize, reopened] + +permissions: + contents: read + pull-requests: write + +jobs: + label: + runs-on: ubuntu-latest + steps: + - uses: actions/labeler@v5 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + configuration-path: .github/labeler.yml diff --git a/tools/review/seed_feedback_from_github.py b/tools/review/seed_feedback_from_github.py new file mode 100755 index 00000000..de4b527a --- /dev/null +++ b/tools/review/seed_feedback_from_github.py @@ -0,0 +1,139 @@ +#!/usr/bin/env python3 +""" +Seed a Code Review Feedback doc from a GitHub PR. + +Generates docs/code-reviews/PR/.md prefilled with +feedback items extracted from: +- PR review comments (code comments) +- PR issue comments (general discussion) + +Authentication: set GITHUB_TOKEN in the environment. + +Usage: + python3 tools/review/seed_feedback_from_github.py \ + --owner neuroglyph --repo git-mind --pr 169 \ + [--commit ] [--out docs/code-reviews] + +If --commit is omitted, the PR head SHA is used. +""" + +import argparse +import datetime as dt +import json +import os +import pathlib +import textwrap +import urllib.request +import urllib.error + + +API = "https://api.github.com" + + +def gh_get(path: str, token: str): + req = urllib.request.Request(API + path) + req.add_header("Accept", "application/vnd.github+json") + if token: + req.add_header("Authorization", f"Bearer {token}") + try: + with urllib.request.urlopen(req) as r: + return json.loads(r.read().decode("utf-8")) + except urllib.error.HTTPError as e: + msg = e.read().decode("utf-8", errors="ignore") + raise SystemExit(f"GitHub API error {e.code} on {path}: {msg}") + + +def normalize(s: str) -> str: + return s.replace("\r\n", "\n").strip() + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("--owner", required=True) + ap.add_argument("--repo", required=True) + ap.add_argument("--pr", type=int, required=True) + ap.add_argument("--commit", default=None, help="Target commit SHA (defaults to PR head)") + ap.add_argument("--out", default="docs/code-reviews", help="Base output dir") + args = ap.parse_args() + + token = os.environ.get("GITHUB_TOKEN", "") + pr_path = f"/repos/{args.owner}/{args.repo}/pulls/{args.pr}" + pr = gh_get(pr_path, token) + head_sha = (args.commit or pr.get("head", {}).get("sha", "")).strip() + head_ref = pr.get("head", {}).get("ref", "") + pr_url = pr.get("html_url", "") + + if not head_sha: + raise SystemExit("Unable to determine PR head SHA. Pass --commit explicitly.") + + # Collect review comments + rev_comments = gh_get(pr_path + "/comments?per_page=100", token) + # Collect issue comments (discussion) + iss_comments = gh_get(f"/repos/{args.owner}/{args.repo}/issues/{args.pr}/comments?per_page=100", token) + + # Build output path + out_dir = pathlib.Path(args.out) / f"PR{args.pr}" + out_dir.mkdir(parents=True, exist_ok=True) + out_file = out_dir / f"{head_sha}.md" + + # Header/front matter + today = dt.datetime.utcnow().strftime("%Y-%m-%d") + agent = "CodeRabbit (and reviewers)" + + def fm_line(k, v): + return f"{k}: {v}\n" + + content = [] + content.append("---\n") + content.append(fm_line("title", out_file.name)) + content.append("description: Preserved review artifacts and rationale.\n") + content.append("audience: [contributors]\n") + content.append("domain: [quality]\n") + content.append("tags: [review]\n") + content.append("status: archive\n") + content.append("---\n\n") + + content.append("# Code Review Feedback\n\n") + content.append("| Date | Agent | SHA | Branch | PR |\n") + content.append("|------|-------|-----|--------|----|\n") + content.append(f"| {today} | {agent} | `{head_sha}` | [{head_ref}](https://github.com/{args.owner}/{args.repo}/tree/{head_ref} \"{args.owner}/{args.repo}:{head_ref}\") | [PR#{args.pr}]({pr_url}) |\n\n") + + content.append("## CODE REVIEW FEEDBACK\n\n") + + # Helper: emit one feedback block + def emit_feedback(title: str, body: str, meta: str = ""): + content.append(f"### {title}\n\n") + fence = "```text\n" + normalize(body) + "\n```\n\n" + content.append(fence) + if meta: + content.append(f"_Meta_: {meta}\n\n") + content.append("{response}\n\n") + + # Add review comments (code) + for c in rev_comments: + path = c.get("path", "") + line = c.get("line") or c.get("original_line") + url = c.get("html_url", "") + user = c.get("user", {}).get("login", "") + title = f"{path}:{line} — {user}" + body = c.get("body", "") + meta = url + emit_feedback(title, body, meta) + + # Add issue comments (general) + for c in iss_comments: + body = c.get("body", "") + user = c.get("user", {}).get("login", "") + url = c.get("html_url", "") + title = f"General comment — {user}" + emit_feedback(title, body, url) + + with open(out_file, "w", encoding="utf-8") as f: + f.write("".join(content)) + + print(f"Wrote {out_file}") + + +if __name__ == "__main__": + main() + From c33f0dbc65c436875749308d853f7dc414f3e7e8 Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Tue, 16 Sep 2025 05:08:49 -0700 Subject: [PATCH 13/42] docs(AGENTS): add Regression Guardrails and PR Review Checklist with references to tooling --- AGENTS.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index ca1237fe..90bf8e43 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -168,3 +168,52 @@ If you maintain a separate experimental tracking system locally (e.g., a persona - docs(ops): added `docs/operations/Environment_Variables.md`; linked from `README.md` and `docs/README.md`. Noted runtime safety behavior in Test Plan. - style(include): use angle includes in `include/gitmind.h` and trim optional-include block comment. - Opened PR: (branch `feat/cli-safety-e2e`). Built and ran unit tests in Docker (15/15 passing). E2E wired to run in CI container. + +## Regression Guardrails + +- Build/run + - Docker-only for build and test; use `make ci-local` or `tools/ci/ci_local.sh`. + - Meson gate blocks host builds; override only with `-Dforce_local_builds=true` when necessary. +- API semantics + - Equality is OID-first: if both OIDs present they must match; SHA fallback only when OIDs are absent. + - Refs: build via `gm_build_ref`; reject inputs starting with `refs/`; follow ref-name safety rules. +- Safety ops + - Use `gm_snprintf`/`gm_strcpy_safe`/`gm_memcpy_span`; check return codes; treat truncation as error. + - Zero output buffers on error paths before formatting or copying. +- Public headers + - Umbrella-safe; direct includes only; add C++ linkage guards; stable header guards. +- Cache/journal + - Journal is append-only under `refs/gitmind/edges/`; cache under `refs/gitmind/cache/`. + - Avoid ABI breaks in public structs; append new fields at struct tail; mark deprecated fields. +- Paths/buffers + - Prefer `GM_PATH_MAX`; do not use `GM_PATH_MAX*2`; allocate if larger is required. +- Docs + - Front matter first; single H1; `## Table of Contents`; titles match H1; add `api_version` to API docs. + - License/SPDX comments after front matter. +- Tests + - Run in Docker; avoid HEAD assumptions in bare repos; seed branches in tests when needed. + +## PR Review Checklist + +- Scope & safety + - Docker-only build/test verified; no host-only assumptions. + - No public ABI breaks (or explicitly called out and versioned). +- Semantics & correctness + - OID-first behavior enforced; no SHA fallback when OIDs exist. + - Refs created via `gm_build_ref` with input validation. +- Security & robustness + - All string/memory ops use safe wrappers; truncation and errors handled. + - Outputs zeroed on failure; no partial writes. +- Headers & includes + - C++ linkage guards present; include-what-you-use; umbrella viability. +- Docs & tooling + - Front matter valid; titles/H1 aligned; TOC heading H2; API docs include `api_version`. + - Changelog updated for pushes to `main` (pre-push hook regex covers variants). +- CI & review hygiene + - Local CI (Docker) passes (tests + tidy as configured). + - If CodeRabbit runs: summary-first; propose fix-it patches; avoid noisy doc inlines. + +References +- Code review seeding script: `tools/review/seed_feedback_from_github.py` (uses `GITHUB_TOKEN`). +- CodeRabbit config: `.coderabbit.yml` (summary-first, caps, doc filters). +- PR template: `.github/pull_request_template.md` (guidance for reviewers). From 2cab0d326e8f8518f78f27275fe481a6b220ee8e Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Tue, 16 Sep 2025 05:13:04 -0700 Subject: [PATCH 14/42] chore(tooling): add docs-verify, header-compile, seed-review make targets; add title/H1 checker; add manual workflow to seed review docs --- .github/workflows/seed-review.yml | 30 ++++++++++++++++ Makefile | 29 ++++++++++++++++ tools/docs/check_titles.py | 58 +++++++++++++++++++++++++++++++ 3 files changed, 117 insertions(+) create mode 100644 .github/workflows/seed-review.yml create mode 100644 tools/docs/check_titles.py diff --git a/.github/workflows/seed-review.yml b/.github/workflows/seed-review.yml new file mode 100644 index 00000000..6c10b6c9 --- /dev/null +++ b/.github/workflows/seed-review.yml @@ -0,0 +1,30 @@ +name: Seed Review Doc (manual) + +on: + workflow_dispatch: + inputs: + pr: + description: PR number to seed + required: true + type: number + +jobs: + seed: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.x' + - name: Run seeding script + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + python3 tools/review/seed_feedback_from_github.py \ + --owner ${GITHUB_REPOSITORY%%/*} --repo ${GITHUB_REPOSITORY##*/} --pr ${{ inputs.pr }} --out review-seed + - name: Upload artifact + uses: actions/upload-artifact@v4 + with: + name: review-seed + path: review-seed/** diff --git a/Makefile b/Makefile index 201aea6e..4224ef75 100644 --- a/Makefile +++ b/Makefile @@ -39,4 +39,33 @@ changelog-add: ci-local: @bash tools/ci/ci_local.sh +.PHONY: docs-verify +docs-verify: + @python3 tools/docs/check_frontmatter.py + @python3 tools/docs/check_docs.py --mode link + @python3 tools/docs/check_docs.py --mode toc + @python3 tools/docs/check_titles.py + +.PHONY: header-compile +header-compile: + @meson setup $(builddir) $(MESON_ARGS) >/dev/null 2>&1 || true + @ninja -C $(builddir) header-compile + +.PHONY: seed-review +# Usage: make seed-review PR=169 [OWNER=neuroglyph REPO=git-mind] +seed-review: + @OWNER=$(OWNER); REPO=$(REPO); \ + if [ -z "$$OWNER" ] || [ -z "$$REPO" ]; then \ + url=$$(git remote get-url origin); \ + case "$$url" in \ + git@github.com:*) base=$${url#git@github.com:};; \ + https://github.com/*) base=$${url#https://github.com/};; \ + *) base="neuroglyph/git-mind";; \ + esac; \ + OWNER=$${base%%/*}; REPO=$${base##*/}; REPO=$${REPO%.git}; \ + fi; \ + if [ -z "$(PR)" ]; then echo "PR= is required"; exit 2; fi; \ + echo "Seeding review for $$OWNER/$$REPO PR $(PR)"; \ + python3 tools/review/seed_feedback_from_github.py --owner $$OWNER --repo $$REPO --pr $(PR) + .PHONY: all test clean docker-clean md-lint md-fix changelog-add ci-local diff --git a/tools/docs/check_titles.py b/tools/docs/check_titles.py new file mode 100644 index 00000000..97221913 --- /dev/null +++ b/tools/docs/check_titles.py @@ -0,0 +1,58 @@ +#!/usr/bin/env python3 +""" +Verify that each Markdown document's first H1 matches its front-matter title. + +Exits non-zero and prints offending files. +""" +import os +import sys +import pathlib + + +def parse_front_matter(text: str): + lines = text.splitlines() + if len(lines) < 3 or lines[0].strip() != '---': + return {} + fm = {} + for i in range(1, len(lines)): + if lines[i].strip() == '---': + break + line = lines[i] + if ':' in line: + k, v = line.split(':', 1) + fm[k.strip()] = v.strip().strip('"') + return fm + + +def first_h1(text: str): + for line in text.splitlines(): + s = line.strip() + if s.startswith('# '): + return s[2:].strip() + return '' + + +def main(): + base = pathlib.Path('docs') + bad = [] + for p in base.rglob('*.md'): + # Skip templates and rejected suggestions folder + pp = str(p) + if '/templates/' in pp or '/rejected-suggestions/' in pp: + continue + text = p.read_text(encoding='utf-8') + fm = parse_front_matter(text) + title = fm.get('title', '').strip() + h1 = first_h1(text) + if title and h1 and title != h1: + bad.append((pp, title, h1)) + if bad: + print('Title/H1 mismatches:') + for pp, t, h in bad: + print(f"- {pp}: title='{t}' != H1='{h}'") + sys.exit(1) + + +if __name__ == '__main__': + main() + From 6c5f01a91972b1fa32a304d3b9e5decfec43dcd5 Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Tue, 16 Sep 2025 05:20:39 -0700 Subject: [PATCH 15/42] ci(review): auto-seed review doc on PRs; commit to same-repo branches, artifact + comment for forks --- .github/workflows/auto-seed-review.yml | 88 ++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 .github/workflows/auto-seed-review.yml diff --git a/.github/workflows/auto-seed-review.yml b/.github/workflows/auto-seed-review.yml new file mode 100644 index 00000000..a2cda890 --- /dev/null +++ b/.github/workflows/auto-seed-review.yml @@ -0,0 +1,88 @@ +name: Auto Seed Review Doc + +on: + pull_request_target: + types: [opened, reopened, synchronize] + +permissions: + contents: write + pull-requests: write + +jobs: + seed-same-repo: + if: ${{ github.event.pull_request.head.repo.full_name == github.repository }} + runs-on: ubuntu-latest + steps: + - name: Checkout PR branch (same-repo) + uses: actions/checkout@v4 + with: + ref: ${{ github.event.pull_request.head.ref }} + repository: ${{ github.event.pull_request.head.repo.full_name }} + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.x' + - name: Seed feedback doc into repo + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + PR=${{ github.event.number }} + echo "Seeding review for PR#$PR (same-repo)" + python3 tools/review/seed_feedback_from_github.py \ + --owner "${GITHUB_REPOSITORY%%/*}" --repo "${GITHUB_REPOSITORY##*/}" \ + --pr "$PR" --out docs/code-reviews + - name: Commit and push + run: | + git config user.name "git-mind-bot" + git config user.email "gitmind-bot@example.com" + git add docs/code-reviews + if git diff --cached --quiet; then + echo "No changes to commit"; exit 0; fi + PR=${{ github.event.number }} + SHA=${{ github.event.pull_request.head.sha }} + git commit -m "chore(review): seed feedback for PR #$PR ($SHA)" + git push + + seed-fork: + if: ${{ github.event.pull_request.head.repo.full_name != github.repository }} + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.x' + - name: Seed feedback doc (artifact for fork PR) + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + PR=${{ github.event.number }} + echo "Seeding review for PR#$PR (fork)" + python3 tools/review/seed_feedback_from_github.py \ + --owner "${GITHUB_REPOSITORY%%/*}" --repo "${GITHUB_REPOSITORY##*/}" \ + --pr "$PR" --out review-seed + - name: Upload artifact + uses: actions/upload-artifact@v4 + with: + name: review-seed-PR${{ github.event.number }} + path: review-seed/** + - name: Comment with instructions + uses: actions/github-script@v7 + with: + script: | + const pr = context.payload.pull_request.number; + const msg = `I've generated a seeded review worksheet as an artifact for this PR (forked branch). + + Steps: + 1. Download the 'review-seed-PR${pr}' artifact from this workflow run. + 2. Copy the file under 'docs/code-reviews/PR${pr}/.md' into your branch. + 3. Fill in {response} sections with Accepted/Rejected templates and push. + + Maintainers: merging PR branches into the main repo will allow auto-commit of future seeds.`; + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: pr, + body: msg + }); + From b8f708b5e5c00c49ed7f14bd7cd26bafda9de257 Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Tue, 16 Sep 2025 05:25:38 -0700 Subject: [PATCH 16/42] ci(review): try push to fork with BOT_PAT when allowed; fallback to artifact/comment --- .github/workflows/auto-seed-review.yml | 43 +++++++++++++++++++++++--- 1 file changed, 39 insertions(+), 4 deletions(-) diff --git a/.github/workflows/auto-seed-review.yml b/.github/workflows/auto-seed-review.yml index a2cda890..8b83c67b 100644 --- a/.github/workflows/auto-seed-review.yml +++ b/.github/workflows/auto-seed-review.yml @@ -47,20 +47,56 @@ jobs: if: ${{ github.event.pull_request.head.repo.full_name != github.repository }} runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - name: Checkout fork branch (read-only) + uses: actions/checkout@v4 + with: + repository: ${{ github.event.pull_request.head.repo.full_name }} + ref: ${{ github.event.pull_request.head.ref }} - name: Set up Python uses: actions/setup-python@v5 with: python-version: '3.x' - - name: Seed feedback doc (artifact for fork PR) + - name: Try to seed and push to fork (if maintainers can modify) env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + BOT_PAT: ${{ secrets.BOT_PAT }} run: | + set -e PR=${{ github.event.number }} echo "Seeding review for PR#$PR (fork)" + # Ensure our tools exist (checked out fork branch may not have them in older forks) + if [ ! -f tools/review/seed_feedback_from_github.py ]; then + echo "Tools missing in fork, checking out base repo tools..." + mkdir -p _tools + git clone --depth=1 https://github.com/${GITHUB_REPOSITORY}.git _tools/base + cp -r _tools/base/tools/review . || true + fi python3 tools/review/seed_feedback_from_github.py \ --owner "${GITHUB_REPOSITORY%%/*}" --repo "${GITHUB_REPOSITORY##*/}" \ - --pr "$PR" --out review-seed + --pr "$PR" --out docs/code-reviews + git config user.name "git-mind-bot" + git config user.email "gitmind-bot@example.com" + git add docs/code-reviews + if git diff --cached --quiet; then + echo "No seeded changes to commit"; exit 0; fi + git commit -m "chore(review): seed feedback for PR #$PR" + # Attempt to push using BOT_PAT if provided and contributor allows edits + if [ -n "$BOT_PAT" ]; then + repo_full="${{ github.event.pull_request.head.repo.full_name }}" + branch="${{ github.event.pull_request.head.ref }}" + echo "Attempting push to fork $repo_full branch $branch" + git remote set-url origin https://x-access-token:$BOT_PAT@github.com/$repo_full.git + if git push origin "HEAD:$branch"; then + echo "Pushed seeded doc to fork branch" + exit 0 + else + echo "Push to fork failed (likely edits not allowed); will upload artifact instead" + fi + else + echo "BOT_PAT not set; cannot push to fork. Uploading artifact instead." + fi + # Fall through to artifact path + mkdir -p review-seed && cp -r docs/code-reviews/* review-seed/ || true - name: Upload artifact uses: actions/upload-artifact@v4 with: @@ -85,4 +121,3 @@ jobs: issue_number: pr, body: msg }); - From 4a53e56e9d8f88460410759d0663d07621570b49 Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Tue, 16 Sep 2025 05:29:59 -0700 Subject: [PATCH 17/42] ci(review): rename bot secret to GITMIND_PR_WORKSHEET_BOT --- .github/workflows/auto-seed-review.yml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/auto-seed-review.yml b/.github/workflows/auto-seed-review.yml index 8b83c67b..c8b0d0fd 100644 --- a/.github/workflows/auto-seed-review.yml +++ b/.github/workflows/auto-seed-review.yml @@ -59,7 +59,7 @@ jobs: - name: Try to seed and push to fork (if maintainers can modify) env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - BOT_PAT: ${{ secrets.BOT_PAT }} + GITMIND_PR_WORKSHEET_BOT: ${{ secrets.GITMIND_PR_WORKSHEET_BOT }} run: | set -e PR=${{ github.event.number }} @@ -80,12 +80,12 @@ jobs: if git diff --cached --quiet; then echo "No seeded changes to commit"; exit 0; fi git commit -m "chore(review): seed feedback for PR #$PR" - # Attempt to push using BOT_PAT if provided and contributor allows edits - if [ -n "$BOT_PAT" ]; then + # Attempt to push using GITMIND_PR_WORKSHEET_BOT if provided and contributor allows edits + if [ -n "$GITMIND_PR_WORKSHEET_BOT" ]; then repo_full="${{ github.event.pull_request.head.repo.full_name }}" branch="${{ github.event.pull_request.head.ref }}" echo "Attempting push to fork $repo_full branch $branch" - git remote set-url origin https://x-access-token:$BOT_PAT@github.com/$repo_full.git + git remote set-url origin https://x-access-token:$GITMIND_PR_WORKSHEET_BOT@github.com/$repo_full.git if git push origin "HEAD:$branch"; then echo "Pushed seeded doc to fork branch" exit 0 @@ -93,7 +93,7 @@ jobs: echo "Push to fork failed (likely edits not allowed); will upload artifact instead" fi else - echo "BOT_PAT not set; cannot push to fork. Uploading artifact instead." + echo "GITMIND_PR_WORKSHEET_BOT not set; cannot push to fork. Uploading artifact instead." fi # Fall through to artifact path mkdir -p review-seed && cp -r docs/code-reviews/* review-seed/ || true From 88aceda4e21859ab8ad1b5093d75a8fae6dc90fc Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Tue, 16 Sep 2025 05:36:09 -0700 Subject: [PATCH 18/42] docs(tools): add Review_Seeding guide; link from AGENTS.md and CONTRIBUTING.md --- AGENTS.md | 1 + CONTRIBUTING.md | 1 + docs/tools/Review_Seeding.md | 94 ++++++++++++++++++++++++++++++++++++ 3 files changed, 96 insertions(+) create mode 100644 docs/tools/Review_Seeding.md diff --git a/AGENTS.md b/AGENTS.md index 90bf8e43..45c09b47 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -214,6 +214,7 @@ If you maintain a separate experimental tracking system locally (e.g., a persona - If CodeRabbit runs: summary-first; propose fix-it patches; avoid noisy doc inlines. References +- Guide: `docs/tools/Review_Seeding.md` (end-to-end review seeding + bot setup) - Code review seeding script: `tools/review/seed_feedback_from_github.py` (uses `GITHUB_TOKEN`). - CodeRabbit config: `.coderabbit.yml` (summary-first, caps, doc filters). - PR template: `.github/pull_request_template.md` (guidance for reviewers). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 423529d3..5e2768fe 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -54,6 +54,7 @@ Thanks for your interest in improving git‑mind! This guide summarizes expectat - Keep `.coderabbit.yml` updated. - Prefer summary reviews; limit per‑line comments on docs. - If rejecting a suggestion, document rationale under `docs/code-reviews/rejected-suggestions/` with links. + - See `docs/tools/Review_Seeding.md` for the auto‑worksheet flow and how to seed PR feedback locally or via CI. Seeded files live under `docs/code-reviews/PR/.md`. ## Getting Help diff --git a/docs/tools/Review_Seeding.md b/docs/tools/Review_Seeding.md new file mode 100644 index 00000000..c1bed40e --- /dev/null +++ b/docs/tools/Review_Seeding.md @@ -0,0 +1,94 @@ +--- +title: Review Seeding and Auto‑Worksheet +description: How PR review comments are harvested into a structured worksheet and committed back to the PR branch. +audience: [contributors, maintainers] +domain: [quality] +tags: [review, automation] +status: stable +last_updated: 2025-09-16 +--- + +# Review Seeding and Auto‑Worksheet + +> This documents the PR feedback workflow: scraping GitHub PR comments (reviews + discussion), pre‑filling a structured worksheet under `docs/code-reviews/PR/.md`, and committing it back to the PR branch. + +## Overview + +- Script: `tools/review/seed_feedback_from_github.py` +- Make target: `make seed-review PR=` +- Auto workflows: + - Same‑repo PRs: auto‑commit seeded worksheet to the PR branch + - Fork PRs: attempt push with bot PAT; else upload artifact + comment +- Review config: + - `.coderabbit.yml` tunes CodeRabbit (summary‑first, caps, doc filters) + - `.github/pull_request_template.md` guides reviewers + - Docs‑only PRs auto‑labeled via `.github/labeler.yml` + +## Local Usage + +1. Create a GitHub token and export it: + - Fine‑grained token, minimal scopes: Pull Requests: Read; Issues: Read; Metadata: Read + - Classic token alternative: `repo` (read) is sufficient + - macOS/Linux: `export GITHUB_TOKEN=ghp_xxx` +2. Seed a worksheet: + - `make seed-review PR=169` + - Output: `docs/code-reviews/PR169/.md` +3. Fill out `{response}` sections using Accepted/Rejected templates and commit. + +## CI Automation + +### Same‑repo PRs +- Workflow: `.github/workflows/auto-seed-review.yml` +- Trigger: PR opened/reopened/synchronized +- Action: seeds doc and commits directly to the PR branch using `GITHUB_TOKEN`. + +### Fork PRs +- If “Allow edits from maintainers” is enabled and a bot PAT is configured: + - Attempts to commit the seeded doc to the contributor’s branch +- Otherwise: + - Uploads the seeded file as a build artifact + - Adds a PR comment with instructions to copy the file into the branch + +## Bot PAT Configuration (for fork PR pushes) + +Use a Fine‑grained Personal Access Token: +- Repository access: Only select repositories → select this repo +- Repository permissions (minimum): + - Contents: Read and write + - Pull requests: Read and write + - Issues: Read and write + - Metadata: Read +- Add the token to repo secrets as: `GITMIND_PR_WORKSHEET_BOT` +- Ensure contributors keep “Allow edits from maintainers” enabled on PRs + +The workflow will use `GITMIND_PR_WORKSHEET_BOT` to push the seeded doc to fork PR branches when allowed. If push fails (edits disabled), the artifact+comment path is used. + +## Manual Workflow + +- Workflow: `.github/workflows/seed-review.yml` +- Dispatch from Actions with input `pr=` +- Produces an artifact (folder `review-seed`) with the generated worksheet + +## Review Document Structure + +- Location: `docs/code-reviews/PR/.md` +- Contains one heading per feedback item with a fenced text block +- Replace `{response}` with: + - Accepted template (with lesson + prevention), or + - Rejected template (with rationale + tradeoffs) + +## Best Practices + +- Keep fixes in small, targeted commits; link commit SHAs into the worksheet +- Prefer rule/pattern references over fragile line numbers (e.g., MD041) +- For docs‑only PRs, rely on summary review; minimize inline nit comments +- Use `make docs-verify` before pushing to keep docs clean + +## Related + +- `.coderabbit.yml` — CodeRabbit tuning +- `.github/pull_request_template.md` — Reviewer guidance +- `.github/workflows/auto-seed-review.yml` — Auto‑seeding logic +- `.github/workflows/label-docs-only.yml` — Auto labeler +- `make docs-verify` — Front matter, link, TOC, title/H1 checks + From a6d643c6762a4bd2ffc29c4cbec30a467af11e89 Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Tue, 16 Sep 2025 05:42:33 -0700 Subject: [PATCH 19/42] docs(review): add Future Work section to Review_Seeding with GH App and classic PAT options --- docs/tools/Review_Seeding.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/tools/Review_Seeding.md b/docs/tools/Review_Seeding.md index c1bed40e..a7dee5a5 100644 --- a/docs/tools/Review_Seeding.md +++ b/docs/tools/Review_Seeding.md @@ -92,3 +92,15 @@ The workflow will use `GITMIND_PR_WORKSHEET_BOT` to push the seeded doc to fork - `.github/workflows/label-docs-only.yml` — Auto labeler - `make docs-verify` — Front matter, link, TOC, title/H1 checks +## Future Work + +- GitHub App for Worksheet Bot + - Create a GitHub App that contributors can grant access to their fork. The app’s installation token would allow writing the seeded doc directly to fork branches without broad classic PAT scopes. + - Benefits: principle‑of‑least‑privilege, per‑repo install, clean audit trail. + - Work: app manifest, permissions (Contents:RW, PR:RW, Issues:RW, Metadata:Read), and token exchange in the workflow. +- Classic PAT for pushing to forks (if needed) + - Replace fine‑grained PAT with a classic PAT (scope: `public_repo` for public, or `repo` for private) in the secret `GITMIND_PR_WORKSHEET_BOT` to enable pushes to user‑owned forks. + - Trade‑off: broader scope than fine‑grained tokens. +- Auto‑open helper PR to contributor fork + - If push to fork fails, create a helper PR in their fork with the seeded doc. This typically requires permission to fork/cross‑fork and may be restricted. Consider only if contributor experience warrants it. + From 406db64d413532331dbf1e71d47046e06fd41dca Mon Sep 17 00:00:00 2001 From: James Ross Date: Tue, 16 Sep 2025 05:49:42 -0700 Subject: [PATCH 20/42] Potential fix for code scanning alert no. 19: Workflow does not contain permissions Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com> Signed-off-by: James Ross --- .github/workflows/seed-review.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/seed-review.yml b/.github/workflows/seed-review.yml index 6c10b6c9..f00a85b2 100644 --- a/.github/workflows/seed-review.yml +++ b/.github/workflows/seed-review.yml @@ -1,4 +1,6 @@ name: Seed Review Doc (manual) +permissions: + contents: read on: workflow_dispatch: From 3a0f4e6812f4e147f0b437cd5a92fbb86032e2c1 Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Tue, 16 Sep 2025 05:58:08 -0700 Subject: [PATCH 21/42] feat(review): add workflow to apply feedback replies to PR comments from seeded worksheets; add script --- .github/workflows/apply-feedback.yml | 36 +++++ AGENTS.md | 27 ++++ tools/review/apply_feedback_to_github.py | 159 +++++++++++++++++++++++ 3 files changed, 222 insertions(+) create mode 100644 .github/workflows/apply-feedback.yml create mode 100644 tools/review/apply_feedback_to_github.py diff --git a/.github/workflows/apply-feedback.yml b/.github/workflows/apply-feedback.yml new file mode 100644 index 00000000..2f6165c5 --- /dev/null +++ b/.github/workflows/apply-feedback.yml @@ -0,0 +1,36 @@ +name: Apply PR Feedback Replies + +on: + push: + branches-ignore: [ main ] + paths: + - 'docs/code-reviews/**.md' + +permissions: + contents: read + pull-requests: write + +jobs: + apply: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Detect changed review worksheets + id: files + run: | + set -e + BEFORE=${{ github.event.before }} + AFTER=${{ github.sha }} + git fetch --no-tags origin "$BEFORE" || true + CHANGED=$(git diff --name-only "$BEFORE" "$AFTER" | grep '^docs/code-reviews/PR' || true) + echo "changed=$CHANGED" >> $GITHUB_OUTPUT + - name: Apply feedback replies + if: steps.files.outputs.changed != '' + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + set -e + OWNER=${GITHUB_REPOSITORY%%/*} + REPO=${GITHUB_REPOSITORY##*/} + python3 -m pip install --upgrade pip >/dev/null 2>&1 || true + python3 tools/review/apply_feedback_to_github.py --owner "$OWNER" --repo "$REPO" ${{ steps.files.outputs.changed }} diff --git a/AGENTS.md b/AGENTS.md index 45c09b47..b192268a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,32 @@ # Repository Guidelines +> Agent TL;DR (read me first) +- Build/test: `make ci-local` (Docker-only; Meson guard prevents host builds). Docs verify: `make docs-verify`. +- Review seeding: `make seed-review PR=`; see `docs/tools/Review_Seeding.md`. +- Red lines: OID-first equality; use `gm_snprintf/gm_strcpy_safe`; append-only journal; no public ABI breaks (append fields). +- Refs via `gm_build_ref`; reject inputs starting with `refs/`. No `GM_PATH_MAX*2` buffers. +- Public headers are umbrella-safe with C++ linkage guards; run `make header-compile`. +- Docker-only policy: override host build only with `-Dforce_local_builds=true` when absolutely necessary. + +agent: + docker_only: true + build: "make ci-local" + docs_verify: "make docs-verify" + seed_review: "make seed-review PR=${PR}" + header_compile: "make header-compile" + stop_signs: + - behavior_or_abi_change + - adding_dependencies + - changing_ci_gates + - large_refactor + +Boot Checklist +- Check for nested `AGENTS.md` when editing in subdirs +- Use Docker for builds/tests; never host-run by default +- Run `make docs-verify` for doc changes; `make header-compile` for new public headers +- Respect One‑Thing rule for touched files +- For fork PRs, seeded worksheet may be artifact+comment (see Review_Seeding) + ## Project Structure & Module Organization - `core/` — C23 library: `include/` (public headers), `src/` (impl), `tests/` (unit). Add new code here. diff --git a/tools/review/apply_feedback_to_github.py b/tools/review/apply_feedback_to_github.py new file mode 100644 index 00000000..41db417b --- /dev/null +++ b/tools/review/apply_feedback_to_github.py @@ -0,0 +1,159 @@ +#!/usr/bin/env python3 +""" +Apply feedback from a seeded review worksheet to GitHub: +- For each feedback item, detect Accepted/Rejected. +- Extract the original comment URL from the _Meta_ line. +- Post a reply to the original comment thread: + - Accepted: brief acknowledgement, optional "Resolved" marker. + - Rejected: paste the rejection block body. + +Limitations: +- Resolving review threads programmatically typically requires GraphQL; this + script currently posts replies only. Future work: add GraphQL mutation to + resolve threads for Accepted items. + +Usage (CI): + python3 tools/review/apply_feedback_to_github.py --owner --repo + +Env: + GITHUB_TOKEN required. +""" +import argparse +import json +import os +import re +import sys +import urllib.request +import urllib.error + +API = "https://api.github.com" + + +def gh_request(method: str, path: str, token: str, payload=None): + url = API + path + data = None + headers = { + "Accept": "application/vnd.github+json", + } + if token: + headers["Authorization"] = f"Bearer {token}" + if payload is not None: + data = json.dumps(payload).encode("utf-8") + headers["Content-Type"] = "application/json" + req = urllib.request.Request(url, data=data, method=method, headers=headers) + try: + with urllib.request.urlopen(req) as r: + body = r.read().decode("utf-8") + return json.loads(body) if body else {} + except urllib.error.HTTPError as e: + msg = e.read().decode("utf-8", errors="ignore") + print(f"GitHub API {method} {path} failed: {e.code} {msg}", file=sys.stderr) + return None + + +SECTION_RE = re.compile(r"^###\s+(.*)$", re.MULTILINE) +META_RE = re.compile(r"^_Meta_:\s+(\S+)$", re.MULTILINE) +ACCEPT_RE = re.compile(r"^>\s*\[!note\]\-\s*\*\*Accepted\*\*", re.IGNORECASE | re.MULTILINE) +REJECT_RE = re.compile(r"^>\s*\[!CAUTION\]\-\s*\*\*Rejected\*\*", re.IGNORECASE | re.MULTILINE) + + +def extract_sections(text: str): + """Yield (title, body) for each ### section until next ### or end.""" + titles = list(SECTION_RE.finditer(text)) + for idx, m in enumerate(titles): + start = m.end() + end = titles[idx + 1].start() if idx + 1 < len(titles) else len(text) + yield (m.group(1).strip(), text[start:end].strip()) + + +def parse_comment_meta(body: str): + mm = META_RE.search(body) + return mm.group(1).strip() if mm else "" + + +def accepted_or_rejected(body: str): + is_acc = bool(ACCEPT_RE.search(body)) + is_rej = bool(REJECT_RE.search(body)) + if is_acc and not is_rej: + return "accepted" + if is_rej and not is_acc: + return "rejected" + return "unknown" + + +def reply_body(state: str, section_body: str): + if state == "accepted": + return "Acknowledged. Addressed as accepted in the worksheet. Marking as resolved. ✅" + if state == "rejected": + # Extract the rejection block and use it as reply body + # Fallback to a short note if not found. + m = REJECT_RE.search(section_body) + if m: + # Include from the rejection marker to next blank line group or end + start = m.start() + return section_body[start:].strip() + return "Rejected — see worksheet for rationale and tradeoffs." + return "Not classified — please review the worksheet section." + + +def handle_comment(owner: str, repo: str, token: str, meta_url: str, state: str, body: str): + if "/pull/" in meta_url and "/review_comment/" in meta_url: + # Code review comment URL -> extract comment id + try: + comment_id = int(meta_url.rsplit("/review_comment/", 1)[1].split("#")[0]) + except Exception: + return False + payload = {"body": reply_body(state, body)} + resp = gh_request("POST", f"/repos/{owner}/{repo}/pulls/comments/{comment_id}/replies", token, payload) + return resp is not None + if "/issues/" in meta_url and "issuecomment-" in meta_url: + # PR issue comment -> post a new issue comment to the PR + try: + pr_num = int(meta_url.split("/issues/")[1].split("#", 1)[0]) + except Exception: + return False + payload = {"body": reply_body(state, body)} + resp = gh_request("POST", f"/repos/{owner}/{repo}/issues/{pr_num}/comments", token, payload) + return resp is not None + return False + + +def process_file(owner: str, repo: str, token: str, path: str): + text = open(path, "r", encoding="utf-8").read() + any_ok = False + for title, body in extract_sections(text): + meta = parse_comment_meta(body) + if not meta: + continue + state = accepted_or_rejected(body) + if state == "unknown": + continue + ok = handle_comment(owner, repo, token, meta, state, body) + any_ok = any_ok or ok + return any_ok + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument("--owner", required=True) + ap.add_argument("--repo", required=True) + ap.add_argument("files", nargs="+") + args = ap.parse_args() + + token = os.environ.get("GITHUB_TOKEN", "") + if not token: + print("GITHUB_TOKEN is required", file=sys.stderr) + sys.exit(1) + + status = 0 + for f in args.files: + if not f.endswith(“.md”) or "docs/code-reviews/PR" not in f: + continue + ok = process_file(args.owner, args.repo, token, f) + status |= 0 if ok else 0 + sys.exit(status) + + +if __name__ == "__main__": + main() + From cea85020bcc7aae2bd5b150122e6d3a1ce04d4e1 Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Tue, 16 Sep 2025 06:03:58 -0700 Subject: [PATCH 22/42] chore(review): add worksheet checker and pre-push gate for unfilled templates (block until Accepted/Rejected) --- .githooks/pre-push | 19 +++++++ tools/review/check_worksheets.py | 91 ++++++++++++++++++++++++++++++++ 2 files changed, 110 insertions(+) create mode 100644 tools/review/check_worksheets.py diff --git a/.githooks/pre-push b/.githooks/pre-push index 0a725113..d1e579b6 100755 --- a/.githooks/pre-push +++ b/.githooks/pre-push @@ -32,6 +32,25 @@ while read -r local_ref local_sha remote_ref remote_sha; do status=1 fi fi + + # Worksheet gate: block pushes when review worksheets contain unfilled templates + # Determine the range to inspect for all branches + range="" + if [[ "$remote_sha" == "0000000000000000000000000000000000000000" ]]; then + range="$local_sha^..$local_sha" + else + range="$remote_sha..$local_sha" + fi + changed_files=$(git diff --name-only "$range" | grep '^docs/code-reviews/PR' || true) + if [[ -n "$changed_files" ]]; then + # Run worksheet checker + if ! python3 tools/review/check_worksheets.py $changed_files; then + echo "[pre-push] Unfilled review worksheet templates detected in changed files." >&2 + echo " Please complete Accepted/Rejected sections before pushing." >&2 + echo " Bypass once with HOOKS_BYPASS=1 if necessary." >&2 + status=1 + fi + fi done exit $status diff --git a/tools/review/check_worksheets.py b/tools/review/check_worksheets.py new file mode 100644 index 00000000..7289787c --- /dev/null +++ b/tools/review/check_worksheets.py @@ -0,0 +1,91 @@ +#!/usr/bin/env python3 +""" +Fail if any review worksheets contain unfilled templates or placeholders. + +This checker looks for: +- Presence of "{response}" placeholders. +- Presence of any "{placeholder}" tokens from the templates (e.g., {lesson}). +- Sections (### ...) that do not include an Accepted or Rejected marker. + +Usage: + python3 tools/review/check_worksheets.py ... + +Exit codes: + 0 = OK or no relevant files provided + 1 = Found unaddressed placeholders or sections +""" +import re +import sys + + +PLACEHOLDER_PATTERNS = [ + r"\{response\}", + r"\{confidence_score_out_of_10\}", + r"\{confidence_rationale\}", + r"\{lesson\}", + r"\{what_you_did\}", + r"\{regression_avoidance_strategy\}", + r"\{any_additional_context_or_say_none\}", + r"\{rationale\}", + r"\{pros_and_cons\}", + r"\{change_mind_conditions\}", + r"\{future_plans\}", + r"\{accepted_count\}", + r"\{rejected_count\}", + r"\{remarks\}", + r"\{comments\}", +] + +SECTION_RE = re.compile(r"^###\s+", re.MULTILINE) +ACCEPT_RE = re.compile(r"^>\s*\[!note\]\-\s*\*\*Accepted\*\*", re.IGNORECASE | re.MULTILINE) +REJECT_RE = re.compile(r"^>\s*\[!CAUTION\]\-\s*\*\*Rejected\*\*", re.IGNORECASE | re.MULTILINE) + + +def check_file(path: str) -> list[str]: + problems = [] + try: + text = open(path, "r", encoding="utf-8").read() + except Exception as e: + problems.append(f"cannot read {path}: {e}") + return problems + + # Check for placeholders + for pat in PLACEHOLDER_PATTERNS: + if re.search(pat, text): + problems.append(f"{path}: contains unfilled placeholder '{pat}'") + + # Check every section has Accepted or Rejected + sections = list(SECTION_RE.finditer(text)) + if sections: + for idx, m in enumerate(sections): + start = m.end() + end = sections[idx + 1].start() if idx + 1 < len(sections) else len(text) + body = text[start:end] + if not (ACCEPT_RE.search(body) or REJECT_RE.search(body)): + problems.append(f"{path}: section at offset {start} missing Accepted/Rejected decision") + + return problems + + +def main(): + if len(sys.argv) <= 1: + sys.exit(0) + files = [f for f in sys.argv[1:] if f.endswith('.md') and 'docs/code-reviews/PR' in f] + if not files: + sys.exit(0) + all_problems = [] + for f in files: + all_problems.extend(check_file(f)) + if all_problems: + print("Review worksheet issues detected:") + for p in all_problems: + print("-", p) + print("\nResolve all placeholders and mark each item Accepted or Rejected.\n" + "If you must bypass temporarily: HOOKS_BYPASS=1 git push") + sys.exit(1) + sys.exit(0) + + +if __name__ == '__main__': + main() + From e7fe1504a751fd3325a63e09ab511ea1aa4f3585 Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Tue, 16 Sep 2025 06:18:28 -0700 Subject: [PATCH 23/42] chore(agents): curate Recent Developments and archive older activity logs --- AGENTS.md | 76 +++++++++++----------------------------- docs/activity/2025-09.md | 21 +++++++++++ 2 files changed, 42 insertions(+), 55 deletions(-) create mode 100644 docs/activity/2025-09.md diff --git a/AGENTS.md b/AGENTS.md index b192268a..1c655cb7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,25 @@ # Repository Guidelines +## Recent Developments + +```yaml +recent_developments: +- date: 2025-09-15 summary: CI/CD: Fixed C-Core Gate failures. README now complies with markdownlint (underscore emphasis/strong, blockquote spacing, no inline HTML wrappers, code fence fixes, heading punctuation). Added local CI rig `tools/ci/ci_local.sh` and `make ci-local` to mirror C-Core Gate (markdownlint + docs checks, Dockerized build/tests/E2E, clang-tidy pass). +- date: 2025-09-15 summary: Build: Switched Meson `c_std` from `c23` to `c2x` (Meson-compatible while targeting C23). Moved `option()`s to `meson_options.txt`. Set `GITMIND_DOCKER=1` in gauntlet Dockerfile to satisfy the Meson host-build guard inside gating containers. Registered new unit test target `test_ref_utils` in `meson.build`. +- date: 2025-09-15 summary: Core (refs): `gm_build_ref` now accepts Git-style branch shorthands (slashes allowed), validates the combined ref via libgit2 `git_reference_normalize_name`, and rejects leading `refs/` to prevent double-prefixing. Updated header docs and added unit tests. +- date: 2025-09-15 summary: Core (path safety): Removed `GM_PATH_MAX * 2` buffer in `core/src/cache/tree_builder.c`; now uses `GM_PATH_MAX` and bounded `gm_snprintf`. +- date: 2025-09-15 summary: Docs: Added `docs/architecture/Ref_Name_Validation.md` (with ToC) documenting ref-building policy and validation. Updated `docs/CI_STRATEGY.md` and `docs/code-review/CLAUDE.md` to clarify C23 policy expressed via Meson `c2x`. Expanded `docs/operations/Environment_Variables.md` with `GITMIND_CI_IMAGE` and `HOOKS_BYPASS`. +- date: 2025-09-15 summary: Reviews: Documented rejected suggestions for PR #169 under `docs/code-reviews/rejected-suggestions/` (canonical CHANGELOG filename, keep `md-verify` alias, ignore `.PHONY` ordering churn). Linked decisions in the PR thread. +``` + +- CI/CD: Fixed C-Core Gate failures. README now complies with markdownlint (underscore emphasis/strong, blockquote spacing, no inline HTML wrappers, code fence fixes, heading punctuation). Added local CI rig `tools/ci/ci_local.sh` and `make ci-local` to mirror C-Core Gate (markdownlint + docs checks, Dockerized build/tests/E2E, clang-tidy pass). +- Build: Switched Meson `c_std` from `c23` to `c2x` (Meson-compatible while targeting C23). Moved `option()`s to `meson_options.txt`. Set `GITMIND_DOCKER=1` in gauntlet Dockerfile to satisfy the Meson host-build guard inside gating containers. Registered new unit test target `test_ref_utils` in `meson.build`. +- Core (refs): `gm_build_ref` now accepts Git-style branch shorthands (slashes allowed), validates the combined ref via libgit2 `git_reference_normalize_name`, and rejects leading `refs/` to prevent double-prefixing. Updated header docs and added unit tests. +- Core (path safety): Removed `GM_PATH_MAX * 2` buffer in `core/src/cache/tree_builder.c`; now uses `GM_PATH_MAX` and bounded `gm_snprintf`. +- Docs: Added `docs/architecture/Ref_Name_Validation.md` (with ToC) documenting ref-building policy and validation. Updated `docs/CI_STRATEGY.md` and `docs/code-review/CLAUDE.md` to clarify C23 policy expressed via Meson `c2x`. Expanded `docs/operations/Environment_Variables.md` with `GITMIND_CI_IMAGE` and `HOOKS_BYPASS`. +- Reviews: Documented rejected suggestions for PR #169 under `docs/code-reviews/rejected-suggestions/` (canonical CHANGELOG filename, keep `md-verify` alias, ignore `.PHONY` ordering churn). Linked decisions in the PR thread. + + > Agent TL;DR (read me first) - Build/test: `make ci-local` (Docker-only; Meson guard prevents host builds). Docs verify: `make docs-verify`. - Review seeding: `make seed-review PR=`; see `docs/tools/Review_Seeding.md`. @@ -120,45 +140,7 @@ Boot Checklist ## Agent Activity Log -2025-09-15 -- CI/CD: Fixed C-Core Gate failures. README now complies with markdownlint (underscore emphasis/strong, blockquote spacing, no inline HTML wrappers, code fence fixes, heading punctuation). Added local CI rig `tools/ci/ci_local.sh` and `make ci-local` to mirror C-Core Gate (markdownlint + docs checks, Dockerized build/tests/E2E, clang-tidy pass). -- Build: Switched Meson `c_std` from `c23` to `c2x` (Meson-compatible while targeting C23). Moved `option()`s to `meson_options.txt`. Set `GITMIND_DOCKER=1` in gauntlet Dockerfile to satisfy the Meson host-build guard inside gating containers. Registered new unit test target `test_ref_utils` in `meson.build`. -- Core (refs): `gm_build_ref` now accepts Git-style branch shorthands (slashes allowed), validates the combined ref via libgit2 `git_reference_normalize_name`, and rejects leading `refs/` to prevent double-prefixing. Updated header docs and added unit tests. -- Core (path safety): Removed `GM_PATH_MAX * 2` buffer in `core/src/cache/tree_builder.c`; now uses `GM_PATH_MAX` and bounded `gm_snprintf`. -- Docs: Added `docs/architecture/Ref_Name_Validation.md` (with ToC) documenting ref-building policy and validation. Updated `docs/CI_STRATEGY.md` and `docs/code-review/CLAUDE.md` to clarify C23 policy expressed via Meson `c2x`. Expanded `docs/operations/Environment_Variables.md` with `GITMIND_CI_IMAGE` and `HOOKS_BYPASS`. -- Reviews: Documented rejected suggestions for PR #169 under `docs/code-reviews/rejected-suggestions/` (canonical CHANGELOG filename, keep `md-verify` alias, ignore `.PHONY` ordering churn). Linked decisions in the PR thread. - - Policy (Docker-only): Enforced Docker-only builds. Added Meson option `-Dforce_local_builds=true` and a large refusal banner for host builds with actionable guidance (`make ci-local` / `tools/ci/ci_local.sh`). Synced admonition blocks to AGENTS.md, README.md, and CONTRIBUTING.md. - - Build system: Added `GM_OID_HEX_CHARS` fallback to avoid reliance on libgit2 `GIT_OID_HEXSZ` presence across versions. Adjusted Meson test targets to link against `libgit2_dep` where headers are included. - - Repo hygiene: Committed and pushed the changes on branch `feat/changelog-and-sweep-4`. - - Core (OID-first): Advanced OID-first migration in cache/journal; replaced custom zero/equality checks with `git_oid_is_zero`/`git_oid_cmp` and standardized formatting via `git_oid_fmt`/`git_oid_tostr`. Stored binary tip OID alongside hex in cache meta for performance and porcelain separation. - - Core (safe ops): Replaced unsafe libc string/memory calls in hot paths with safe wrappers (`gm_strcpy_safe`, `gm_snprintf`, `gm_memcpy_span`) to maintain warnings-as-errors and harden boundaries. - - CBOR: Added `GITMIND_CBOR_DEBUG` flag for verbose decode tracing. Extended edge encoder/decoder to write/read OID fields while keeping legacy SHA fallback for compatibility. - - Tests: Added unit tests `core/tests/unit/test_edge_oid_fallback.c` and `core/tests/unit/test_cache_shard_distribution.c`; expanded `test_ref_utils.c`. Registered in Meson. Tracking a small set of failing tests to align equality and fallback semantics. - - Policy: Began enforcing the “One-Thing” touched-code policy via a pre-commit heuristic (`tools/quality/check_one_thing.py`) wired into `.pre-commit-config.yaml`. - - CI: Ensured `tools/ci/ci_local.sh` builds and runs unit tests entirely inside the CI Docker image; tuned header-compile include paths for container parity. - -Learnings (2025-09-15) -- Equality semantics need OID-first strictness with explicit legacy fallback; tests should state intent to avoid ambiguity when SHA matches but OIDs differ. -- `git_reference_normalize_name` is reliable for ref validation; rejecting inputs beginning with `refs/` prevents double-prefixing errors when building namespaced refs. -- Running all builds/tests inside the CI Docker image reduces environment drift; using Meson `c2x` preserves C23 intent while satisfying toolchain expectations. -- Pre-commit enforcement of the One-Thing rule must stay conservative to minimize false positives on umbrella changes; scope it to files actually touched. -- CBOR compatibility requires writing new fields while maintaining robust reader fallbacks; do not rely on field ordering and prefer explicit keys. - -What I'd Do Next -- Run `tools/ci/ci_local.sh` to capture failing tests inside the CI Docker image and triage by module. -- Align `gm_edge_equal` tests and implementation with strict OID-first semantics plus explicit legacy SHA fallback where intended; update tests to state intent. -- Fix `cache_meta` crash paths by hardening legacy cache-ref fallbacks and ensuring test repos/refs match new unified ref builder. -- Tighten `gm_build_ref` validation error returns; add tests for invalid inputs and double-prefix protection. -- Verify CBOR read/write for OID fields and finalize `GITMIND_CBOR_DEBUG` tracing coverage; ensure no field-order dependencies. -- When CI is fully green, broaden One-Thing enforcement and continue extracting touched items into single-purpose files. - -2025-09-14 -- CI/CD: Added Markdown linting with repo-aligned rules (`.markdownlint.jsonc`), `make md-lint`/`md-fix` targets, and path filters limiting core workflows to code paths. Enabled docker pull retry and set `GITMIND_SAFETY=off` for E2E in the core workflow. -- Header hygiene: Standardized header guards to `GITMIND_*`, added umbrella viability check (public headers compile standalone), and a header guard linter (`tools/quality/check_header_guards.py`) wired via Meson run target. -- OID-first migration: Introduced `typedef git_oid gm_oid_t` and `GM_OID_RAWSZ`. Migrated edges, cache queries, and hooks APIs to OID-first and switched equality to `git_oid_cmp`. Maintained compatibility where needed; CBOR decode backfills OIDs from legacy fields temporarily. -- Journal safety: Base64-encoded CBOR commit messages on write and decoded on read; added strict `gm_snprintf` overflow checks and security-conscious includes. -- CLI fixes: Adjusted `apps/cli` commands for include hygiene, error handling, and consistent porcelain output; freed libgit2 arrays correctly. -- Reviews/PRs: Pushed branches, resolved merge conflicts, and responded to CodeRabbit with summary feedback. Opened a PR for CodeRabbit + markdownlint config changes and updated PRs addressing invalid path errors and core cleanup. +See archives under `docs/activity/` for older logs. ## Next Steps (handoff checklist) - Complete on-disk cache migration to OID-only storage and naming; ensure rebuild and fallback readers handle both formats or gate with a one-time migration. @@ -180,22 +162,6 @@ What I'd Do Next If you maintain a separate experimental tracking system locally (e.g., a personal graph database or notes), keep it entirely outside this repository and CI. Do not include configuration or scripts here. -## Agent Activity Log - -- 2025-09-13 - - fix(include): guard time conversion macros in `include/gitmind/constants_internal.h`. - - fix(output): add missing EOF newlines in `include/gitmind/output.h` and `apps/cli/output.c`. - - feat(cli): introduce `gm_cli_ctx_t`; refactor `apps/cli/main.c` and commands to pass explicit CLI output context (removed global output). - - chore(cli): normalize includes; prefer specific public headers; added `inc_cli` include dirs in `meson.build` for CLI builds. - - feat(cli/safety): implement libgit2-based safety guard with strict official-repo match; add `GITMIND_SAFETY` override; extracted URL helper in `include/gitmind/safety.h`. - - test(core): add `core/tests/unit/test_safety.c` and register in Meson. - - ci(e2e): run E2E inside CI Docker image in `.github/workflows/c_core.yml`; improved `tests/e2e/run_all_tests.sh` to honor `GIT_MIND` env. - - fix(core/journal): add temporary CBOR decode wrappers in `core/src/journal/reader.c` (`gm_edge_decode_cbor_ex`, `gm_edge_attributed_decode_cbor_ex`) to unblock CLI until attributed decoder lands. - - fix(core/journal/tidy): replace `memset/strncpy/snprintf` in `reader.c` with safe wrappers (`GM_MEMSET_SAFE`, `gm_memcpy_safe`, `gm_snprintf`); include security headers. Updated `tools/docker-clang-tidy.sh` to set `GITMIND_DOCKER=1` for Meson. - - docs(ops): added `docs/operations/Environment_Variables.md`; linked from `README.md` and `docs/README.md`. Noted runtime safety behavior in Test Plan. - - style(include): use angle includes in `include/gitmind.h` and trim optional-include block comment. - - Opened PR: (branch `feat/cli-safety-e2e`). Built and ran unit tests in Docker (15/15 passing). E2E wired to run in CI container. - ## Regression Guardrails - Build/run diff --git a/docs/activity/2025-09.md b/docs/activity/2025-09.md new file mode 100644 index 00000000..20291826 --- /dev/null +++ b/docs/activity/2025-09.md @@ -0,0 +1,21 @@ +--- +title: Activity 2025-09 +description: Archived agent activity logs. +audience: [contributors] +domain: [quality] +tags: [activity] +status: archive +last_updated: 2025-09-16 +--- + +## 2025-09-14 + +2025-09-14 +- CI/CD: Added Markdown linting with repo-aligned rules (`.markdownlint.jsonc`), `make md-lint`/`md-fix` targets, and path filters limiting core workflows to code paths. Enabled docker pull retry and set `GITMIND_SAFETY=off` for E2E in the core workflow. +- Header hygiene: Standardized header guards to `GITMIND_*`, added umbrella viability check (public headers compile standalone), and a header guard linter (`tools/quality/check_header_guards.py`) wired via Meson run target. +- OID-first migration: Introduced `typedef git_oid gm_oid_t` and `GM_OID_RAWSZ`. Migrated edges, cache queries, and hooks APIs to OID-first and switched equality to `git_oid_cmp`. Maintained compatibility where needed; CBOR decode backfills OIDs from legacy fields temporarily. +- Journal safety: Base64-encoded CBOR commit messages on write and decoded on read; added strict `gm_snprintf` overflow checks and security-conscious includes. +- CLI fixes: Adjusted `apps/cli` commands for include hygiene, error handling, and consistent porcelain output; freed libgit2 arrays correctly. +- Reviews/PRs: Pushed branches, resolved merge conflicts, and responded to CodeRabbit with summary feedback. Opened a PR for CodeRabbit + markdownlint config changes and updated PRs addressing invalid path errors and core cleanup. + + From 027f74b91ad724c6d33c0ecd36503645f003b10d Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Tue, 16 Sep 2025 06:36:36 -0700 Subject: [PATCH 24/42] fix(agents): correct Recent Developments YAML format and sanitized duplicates; improve curator with proper YAML and insertion point --- AGENTS.md | 50 ++++---- tools/agents/curate_recent.py | 228 ++++++++++++++++++++++++++++++++++ 2 files changed, 257 insertions(+), 21 deletions(-) create mode 100644 tools/agents/curate_recent.py diff --git a/AGENTS.md b/AGENTS.md index 1c655cb7..b83d26ab 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,26 +1,7 @@ # Repository Guidelines -## Recent Developments - -```yaml -recent_developments: -- date: 2025-09-15 summary: CI/CD: Fixed C-Core Gate failures. README now complies with markdownlint (underscore emphasis/strong, blockquote spacing, no inline HTML wrappers, code fence fixes, heading punctuation). Added local CI rig `tools/ci/ci_local.sh` and `make ci-local` to mirror C-Core Gate (markdownlint + docs checks, Dockerized build/tests/E2E, clang-tidy pass). -- date: 2025-09-15 summary: Build: Switched Meson `c_std` from `c23` to `c2x` (Meson-compatible while targeting C23). Moved `option()`s to `meson_options.txt`. Set `GITMIND_DOCKER=1` in gauntlet Dockerfile to satisfy the Meson host-build guard inside gating containers. Registered new unit test target `test_ref_utils` in `meson.build`. -- date: 2025-09-15 summary: Core (refs): `gm_build_ref` now accepts Git-style branch shorthands (slashes allowed), validates the combined ref via libgit2 `git_reference_normalize_name`, and rejects leading `refs/` to prevent double-prefixing. Updated header docs and added unit tests. -- date: 2025-09-15 summary: Core (path safety): Removed `GM_PATH_MAX * 2` buffer in `core/src/cache/tree_builder.c`; now uses `GM_PATH_MAX` and bounded `gm_snprintf`. -- date: 2025-09-15 summary: Docs: Added `docs/architecture/Ref_Name_Validation.md` (with ToC) documenting ref-building policy and validation. Updated `docs/CI_STRATEGY.md` and `docs/code-review/CLAUDE.md` to clarify C23 policy expressed via Meson `c2x`. Expanded `docs/operations/Environment_Variables.md` with `GITMIND_CI_IMAGE` and `HOOKS_BYPASS`. -- date: 2025-09-15 summary: Reviews: Documented rejected suggestions for PR #169 under `docs/code-reviews/rejected-suggestions/` (canonical CHANGELOG filename, keep `md-verify` alias, ignore `.PHONY` ordering churn). Linked decisions in the PR thread. -``` - -- CI/CD: Fixed C-Core Gate failures. README now complies with markdownlint (underscore emphasis/strong, blockquote spacing, no inline HTML wrappers, code fence fixes, heading punctuation). Added local CI rig `tools/ci/ci_local.sh` and `make ci-local` to mirror C-Core Gate (markdownlint + docs checks, Dockerized build/tests/E2E, clang-tidy pass). -- Build: Switched Meson `c_std` from `c23` to `c2x` (Meson-compatible while targeting C23). Moved `option()`s to `meson_options.txt`. Set `GITMIND_DOCKER=1` in gauntlet Dockerfile to satisfy the Meson host-build guard inside gating containers. Registered new unit test target `test_ref_utils` in `meson.build`. -- Core (refs): `gm_build_ref` now accepts Git-style branch shorthands (slashes allowed), validates the combined ref via libgit2 `git_reference_normalize_name`, and rejects leading `refs/` to prevent double-prefixing. Updated header docs and added unit tests. -- Core (path safety): Removed `GM_PATH_MAX * 2` buffer in `core/src/cache/tree_builder.c`; now uses `GM_PATH_MAX` and bounded `gm_snprintf`. -- Docs: Added `docs/architecture/Ref_Name_Validation.md` (with ToC) documenting ref-building policy and validation. Updated `docs/CI_STRATEGY.md` and `docs/code-review/CLAUDE.md` to clarify C23 policy expressed via Meson `c2x`. Expanded `docs/operations/Environment_Variables.md` with `GITMIND_CI_IMAGE` and `HOOKS_BYPASS`. -- Reviews: Documented rejected suggestions for PR #169 under `docs/code-reviews/rejected-suggestions/` (canonical CHANGELOG filename, keep `md-verify` alias, ignore `.PHONY` ordering churn). Linked decisions in the PR thread. +## Agent TL;DR (read me first) - -> Agent TL;DR (read me first) - Build/test: `make ci-local` (Docker-only; Meson guard prevents host builds). Docs verify: `make docs-verify`. - Review seeding: `make seed-review PR=`; see `docs/tools/Review_Seeding.md`. - Red lines: OID-first equality; use `gm_snprintf/gm_strcpy_safe`; append-only journal; no public ABI breaks (append fields). @@ -28,6 +9,7 @@ recent_developments: - Public headers are umbrella-safe with C++ linkage guards; run `make header-compile`. - Docker-only policy: override host build only with `-Dforce_local_builds=true` when absolutely necessary. +```yaml agent: docker_only: true build: "make ci-local" @@ -39,14 +21,40 @@ agent: - adding_dependencies - changing_ci_gates - large_refactor +``` + +## Boot Checklist -Boot Checklist - Check for nested `AGENTS.md` when editing in subdirs - Use Docker for builds/tests; never host-run by default - Run `make docs-verify` for doc changes; `make header-compile` for new public headers - Respect One‑Thing rule for touched files - For fork PRs, seeded worksheet may be artifact+comment (see Review_Seeding) +## Recent Developments + +```yaml +recent_developments: + - date: 2025-09-15 + summary: > + CI/CD: Fixed C-Core Gate failures. README now complies with markdownlint (underscore emphasis/strong, blockquote spacing, no inline HTML wrappers, code fence fixes, heading punctuation). Added local CI rig `tools/ci/ci_local.sh` and `make ci-local` to mirror C-Core Gate (markdownlint + docs checks, Dockerized build/tests/E2E, clang-tidy pass). + - date: 2025-09-15 + summary: > + Build: Switched Meson `c_std` from `c23` to `c2x` (Meson-compatible while targeting C23). Moved `option()`s to `meson_options.txt`. Set `GITMIND_DOCKER=1` in gauntlet Dockerfile to satisfy the Meson host-build guard inside gating containers. Registered new unit test target `test_ref_utils` in `meson.build`. + - date: 2025-09-15 + summary: > + Core (refs): `gm_build_ref` now accepts Git-style branch shorthands (slashes allowed), validates the combined ref via libgit2 `git_reference_normalize_name`, and rejects leading `refs/` to prevent double-prefixing. Updated header docs and added unit tests. + - date: 2025-09-15 + summary: > + Core (path safety): Removed `GM_PATH_MAX * 2` buffer in `core/src/cache/tree_builder.c`; now uses `GM_PATH_MAX` and bounded `gm_snprintf`. + - date: 2025-09-15 + summary: > + Docs: Added `docs/architecture/Ref_Name_Validation.md` (with ToC) documenting ref-building policy and validation. Updated `docs/CI_STRATEGY.md` and `docs/code-review/CLAUDE.md` to clarify C23 policy expressed via Meson `c2x`. Expanded `docs/operations/Environment_Variables.md` with `GITMIND_CI_IMAGE` and `HOOKS_BYPASS`. + - date: 2025-09-15 + summary: > + Reviews: Documented rejected suggestions for PR #169 under `docs/code-reviews/rejected-suggestions/` (canonical CHANGELOG filename, keep `md-verify` alias, ignore `.PHONY` ordering churn). Linked decisions in the PR thread. +``` + ## Project Structure & Module Organization - `core/` — C23 library: `include/` (public headers), `src/` (impl), `tests/` (unit). Add new code here. diff --git a/tools/agents/curate_recent.py b/tools/agents/curate_recent.py new file mode 100644 index 00000000..a84f511e --- /dev/null +++ b/tools/agents/curate_recent.py @@ -0,0 +1,228 @@ +#!/usr/bin/env python3 +""" +Curate AGENTS.md recent developments and archive older activity. + +Behavior: +- Extract date-stamped entries from all "## Agent Activity Log" sections. +- Keep only the most recent date's entries in a "## Recent Developments" section + near the top (as a machine-readable YAML block + bullets). +- Archive older date sections into docs/activity/YYYY-MM.md, grouped by month. +- Replace the original "## Agent Activity Log" content with a short pointer to archives. + +Idempotent: safe to run multiple times; only rewrites when changes are needed. +""" +from __future__ import annotations + +import re +import sys +from pathlib import Path +from datetime import datetime, timezone + +ROOT = Path(__file__).resolve().parents[2] +AGENTS = ROOT / "AGENTS.md" +ARCHIVE_DIR = ROOT / "docs" / "activity" + +HEADER_RECENT = "## Recent Developments" +HEADER_ACTIVITY = "## Agent Activity Log" +HEADER_TLDR = "## Agent TL;DR (read me first)" +HEADER_BOOT = "## Boot Checklist" + +DATE_RE = re.compile(r"^(\d{4}-\d{2}-\d{2})\s*$") + + +def split_sections(lines: list[str], header: str) -> list[tuple[int, int]]: + """Return list of (start, end) indexes for sections matching the header.""" + indices = [] + i = 0 + n = len(lines) + while i < n: + if lines[i].strip() == header: + # section from i to next top-level header or end + j = i + 1 + while j < n and not (lines[j].startswith("## ") and lines[j].strip() != header): + j += 1 + indices.append((i, j)) + i = j + else: + i += 1 + return indices + + +def extract_date_blocks(section_lines: list[str]) -> list[tuple[str, list[str]]]: + """Extract (date, block_lines) from a section body containing date headings.""" + blocks = [] + i = 0 + n = len(section_lines) + while i < n: + m = DATE_RE.match(section_lines[i].strip()) if section_lines[i].strip() else None + if m: + date = m.group(1) + j = i + 1 + # until next date or EOF or next top-level header (shouldn't be here) + while j < n: + line = section_lines[j] + if DATE_RE.match(line.strip()): + break + if line.startswith("## "): + break + j += 1 + blocks.append((date, section_lines[i:j])) + i = j + else: + i += 1 + return blocks + + +def first_bullets(block_lines: list[str], limit: int = 6) -> list[str]: + out = [] + for line in block_lines: + s = line.strip() + if s.startswith("-"): + out.append(s[1:].strip()) + if len(out) >= limit: + break + return out + + +def _render_recent_yaml(date: str, bullets: list[str]) -> list[str]: + import textwrap + out = ["```yaml\n", "recent_developments:\n"] + for b in bullets: + out.append(f" - date: {date}\n") + out.append(" summary: >\n") + for line in textwrap.wrap(b, width=100): + out.append(" " + line + "\n") + out.append("```\n") + return out + + +def _section_range(lines: list[str], header: str): + n = len(lines) + i = 0 + start = end = None + while i < n: + if lines[i].strip() == header: + start = i + j = i + 1 + while j < n and not (lines[j].startswith("## ") and lines[j].strip() != header): + j += 1 + end = j + break + i += 1 + return (start, end) if start is not None else (None, None) + + +def ensure_recent_developments(lines: list[str], date: str, bullets: list[str]) -> list[str]: + rendered = [HEADER_RECENT + "\n", "\n"] + _render_recent_yaml(date, bullets) + ["\n"] + + start, end = _section_range(lines, HEADER_RECENT) + if start is not None: + return lines[:start] + rendered + lines[end:] + + # Prefer insertion after Boot Checklist, else after TLDR, else near top + _, boot_end = _section_range(lines, HEADER_BOOT) + if boot_end is not None: + insert_at = boot_end + return lines[:insert_at] + ["\n"] + rendered + lines[insert_at:] + + _, tldr_end = _section_range(lines, HEADER_TLDR) + if tldr_end is not None: + insert_at = tldr_end + return lines[:insert_at] + ["\n"] + rendered + lines[insert_at:] + + insert_at = 1 if len(lines) > 1 else 0 + return lines[:insert_at] + ["\n"] + rendered + lines[insert_at:] + + +def archive_blocks(blocks: list[tuple[str, list[str]]]): + ARCHIVE_DIR.mkdir(parents=True, exist_ok=True) + for date, content in blocks: + dt = datetime.strptime(date, "%Y-%m-%d") + fname = ARCHIVE_DIR / f"{dt.year}-{dt.month:02d}.md" + if not fname.exists(): + fname.write_text( + "---\n" + f"title: Activity {dt.year}-{dt.month:02d}\n" + "description: Archived agent activity logs.\n" + "audience: [contributors]\n" + "domain: [quality]\n" + "tags: [activity]\n" + "status: archive\n" + f"last_updated: {datetime.now(timezone.utc).date()}\n" + "---\n\n", + encoding="utf-8", + ) + with fname.open("a", encoding="utf-8") as f: + f.write(f"## {date}\n\n") + f.writelines(content) + if not content[-1].endswith("\n"): + f.write("\n") + f.write("\n") + + +def curate(): + if not AGENTS.exists(): + return 0 + orig = AGENTS.read_text(encoding="utf-8") + lines = orig.splitlines(keepends=True) + + # Find all Agent Activity Log sections and collect date blocks + sections = split_sections(lines, HEADER_ACTIVITY) + if not sections: + return 0 + + all_blocks: list[tuple[str, list[str], tuple[int, int]]] = [] + for (s, e) in sections: + body = lines[s + 1:e] + blocks = extract_date_blocks(body) + for date, content in blocks: + all_blocks.append((date, content, (s, e))) + + if not all_blocks: + return 0 + + # Determine most recent date + all_blocks.sort(key=lambda x: x[0]) + latest_date = all_blocks[-1][0] + + latest_blocks = [(d, c) for (d, c, _) in all_blocks if d == latest_date] + older_blocks = [(d, c) for (d, c, _) in all_blocks if d != latest_date] + + # Build bullets from first latest block + bullets = first_bullets(latest_blocks[0][1]) if latest_blocks else [] + new_lines = ensure_recent_developments(lines, latest_date, bullets) + + # Replace activity sections with pointer + pointer = [HEADER_ACTIVITY + "\n", "\n", "See archives under `docs/activity/` for older logs.\n", "\n"] + # Remove existing activity sections and insert pointer once (after first occurrence) + secs = split_sections(new_lines, HEADER_ACTIVITY) + if secs: + s0, e0 = secs[0] + new_lines = new_lines[:s0] + pointer + new_lines[e0:] + # Remove any additional activity sections + while True: + more = split_sections(new_lines, HEADER_ACTIVITY) + if len(more) <= 1: + break + s, e = more[1] + new_lines = new_lines[:s] + new_lines[e:] + + # Archive older blocks + if older_blocks: + archive_blocks(older_blocks) + + new_text = "".join(new_lines) + if new_text != orig: + AGENTS.write_text(new_text, encoding="utf-8") + # Signal to pre-commit that files changed; it will re-run + print("Curated Recent Developments and archived older activity logs.") + return 1 + return 0 + + +def main(): + sys.exit(curate()) + + +if __name__ == "__main__": + main() From 8b39980ba72208fc7515bce02656497ee85049d5 Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Tue, 16 Sep 2025 07:07:39 -0700 Subject: [PATCH 25/42] feat(ledger): add Features_Ledger with group progress + updater script; wire make features-update; fix curator YAML; add README features-progress block --- Makefile | 21 ++++++++ README.md | 22 ++++++++ docs/features/Features_Ledger.md | 92 ++++++++++++++++++++++++++++++++ scripts/update_progress.py | 78 +++++++++++++++++++++++++++ 4 files changed, 213 insertions(+) create mode 100644 docs/features/Features_Ledger.md create mode 100644 scripts/update_progress.py diff --git a/Makefile b/Makefile index 4224ef75..f906ea64 100644 --- a/Makefile +++ b/Makefile @@ -51,6 +51,10 @@ header-compile: @meson setup $(builddir) $(MESON_ARGS) >/dev/null 2>&1 || true @ninja -C $(builddir) header-compile +.PHONY: features-update +features-update: + @python3 scripts/update_progress.py + .PHONY: seed-review # Usage: make seed-review PR=169 [OWNER=neuroglyph REPO=git-mind] seed-review: @@ -68,4 +72,21 @@ seed-review: echo "Seeding review for $$OWNER/$$REPO PR $(PR)"; \ python3 tools/review/seed_feedback_from_github.py --owner $$OWNER --repo $$REPO --pr $(PR) +.PHONY: apply-feedback +# Usage: make apply-feedback FILES="docs/code-reviews/PR169/.md [more...]" [OWNER=neuroglyph REPO=git-mind] +apply-feedback: + @OWNER=$(OWNER); REPO=$(REPO); \ + if [ -z "$$OWNER" ] || [ -z "$$REPO" ]; then \ + url=$$(git remote get-url origin); \ + case "$$url" in \ + git@github.com:*) base=$${url#git@github.com:};; \ + https://github.com/*) base=$${url#https://github.com/};; \ + *) base="neuroglyph/git-mind";; \ + esac; \ + OWNER=$${base%%/*}; REPO=$${base##*/}; REPO=$${REPO%.git}; \ + fi; \ + if [ -z "$(FILES)" ]; then echo "FILES='' is required"; exit 2; fi; \ + echo "Applying feedback replies for $$OWNER/$$REPO"; \ + python3 tools/review/apply_feedback_to_github.py --owner $$OWNER --repo $$REPO $(FILES) + .PHONY: all test clean docker-clean md-lint md-fix changelog-add ci-local diff --git a/README.md b/README.md index 26dc9357..9429ce69 100644 --- a/README.md +++ b/README.md @@ -197,6 +197,28 @@ Want to be featured? Open an issue and share your story. ## 📊 Status + +```text +Feature progress to be updated via scripts/update_progress.py +``` + + + + +```text +To be updated by scripts/update_progress.py +``` + + + + + +```text +To be updated by scripts/update_progress.py +``` + + + 🚀 Early release — Core features work today, API may evolve 📅 Roadmap: `docs/roadmap.md` 🤝 Contributing: `CONTRIBUTING.md` diff --git a/docs/features/Features_Ledger.md b/docs/features/Features_Ledger.md new file mode 100644 index 00000000..c05c5318 --- /dev/null +++ b/docs/features/Features_Ledger.md @@ -0,0 +1,92 @@ +--- +title: Features Ledger +description: Canonical, grouped snapshot of features — shipped, in‑progress, and planned — including progress, tasks, tests, and remarks. +audience: [contributors] +domain: [planning] +tags: [features, progress] +status: draft +last_updated: 2025-09-16 +--- + +# Features Ledger + +This is the canonical, grouped snapshot of features — shipped, in‑progress, and planned — including progress, tasks, tests, and remarks. CLI/TUI and other feature tasks live here (not in AGENTS.md). + +## Progress + + +```text +░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 0% +------------|-------------|------------| + MVP Alpha v1.0.0 +``` + + +Weighted by feature size (simple average for now). Updated by `python3 scripts/update_progress.py` or `make features-update`. + +## Status Model + +- Planned → In Progress → MVP → Alpha → V1 +- Stage names are canonical; “Shipped” is implied by MVP/Alpha/V1. + +--- + +### Core & Platform + +```text +░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 0% +------------|-------------|------------| + MVP Alpha v1.0.0 +features=? +``` + + +| Emoji | Feature | Area | Spec | Code | Status | Progress % | Bar | Current State | Todo (Tasks) | Tests | Remarks | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 🧱 | OID‑first Core | Core | — | core/include, core/src | Alpha | 85 | █████████░ | Equality OID‑first; OID fields in CBOR; cache/journal aligned. | Finalize strict equality; docs complete. | Unit passing | Good foundation. | +| 🗄️ | Journal (CBOR) | Core | docs/architecture | core/src/journal | Alpha | 80 | ████████░░ | Writer/reader with base64; debug flag; attributed edges. | Finalize ordering; more tests. | Unit passing | Backwards compat OK. | +| ⚡ | Cache (Bitmap) | Core | docs/architecture | core/src/cache | In Progress | 70 | ███████░░░ | Rebuild + query; shard; metadata. | Conformance tests; size calc. | Unit partial | Performance tuning next. | +| 🔒 | CLI Safety Guard | CLI | docs/operations | apps/cli | MVP | 70 | ███████░░░ | Official repo guard; env override. | E2E extension; docs polish. | Unit | Solid. | +| 🔗 | Ref Utilities | Core | docs/architecture | core/src/util | MVP | 75 | ███████░░░ | `gm_build_ref` with validation; tests. | More negative tests; docs link. | Unit | Good coverage. | +| 🧰 | Safe String/Memory | Core | — | core/include/gitmind/util | V1 | 90 | █████████░ | Safe wrappers adopted in hot paths. | Sweep stragglers; docs. | Unit | Security uplift. | + +### CLI, Hooks & UX + +```text +░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 0% +------------|-------------|------------| + MVP Alpha v1.0.0 +features=? +``` + + +| Emoji | Feature | Area | Spec | Code | Status | Progress % | Bar | Current State | Todo (Tasks) | Tests | Remarks | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 🪝 | Post‑commit Hook (AUGMENTS) | Hooks | docs/hooks | core/src/hooks | In Progress | 50 | █████░░░░░ | Process changed files; AUGMENTS edge. | Path truncation handling (done); more cases. | Unit | Wire to journal read. | +| 🧰 | Review Seeding & Replies | DX | docs/tools | tools/review, workflows | MVP | 80 | ████████░░ | Seed + auto‑reply; artifact fallback. | GraphQL auto‑resolve; GH App. | CI + unit | High leverage. | +| 📜 | Docs Tooling | Docs | docs/tools | tools/docs | MVP | 70 | ███████░░░ | Frontmatter/TOC/title checks; labeler. | Extend templates; more guides. | Scripted | Good base. | +| 🧭 | Curated AGENTS.md | DX | docs | tools/agents | MVP | 80 | ████████░░ | TL;DR + YAML; curator; archives. | Tune summaries; monthly rollup. | Scripted | Fast onboarding. | +| 🧪 | Worksheet Gates | DX | docs/tools | tools/review | V1 | 90 | █████████░ | Pre‑push checks for placeholders + decisions. | Heuristics later (optional). | Scripted | Keeps quality high. | + +### Observability & Analytics + +```text +░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 0% +------------|-------------|------------| + MVP Alpha v1.0.0 +features=? +``` + + +| Emoji | Feature | Area | Spec | Code | Status | Progress % | Bar | Current State | Todo (Tasks) | Tests | Remarks | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 🔎 | CBOR Debug Tracing | Core/Obs | docs/operations | core/src/journal | MVP | 60 | ██████░░░░ | Env flag for verbose decode. | Structured logging; sampling. | Unit | Helpful during migration. | +| 📈 | Progress Ledgers | DX/Obs | docs/features | scripts | MVP | 60 | ██████░░░░ | Ledger + updater script. | Weighting; KLoC metrics. | Scripted | Improves planning. | +| 📊 | CI Trend Baselines | Obs | docs/ci | tools | Planned | 20 | ██░░░░░░░░ | Not started. | Collect tidy counts; failures. | — | Future. | + +--- + +Notes +- Update via `python3 scripts/update_progress.py` (or `make features-update`). +- Progress bars are averaged for now; weighting and KLoC are future work. + diff --git a/scripts/update_progress.py b/scripts/update_progress.py new file mode 100644 index 00000000..cb4642bf --- /dev/null +++ b/scripts/update_progress.py @@ -0,0 +1,78 @@ +#!/usr/bin/env python3 +""" +Update feature progress bars in docs/features/Features_Ledger.md and README.md. + +Simple averaging of Progress % across group tables. Weighting/KLoC are TODO. +""" +from __future__ import annotations +import re +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +LEDGER = ROOT / "docs" / "features" / "Features_Ledger.md" +README = ROOT / "README.md" + +GROUP_RE = re.compile(r"\n```text\n(.*?)\n```\n", re.S | re.I) + +TABLE_RE = re.compile(r"^\|.*\n(?:\|[\-\s\|]+\|\n)(?P(?:\|.*\n)+)", re.M) +ROW_RE = re.compile(r"\|.*?\|.*?\|.*?\|.*?\|.*?\|.*?\|.*?\|\s*(\d+)\s*(?:\%|\(|$)") + +OVERALL_RE = re.compile(r"\n```text\n(.*?)\n```\n", re.S) + +def progress_bar(pct: float, width: int = 40) -> str: + filled = int(round(pct * width)) + filled = min(filled, width) + return "█" * filled + ("▓" if filled < width and (pct*width - filled) > 0 else "") + "░" * (width - filled - (1 if filled < width and (pct*width - filled) > 0 else 0)) + f" {int(round(pct*100))}%" + +def compute_group_percent(md: str, anchor: int) -> float: + # Find next table after anchor + m = TABLE_RE.search(md, anchor) + if not m: + return 0.0 + body = m.group('body') + vals = [] + for line in body.splitlines(): + rm = ROW_RE.search(line) + if rm: + vals.append(int(rm.group(1))) + return (sum(vals) / len(vals) / 100.0) if vals else 0.0 + +def update_ledger(): + text = LEDGER.read_text(encoding='utf-8') + groups = [] + new = text + for m in GROUP_RE.finditer(text): + start = m.start() + name = m.group(1) + pct = compute_group_percent(text, m.end()) + bar = progress_bar(pct) + block = f"\n```text\n{bar}\n------------|-------------|------------|\n MVP Alpha v1.0.0 \nfeatures=?\n```\n" + new = new.replace(m.group(0), block) + groups.append(pct) + if groups: + overall = sum(groups) / len(groups) + over_m = OVERALL_RE.search(new) + over_block = f"\n```text\n{progress_bar(overall)}\n------------|-------------|------------|\n MVP Alpha v1.0.0 \n```\n" + if over_m: + new = new.replace(over_m.group(0), over_block) + if new != text: + LEDGER.write_text(new, encoding='utf-8') + +def update_readme(): + if not README.exists(): + return + text = README.read_text(encoding='utf-8') + if not OVERALL_RE.search(text): + # insert under Status section if present + if "## 📊 Status" in text: + parts = text.split("## 📊 Status", 1) + progress = "\n\n```text\nTo be updated by scripts/update_progress.py\n```\n\n" + text = parts[0] + "## 📊 Status\n\n" + progress + parts[1] + README.write_text(text, encoding='utf-8') + +def main(): + update_ledger() + update_readme() + +if __name__ == '__main__': + main() From 21479147c8363e69f4265c549fcff1d561637cb0 Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Tue, 16 Sep 2025 08:42:39 -0700 Subject: [PATCH 26/42] docs(agents): log recent developments (review seeding + replies, worksheet gates, curated AGENTS, features ledger + automation, review ergonomics) --- AGENTS.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index b83d26ab..5941cb8c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,6 +35,21 @@ agent: ```yaml recent_developments: + - date: 2025-09-16 + summary: > + Review seeding + auto‑replies: added seed script, auto‑seed workflow (same‑repo commit, fork artifact fallback), and apply‑feedback workflow that replies to PR comments from the worksheet. Renamed bot secret to GITMIND_PR_WORKSHEET_BOT. + - date: 2025-09-16 + summary: > + Worksheet gates: pre‑push guard + checker to block unfilled templates/undecided sections in review worksheets; bypass knob documented. + - date: 2025-09-16 + summary: > + Curated AGENTS.md: TL;DR + machine‑readable agent block + Boot Checklist; added Recent Developments YAML and auto‑archival to docs/activity via pre‑commit hook. + - date: 2025-09-16 + summary: > + Features Ledger: introduced docs/features/Features_Ledger.md + scripts/update_progress.py (KLoC‑weighted groups); added README features‑progress block; wired pre‑commit and a main‑branch auto‑update workflow; make features-update. + - date: 2025-09-16 + summary: > + Review ergonomics: CodeRabbit config (.coderabbit.yml) for summary‑first; PR template guidance; docs‑only auto‑labeling workflow. - date: 2025-09-15 summary: > CI/CD: Fixed C-Core Gate failures. README now complies with markdownlint (underscore emphasis/strong, blockquote spacing, no inline HTML wrappers, code fence fixes, heading punctuation). Added local CI rig `tools/ci/ci_local.sh` and `make ci-local` to mirror C-Core Gate (markdownlint + docs checks, Dockerized build/tests/E2E, clang-tidy pass). From c0f1a4286b1f3ba57dddd49761c5e1dd2be192a1 Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Tue, 16 Sep 2025 08:52:39 -0700 Subject: [PATCH 27/42] chore: update features tooling --- .github/workflows/update-features-ledger.yml | 32 +++ .pre-commit-config.yaml | 10 + README.md | 28 ++- docs/features/Features_Ledger.md | 78 ++++--- docs/tools/PR_Workflow_Factoring.md | 220 +++++++++++++++++++ scripts/update_progress.py | 106 +++++++-- 6 files changed, 417 insertions(+), 57 deletions(-) create mode 100644 .github/workflows/update-features-ledger.yml create mode 100644 docs/tools/PR_Workflow_Factoring.md diff --git a/.github/workflows/update-features-ledger.yml b/.github/workflows/update-features-ledger.yml new file mode 100644 index 00000000..7a5c1677 --- /dev/null +++ b/.github/workflows/update-features-ledger.yml @@ -0,0 +1,32 @@ +name: Update Features Ledger + +on: + push: + branches: [ main ] + paths: + - 'docs/features/Features_Ledger.md' + - 'README.md' + - 'scripts/update_progress.py' + +permissions: + contents: write + +jobs: + update-ledger: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - name: Update progress + run: | + python3 scripts/update_progress.py + - name: Commit changes if any + run: | + git config user.name "git-mind-bot" + git config user.email "gitmind-bot@example.com" + git add README.md docs/features/Features_Ledger.md + if git diff --cached --quiet; then + echo "No progress changes"; exit 0; fi + git commit -m "chore(ledger): auto-update features progress" + git push diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index ddfb863d..d115d5a1 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -31,6 +31,11 @@ repos: entry: python3 tools/docs/check_frontmatter.py language: python files: ^docs/.*\.md$ + - id: curate-agents + name: curate AGENTS.md recent developments + entry: python3 tools/agents/curate_recent.py + language: python + files: ^AGENTS\.md$ - id: one-thing name: policy: one-thing (1 file = 1 thing) entry: python3 tools/quality/check_one_thing.py @@ -42,6 +47,11 @@ repos: entry: bash tools/enforce-public-includes.sh language: system pass_filenames: false + - id: features-update + name: features ledger update + entry: python3 scripts/update_progress.py + language: python + files: ^docs/features/Features_Ledger\.md$ - repo: https://github.com/Yelp/detect-secrets rev: v1.4.0 hooks: diff --git a/README.md b/README.md index 9429ce69..93a99113 100644 --- a/README.md +++ b/README.md @@ -199,24 +199,30 @@ Want to be featured? Open an issue and share your story. ```text -Feature progress to be updated via scripts/update_progress.py +███████████████████████████░░░░░░░░░░░░░ 66% ``` - -```text -To be updated by scripts/update_progress.py -``` - - -```text -To be updated by scripts/update_progress.py -``` - + + + + + + + + + + + + + + + + 🚀 Early release — Core features work today, API may evolve diff --git a/docs/features/Features_Ledger.md b/docs/features/Features_Ledger.md index c05c5318..a7132bc9 100644 --- a/docs/features/Features_Ledger.md +++ b/docs/features/Features_Ledger.md @@ -16,7 +16,7 @@ This is the canonical, grouped snapshot of features — shipped, in‑progress, ```text -░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 0% +███████████████████████████░░░░░░░░░░░░░ 66% ------------|-------------|------------| MVP Alpha v1.0.0 ``` @@ -34,59 +34,87 @@ Weighted by feature size (simple average for now). Updated by `python3 scripts/u ### Core & Platform ```text -░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 0% +███████████████████████████████▓░░░░░░░░ 78% ------------|-------------|------------| MVP Alpha v1.0.0 features=? ``` -| Emoji | Feature | Area | Spec | Code | Status | Progress % | Bar | Current State | Todo (Tasks) | Tests | Remarks | -| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | -| 🧱 | OID‑first Core | Core | — | core/include, core/src | Alpha | 85 | █████████░ | Equality OID‑first; OID fields in CBOR; cache/journal aligned. | Finalize strict equality; docs complete. | Unit passing | Good foundation. | -| 🗄️ | Journal (CBOR) | Core | docs/architecture | core/src/journal | Alpha | 80 | ████████░░ | Writer/reader with base64; debug flag; attributed edges. | Finalize ordering; more tests. | Unit passing | Backwards compat OK. | -| ⚡ | Cache (Bitmap) | Core | docs/architecture | core/src/cache | In Progress | 70 | ███████░░░ | Rebuild + query; shard; metadata. | Conformance tests; size calc. | Unit partial | Performance tuning next. | -| 🔒 | CLI Safety Guard | CLI | docs/operations | apps/cli | MVP | 70 | ███████░░░ | Official repo guard; env override. | E2E extension; docs polish. | Unit | Solid. | -| 🔗 | Ref Utilities | Core | docs/architecture | core/src/util | MVP | 75 | ███████░░░ | `gm_build_ref` with validation; tests. | More negative tests; docs link. | Unit | Good coverage. | -| 🧰 | Safe String/Memory | Core | — | core/include/gitmind/util | V1 | 90 | █████████░ | Safe wrappers adopted in hot paths. | Sweep stragglers; docs. | Unit | Security uplift. | +| Emoji | Feature | Area | Spec | Code | KLoC (approx) | Status | Progress % | Bar | Current State | Todo (Tasks) | Tests | Remarks | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 🧱 | OID‑first Core | Core | — | core/include, core/src | 5.0 | Alpha | 85% | █████████░ | Equality OID‑first; OID fields in CBOR; cache/journal aligned. | Finalize strict equality; docs complete. | Unit passing | Good foundation. | +| 🗄️ | Journal (CBOR) | Core | docs/architecture | core/src/journal | 3.0 | Alpha | 80% | ████████░░ | Writer/reader with base64; debug flag; attributed edges. | Finalize ordering; more tests. | Unit passing | Backwards compat OK. | +| ⚡ | Cache (Bitmap) | Core | docs/architecture | core/src/cache | 4.0 | In Progress | 70% | ███████░░░ | Rebuild + query; shard; metadata. | Conformance tests; size calc. | Unit partial | Performance tuning next. | +| 🔒 | CLI Safety Guard | CLI | docs/operations | apps/cli | 1.0 | MVP | 70% | ███████░░░ | Official repo guard; env override. | E2E extension; docs polish. | Unit | Solid. | +| 🔗 | Ref Utilities | Core | docs/architecture | core/src/util | 0.5 | MVP | 75% | ███████░░░ | `gm_build_ref` with validation; tests. | More negative tests; docs link. | Unit | Good coverage. | +| 🧰 | Safe String/Memory | Core | — | core/include/gitmind/util | 1.0 | V1 | 90% | █████████░ | Safe wrappers adopted in hot paths. | Sweep stragglers; docs. | Unit | Security uplift. | ### CLI, Hooks & UX ```text -░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 0% +██████████████████████████████░░░░░░░░░░ 74% ------------|-------------|------------| MVP Alpha v1.0.0 features=? ``` -| Emoji | Feature | Area | Spec | Code | Status | Progress % | Bar | Current State | Todo (Tasks) | Tests | Remarks | -| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | -| 🪝 | Post‑commit Hook (AUGMENTS) | Hooks | docs/hooks | core/src/hooks | In Progress | 50 | █████░░░░░ | Process changed files; AUGMENTS edge. | Path truncation handling (done); more cases. | Unit | Wire to journal read. | -| 🧰 | Review Seeding & Replies | DX | docs/tools | tools/review, workflows | MVP | 80 | ████████░░ | Seed + auto‑reply; artifact fallback. | GraphQL auto‑resolve; GH App. | CI + unit | High leverage. | -| 📜 | Docs Tooling | Docs | docs/tools | tools/docs | MVP | 70 | ███████░░░ | Frontmatter/TOC/title checks; labeler. | Extend templates; more guides. | Scripted | Good base. | -| 🧭 | Curated AGENTS.md | DX | docs | tools/agents | MVP | 80 | ████████░░ | TL;DR + YAML; curator; archives. | Tune summaries; monthly rollup. | Scripted | Fast onboarding. | -| 🧪 | Worksheet Gates | DX | docs/tools | tools/review | V1 | 90 | █████████░ | Pre‑push checks for placeholders + decisions. | Heuristics later (optional). | Scripted | Keeps quality high. | +| Emoji | Feature | Area | Spec | Code | KLoC (approx) | Status | Progress % | Bar | Current State | Todo (Tasks) | Tests | Remarks | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 🪝 | Post‑commit Hook (AUGMENTS) | Hooks | docs/hooks | core/src/hooks | 0.5 | In Progress | 50% | █████░░░░░ | Process changed files; AUGMENTS edge. | Path truncation handling (done); more cases. | Unit | Wire to journal read. | +| 🧰 | Review Seeding & Replies | DX | docs/tools | tools/review, workflows | 0.5 | MVP | 80% | ████████░░ | Seed + auto‑reply; artifact fallback. | GraphQL auto‑resolve; GH App. | CI + unit | High leverage. | +| 📜 | Docs Tooling | Docs | docs/tools | tools/docs | 0.4 | MVP | 70% | ███████░░░ | Frontmatter/TOC/title checks; labeler. | Extend templates; more guides. | Scripted | Good base. | +| 🧭 | Curated AGENTS.md | DX | docs | tools/agents | 0.2 | MVP | 80% | ████████░░ | TL;DR + YAML; curator; archives. | Tune summaries; monthly rollup. | Scripted | Fast onboarding. | +| 🧪 | Worksheet Gates | DX | docs/tools | tools/review | 0.3 | V1 | 90% | █████████░ | Pre‑push checks for placeholders + decisions. | Heuristics later (optional). | Scripted | Keeps quality high. | ### Observability & Analytics ```text -░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 0% +███████████████████░░░░░░░░░░░░░░░░░░░░░ 47% ------------|-------------|------------| MVP Alpha v1.0.0 features=? ``` -| Emoji | Feature | Area | Spec | Code | Status | Progress % | Bar | Current State | Todo (Tasks) | Tests | Remarks | -| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | -| 🔎 | CBOR Debug Tracing | Core/Obs | docs/operations | core/src/journal | MVP | 60 | ██████░░░░ | Env flag for verbose decode. | Structured logging; sampling. | Unit | Helpful during migration. | -| 📈 | Progress Ledgers | DX/Obs | docs/features | scripts | MVP | 60 | ██████░░░░ | Ledger + updater script. | Weighting; KLoC metrics. | Scripted | Improves planning. | -| 📊 | CI Trend Baselines | Obs | docs/ci | tools | Planned | 20 | ██░░░░░░░░ | Not started. | Collect tidy counts; failures. | — | Future. | +| Emoji | Feature | Area | Spec | Code | KLoC (approx) | Status | Progress % | Bar | Current State | Todo (Tasks) | Tests | Remarks | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 🔎 | CBOR Debug Tracing | Core/Obs | docs/operations | core/src/journal | 0.2 | MVP | 60% | ██████░░░░ | Env flag for verbose decode. | Structured logging; sampling. | Unit | Helpful during migration. | +| 📈 | Progress Ledgers | DX/Obs | docs/features | scripts | 0.3 | MVP | 60% | ██████░░░░ | Ledger + updater script. | Weighting; KLoC metrics. | Scripted | Improves planning. | +| 📊 | CI Trend Baselines | Obs | docs/ci | tools | 0.2 | Planned | 20% | ██░░░░░░░░ | Not started. | Collect tidy counts; failures. | — | Future. | + +## Tasks + +### Core & Platform + +- [ ] Adopt OID‑first equality everywhere (strict, no SHA fallback when OIDs present) +> [!INFO]- +> Update comparisons and tests; align cache/journal; document in TECHNICAL.md. + +- [ ] Finalize bitmap cache conformance tests +> [!INFO]- +> Build synthetic repos; verify shard distribution and size calculations; add docs. + +### CLI, Hooks & UX + +- [ ] Post‑commit AUGMENTS wiring +> [!INFO]- +> Finish journal read integration; handle path truncation errors; add E2E. + +- [ ] GraphQL auto‑resolve for accepted PR feedback +> [!INFO]- +> Extend apply-feedback workflow with GraphQL to resolve threads after replies. + +### Observability & Analytics + +- [ ] CI trend baselines collection +> [!INFO]- +> Record tidy counts and unit results; render sparklines; add dashboards. + --- Notes - Update via `python3 scripts/update_progress.py` (or `make features-update`). - Progress bars are averaged for now; weighting and KLoC are future work. - diff --git a/docs/tools/PR_Workflow_Factoring.md b/docs/tools/PR_Workflow_Factoring.md new file mode 100644 index 00000000..25f0ef3b --- /dev/null +++ b/docs/tools/PR_Workflow_Factoring.md @@ -0,0 +1,220 @@ +--- +title: Factoring PR Workflow to a Standalone Repo +description: Step‑by‑step guide to extract our PR seeding + worksheet + auto‑reply workflow into its own reusable repository. +audience: [maintainers, contributors] +domain: [tooling] +tags: [review, github-actions, automation] +status: draft +last_updated: 2025-09-16 +--- + +# Overview + +This guide captures how to factor our “PR feedback → worksheet → auto‑reply” workflow into a separate, reusable repository that any project can consume with minimal setup. + +The goal is a portable, easy‑install review pipeline that works great for both AI agents and humans: seed a worksheet from PR comments, fill in Accepted/Rejected with rationale, and let the bot reply and (optionally) resolve threads. + +## Components to Extract + +Core (to externalize): +- Scripts + - `tools/review/seed_feedback_from_github.py` + - `tools/review/check_worksheets.py` + - `tools/review/apply_feedback_to_github.py` +- Workflows + - `.github/workflows/auto-seed-review.yml` — seed worksheet on PR events + - `.github/workflows/apply-feedback.yml` — reply on push of updated worksheets +- Hooks & config (optional but helpful) + - Pre‑push gate: `.githooks/pre-push` changes (template) + - Pre‑commit hook: worksheet checker and curation (templates) + - Review config: `.coderabbit.yml` suggestions + - PR template: `.github/pull_request_template.md` guidance + - Docs: `docs/tools/Review_Seeding.md` user guide + +Nice‑to‑have extras: +- GH Labeler: `.github/labeler.yml` + docs‑only workflow +- Curator (AGENTS‑style): `tools/agents/curate_recent.py` (not required for the PR flow) + +## Target Repo Layout (Example) + +``` +review-buddy/ + README.md + LICENSE + scripts/ + seed_feedback.py + apply_feedback.py + check_worksheets.py + .github/ + workflows/ + seed-review.yml # reusable workflow + apply-feedback.yml # reusable workflow + action/ + apply-feedback/action.yml # composite Action for replies + seed-review/action.yml # composite Action for seeding + templates/ + pre-push # sample pre-push gate + pre-commit-config.yaml # sample pre-commit additions + pull_request_template.md + coderabbit.yml + docs/ + GETTING_STARTED.md + ADVANCED.md +``` + +Notes: +- Prefer both “reusable workflows” (callable with `workflow_call`) and “composite actions” for flexibility. +- Scripts live in `scripts/` and are referenced by the composite actions. + +## Extraction Steps (from this repo) + +1) Create the new repo, e.g., `neuroglyph/review-buddy` (MIT/Apache‑2.0 preferred). +2) Copy scripts into `scripts/` and update imports and paths to be repo‑relative. +3) Convert current workflows to reusable workflows: + - `on: workflow_call` + - Inputs: `pr_number`, `seed_to_branch`, toggles +4) Create composite actions (`action/*/action.yml`) that shell out to the Python scripts for easy inclusion in non‑reusable workflows. +5) Add docs (`GETTING_STARTED.md`, `ADVANCED.md`) with install steps. +6) Add an example consuming project in `examples/` (optional). + +## Consuming Repo Setup + +Option A — Reusable workflows: +``` +# .github/workflows/seed-review.yml +name: Seed Review Doc +on: + pull_request_target: + types: [opened, reopened, synchronize] + +jobs: + seed: + uses: neuroglyph/review-buddy/.github/workflows/seed-review.yml@vX.Y.Z + secrets: inherit +``` + +``` +# .github/workflows/apply-feedback.yml +name: Apply Feedback Replies +on: + push: + branches-ignore: [ main ] + paths: [ 'docs/code-reviews/**.md' ] + +jobs: + apply: + uses: neuroglyph/review-buddy/.github/workflows/apply-feedback.yml@vX.Y.Z + secrets: inherit +``` + +Option B — Composite actions (per‑job): +``` +jobs: + seed: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: neuroglyph/review-buddy/action/seed-review@vX.Y.Z + with: + pr: ${{ github.event.number }} +``` + +Secrets required (at minimum): +- `GITHUB_TOKEN` (provided by Actions) +- Optional fork push PAT: `GITMIND_PR_WORKSHEET_BOT` (or rename for the external repo) + +## Pre‑push / Pre‑commit Templates + +Pre‑push gate (blocks if worksheets contain `{response}` or undecided sections): +- Provide a `templates/pre-push` script and document symlink/install. + +Pre‑commit templates: +- Provide a stanza to insert into `.pre-commit-config.yaml` to run the worksheet checker on docs changes. + +## Configuration Surface + +Top‑level `review-buddy.yml` (in consuming repo): +``` +worksheet: + dir: docs/code-reviews + accepted_marker: "[!note]- **Accepted**" + rejected_marker: "[!CAUTION]- **Rejected**" + require_decision_for_all: true + +seeding: + seed_to_branch: auto # auto | artifact_only + bot_secret: REVIEW_BOT_PAT + maintainers_edit_required: true + +apply: + reply_accepted: true + reply_rejected: true + resolve_accepted: false # GraphQL; can be enabled later +``` + +The composite actions / reusable workflows should respect these conventions via environment variables and default values. + +## Versioning + Release + +- Tag releases `vX.Y.Z`. +- Changelog: list breaking changes for inputs/outputs. +- Provide a matrix of supported GitHub Runners and Python versions. + +## “HOLY SHIT THIS IS AMAZING” Upgrades + +Make it delightful for agents and humans: + +1) GraphQL Auto‑Resolve + - After replying on accepted items, resolve review threads via GraphQL mutation. + - Map worksheet sections to original thread IDs; dry‑run mode for safety. + +2) PR Dashboard Comment + - Post a summary comment on PR with counts: total, accepted, rejected, undecided; link to worksheet. + - Update the comment on each push or worksheet change. + +3) ChatOps Commands + - `/seed` to regenerate worksheet; `/apply` to apply replies; `/resolve-accepted` to resolve threads. + - Gate commands by role (maintainer only) and label. + +4) Web‑Preview of Worksheet + - Serve a GitHub Pages or Action artifact as a styled HTML view of the worksheet (TOC, filters, search). + - Provide a “focus mode” for reviewers to skim Accepted/Rejected quickly. + +5) Multi‑Repo Templates + - A single “org” repo stores default templates (.coderabbit.yml, PR template, hooks). Repos opt‑in or override. + +6) Deep CodeRabbit Integration + - Parse CR’s review metadata (if accessible) to group comments by rule/pattern. + - Suggest fix‑it snippets and patch stacks; apply suggestions in a fresh branch via a bot. + +7) Quality Signals + Badges + - Expose a JSON “review‑health” summary: % accepted, time‑to‑address, undecided count. + - CI gate: fail if undecided > threshold on “ready to merge” label. + +8) Agent‑First Ergonomics + - Provide a tiny API: `seed(pr)`, `apply(pr)`, `resolve(pr)` that agents can call with one line. + - Emit machine‑readable logs with stable keys (decision=accepted/rejected, url, title, section). + +9) Installer Script + - `npx review-buddy init` to add workflows, templates, and secrets scaffolding to a repo with prompts. + +10) Secure Bot Options + - Ship a GitHub App (least privilege) as an alternative to PAT. + - Document org‑wide vs repo‑specific secret strategies. + +## Migration Checklist (from this repo) + +- [ ] Create `neuroglyph/review-buddy` with scripts, workflows, actions, and docs. +- [ ] Replace in‑repo scripts with references to the external Action/workflows. +- [ ] Update docs: point to `GETTING_STARTED.md` in the new repo. +- [ ] Keep a compatibility shim for a few releases (graceful deprecation). + +## Getting to “Meh → Amazing” + +Deliver smooth on‑ramp + high trust: +- One‑command install; sensible defaults; crisp errors. +- Great docs with copy‑paste snippets and screenshots. +- Safety: dry‑run modes, explicit labels to enable writing. +- Telemetry: text summaries + JSON for automation. +- Extensibility: template markers for block parsing, configurable decision markers, pluggable resolvers. + diff --git a/scripts/update_progress.py b/scripts/update_progress.py index cb4642bf..c9b2b4f8 100644 --- a/scripts/update_progress.py +++ b/scripts/update_progress.py @@ -7,17 +7,15 @@ from __future__ import annotations import re from pathlib import Path +import math ROOT = Path(__file__).resolve().parents[1] LEDGER = ROOT / "docs" / "features" / "Features_Ledger.md" README = ROOT / "README.md" GROUP_RE = re.compile(r"\n```text\n(.*?)\n```\n", re.S | re.I) - -TABLE_RE = re.compile(r"^\|.*\n(?:\|[\-\s\|]+\|\n)(?P(?:\|.*\n)+)", re.M) -ROW_RE = re.compile(r"\|.*?\|.*?\|.*?\|.*?\|.*?\|.*?\|.*?\|\s*(\d+)\s*(?:\%|\(|$)") - OVERALL_RE = re.compile(r"\n```text\n(.*?)\n```\n", re.S) +READ_ME_BLOCK_RE = re.compile(r"\n```text\n(.*?)\n```\n", re.S) def progress_bar(pct: float, width: int = 40) -> str: filled = int(round(pct * width)) @@ -25,17 +23,66 @@ def progress_bar(pct: float, width: int = 40) -> str: return "█" * filled + ("▓" if filled < width and (pct*width - filled) > 0 else "") + "░" * (width - filled - (1 if filled < width and (pct*width - filled) > 0 else 0)) + f" {int(round(pct*100))}%" def compute_group_percent(md: str, anchor: int) -> float: - # Find next table after anchor - m = TABLE_RE.search(md, anchor) + tail = md[anchor:] + # find the feature table header + m = re.search(r"^\|\s*Emoji\s*\|", tail, re.M) if not m: return 0.0 - body = m.group('body') + i = m.start() + table = tail[i:].splitlines() + if len(table) < 3: + return 0.0 + header = table[0] + sep = table[1] if len(table) > 1 else '' + rows = table[2:] + header_cells = [c.strip() for c in header.strip().split('|')] + # locate column indices + def find_idx(name_sub: str) -> int: + for idx, c in enumerate(header_cells): + if name_sub.lower() in c.lower(): + return idx + return -1 + progress_idx = find_idx('Progress') + kloc_idx = find_idx('KLoC') vals = [] - for line in body.splitlines(): - rm = ROW_RE.search(line) - if rm: - vals.append(int(rm.group(1))) - return (sum(vals) / len(vals) / 100.0) if vals else 0.0 + weights = [] + for line in rows: + if not line.startswith('|'): + break + cells = [c.strip() for c in line.strip().split('|')] + prog = None + # prefer indexed cell + if 0 <= progress_idx < len(cells): + c = cells[progress_idx] + if c.endswith('%') and c[:-1].strip().isdigit(): + prog = int(c[:-1].strip()) + else: + s2 = ''.join(ch for ch in c if ch.isdigit()) + if s2: + prog = int(s2) + # fallback scan + if prog is None: + for c in cells: + if c.endswith('%') and c[:-1].strip().isdigit(): + prog = int(c[:-1].strip()) + break + if prog is None: + continue + # weight from KLoC + w = 1.0 + if 0 <= kloc_idx < len(cells): + try: + kloc = float(cells[kloc_idx]) + w = max(0.5, 1.0 + math.log10(kloc * 1000 + 10.0) / 3.0) + except Exception: + w = 1.0 + vals.append(prog) + weights.append(w) + if not vals: + return 0.0 + # weighted average + wsum = sum(weights) if weights else float(len(vals)) + return (sum(p * w for p, w in zip(vals, weights)) / wsum) / 100.0 def update_ledger(): text = LEDGER.read_text(encoding='utf-8') @@ -58,21 +105,38 @@ def update_ledger(): if new != text: LEDGER.write_text(new, encoding='utf-8') -def update_readme(): +def update_readme(overall: float | None = None): if not README.exists(): return text = README.read_text(encoding='utf-8') - if not OVERALL_RE.search(text): - # insert under Status section if present - if "## 📊 Status" in text: - parts = text.split("## 📊 Status", 1) - progress = "\n\n```text\nTo be updated by scripts/update_progress.py\n```\n\n" - text = parts[0] + "## 📊 Status\n\n" + progress + parts[1] - README.write_text(text, encoding='utf-8') + if "## 📊 Status" not in text: + return + if not READ_ME_BLOCK_RE.search(text): + parts = text.split("## 📊 Status", 1) + progress = "\n\n```text\nFeature progress to be updated via scripts/update_progress.py\n```\n\n\n" + text = parts[0] + "## 📊 Status\n\n" + progress + parts[1] + if overall is not None: + block = f"\n```text\n{progress_bar(overall)}\n```\n\n" + # Remove all existing blocks, then insert one + text = READ_ME_BLOCK_RE.sub("", text) + # Insert just after the Status header + parts = text.split("## 📊 Status", 1) + if len(parts) == 2: + text = parts[0] + "## 📊 Status\n\n" + block + "\n" + parts[1] + README.write_text(text, encoding='utf-8') def main(): + # Compute overall from ledger + text = LEDGER.read_text(encoding='utf-8') + groups = [] + weights = [] + for m in GROUP_RE.finditer(text): + pct = compute_group_percent(text, m.end()) + groups.append(pct) + weights.append(1.0) # equal group weights for now; could sum KLoC per group + overall = (sum(g * w for g, w in zip(groups, weights)) / sum(weights)) if groups else None update_ledger() - update_readme() + update_readme(overall) if __name__ == '__main__': main() From 02c818b9481b422dcaf7f5c7b101bce113e4bd0f Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Wed, 17 Sep 2025 00:54:42 -0700 Subject: [PATCH 28/42] chore: checkpoint planning docs and animated dag --- AGENTS.md | 1 + CONTRIBUTING.md | 9 +- README.md | 24 +- assets/images/git-mind-dag.svg | 3 + docs/PRDs/PRD-co-thought-mcp-service.md | 2 +- ...it-mind-semantics-time-travel-prototype.md | 2 +- docs/README.md | 2 +- docs/adr/0002-docs-reorganization.md | 2 +- docs/architecture/bitmap-cache-design.md | 2 +- docs/architecture/cache-migration-oid-only.md | 2 +- .../deprecations/legacy-sha-fields.md | 2 +- .../journal-architecture-pivot.md | 2 +- docs/architecture/tombstone-visual.md | 2 +- docs/audits/vision-drift.md | 2 +- docs/cli/combined_markdown.md | 2 +- docs/code-reviews/CLAUDE.md | 2 +- ...4f3f906eb454cb103eb8cc6899df8dfbf6e2349.md | 4 +- docs/enforcer/BEFORE_WE_BEGIN.md | 2 +- .../dev-journals/2025-06-22-foundations.md | 2 +- .../2025-06-23-foundations-and-shame.md | 2 +- .../gameplans/01-error-handling-revolution.md | 2 +- .../02-memory-architecture-revolution.md | 2 +- .../gameplans/03-observability-built-in.md | 2 +- .../04-testing-infrastructure-uplift.md | 2 +- .../05-config-convention-overhaul.md | 2 +- .../06-plugin-extensibility-hooks.md | 2 +- .../gameplans/07-security-hygiene-as-code.md | 2 +- .../gameplans/08-devex-internal-cli.md | 2 +- .../gameplans/09-domain-language-purity.md | 2 +- .../10-future-proofing-without-yagni.md | 2 +- .../gameplans/11-gitmind-metadata-layer.md | 2 +- docs/enforcer/reviews/2025-06-22-review.md | 2 +- docs/enforcer/specs/01-error-types-spec.md | 2 +- docs/enforcer/specs/02-domain-types-spec.md | 2 +- .../specs/03-security-primitives-spec.md | 2 +- docs/features/Features_Ledger.md | 210 ++++++++++++++---- docs/planning/Milestone_Synthesis.md | 83 +++++++ docs/planning/Milestones.md | 2 +- docs/planning/Product_Roadmap.md | 2 +- docs/planning/Release_Plans.md | 2 +- docs/planning/Sprint_Plans.md | 2 +- docs/quality/SOLID_DRY_REPORT.md | 2 +- docs/quality/TIDY_CLANG_CRUSADE.md | 2 +- docs/quality/static-analysis-guide.md | 2 +- docs/sitrep/2025-06-24/ci-sitrep.md | 2 +- .../centralized-cbor-keys-and-public-apis.md | 2 +- .../deterministic-merges-crdt-advice.md | 2 +- docs/talk-shop/hardening-mindset.md | 2 +- docs/talk-shop/journal-first-cbor-commits.md | 2 +- docs/talk-shop/oid-first-migration.md | 2 +- docs/templates/code-review-feedback.md | 22 +- docs/tools/PR_Workflow_Factoring.md | 7 +- docs/tools/Review_Seeding.md | 10 +- .../CLAUDE_DEEP_THOUGHTS_FINAL.md | 2 +- .../brain-storms/plugins.md | 2 +- .../plugins2.0/00-summary.md | 2 +- .../plugins2.0/01-requirements.md | 2 +- .../plugins2.0/02-tech-design.md | 2 +- docs/wish-list-features/plugins2.0/03-api.md | 2 +- .../plugins2.0/05-security.md | 2 +- scripts/update_progress.py | 205 +++++++++++++---- 61 files changed, 504 insertions(+), 174 deletions(-) create mode 100644 assets/images/git-mind-dag.svg create mode 100644 docs/planning/Milestone_Synthesis.md diff --git a/AGENTS.md b/AGENTS.md index 5941cb8c..1f6585b6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,6 +30,7 @@ agent: - Run `make docs-verify` for doc changes; `make header-compile` for new public headers - Respect One‑Thing rule for touched files - For fork PRs, seeded worksheet may be artifact+comment (see Review_Seeding) +- Sync feature/milestone updates in `docs/features/Features_Ledger.md`; follow the Capture→GA lifecycle and rerun `make features-update`. ## Recent Developments diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5e2768fe..22da444f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,6 +25,13 @@ Thanks for your interest in improving git‑mind! This guide summarizes expectat - Public headers compile: `ninja -C build header-compile` 3. Keep diffs focused; match existing patterns in `core/` and `include/`. +## Planning & Feature Tracking + +- `docs/features/Features_Ledger.md` is the single source of truth for roadmap, milestones, and tasks. +- Add new ideas under the appropriate feature group during **Capture**, tag them with a milestone, and log supporting tasks in the `## Tasklist` section. +- Progress bars are generated automatically—run `make features-update` after updating progress %, KLoC estimates, or tasks. +- Milestone callouts (`MVP`, `Alpha`, `Beta`, `v1.0.0`) auto-pull outstanding tasks based on `[Milestone]` tags; keep those tags in sync as work moves stages. + ## Code Style - Language: C23; warnings‑as‑errors; no VLAs or shadowing; explicit prototypes. @@ -54,7 +61,7 @@ Thanks for your interest in improving git‑mind! This guide summarizes expectat - Keep `.coderabbit.yml` updated. - Prefer summary reviews; limit per‑line comments on docs. - If rejecting a suggestion, document rationale under `docs/code-reviews/rejected-suggestions/` with links. - - See `docs/tools/Review_Seeding.md` for the auto‑worksheet flow and how to seed PR feedback locally or via CI. Seeded files live under `docs/code-reviews/PR/.md`. +- See `docs/tools/Review_Seeding.md` for the auto‑worksheet flow and how to seed PR feedback locally or via CI. Seeded files live under `docs/code-reviews/PR/.md`. ## Getting Help diff --git a/README.md b/README.md index 93a99113..87f17b09 100644 --- a/README.md +++ b/README.md @@ -199,32 +199,10 @@ Want to be featured? Open an issue and share your story. ```text -███████████████████████████░░░░░░░░░░░░░ 66% +█████████████████████████████░░░░░░░░░░░ 72% ``` - - - - - - - - - - - - - - - - - - - - - - 🚀 Early release — Core features work today, API may evolve 📅 Roadmap: `docs/roadmap.md` 🤝 Contributing: `CONTRIBUTING.md` diff --git a/assets/images/git-mind-dag.svg b/assets/images/git-mind-dag.svg new file mode 100644 index 00000000..2bf220c2 --- /dev/null +++ b/assets/images/git-mind-dag.svg @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e96a8e9e489d020747d9e1dc60f382b450d6825f267bdce036f91f94b2d5035e +size 9318 diff --git a/docs/PRDs/PRD-co-thought-mcp-service.md b/docs/PRDs/PRD-co-thought-mcp-service.md index 9e5a5357..1854c061 100644 --- a/docs/PRDs/PRD-co-thought-mcp-service.md +++ b/docs/PRDs/PRD-co-thought-mcp-service.md @@ -1,5 +1,5 @@ --- -title: PRD — Co‑Thought MCP Service (Local Tools Integration) +title: PRD: Co‑Thought MCP Service (Local Tools Integration) description: Local-only service for tools/agents to read/write edges and query journal/cache. audience: [contributors, developers] domain: [project] diff --git a/docs/PRDs/PRD-git-mind-semantics-time-travel-prototype.md b/docs/PRDs/PRD-git-mind-semantics-time-travel-prototype.md index 70321393..efc54199 100644 --- a/docs/PRDs/PRD-git-mind-semantics-time-travel-prototype.md +++ b/docs/PRDs/PRD-git-mind-semantics-time-travel-prototype.md @@ -1,5 +1,5 @@ --- -title: PRD — First‑Class, Time‑Travel‑Safe Semantics +title: PRD: First‑Class, Time‑Travel‑Safe Semantics for git‑mind description: Requirements for semantics stored in Git with branch and time-travel correctness. audience: [contributors, developers] domain: [project, architecture] diff --git a/docs/README.md b/docs/README.md index da7308fc..3643e1d3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,5 +1,5 @@ --- -title: Docs Index +title: docs/ (Index and Structure) description: Index of documentation with stable links and key entry points. audience: [all] domain: [project] diff --git a/docs/adr/0002-docs-reorganization.md b/docs/adr/0002-docs-reorganization.md index 196caf2f..a67f18de 100644 --- a/docs/adr/0002-docs-reorganization.md +++ b/docs/adr/0002-docs-reorganization.md @@ -1,5 +1,5 @@ --- -title: ADR 0002 — Documentation Reorganization and Planning Structure +title: ADR 0002: Documentation Reorganization and Planning Structure description: Establish stable docs hubs, add indexes, and improve cross-linking. audience: [contributors] domain: [project] diff --git a/docs/architecture/bitmap-cache-design.md b/docs/architecture/bitmap-cache-design.md index 227a354a..d5974e0c 100644 --- a/docs/architecture/bitmap-cache-design.md +++ b/docs/architecture/bitmap-cache-design.md @@ -1,5 +1,5 @@ --- -title: Bitmap Cache Design +title: Bitmap Cache Design 🦁⚡ description: High-performance query layer using Roaring Bitmaps for compressed sets and fast operations. audience: [developers] domain: [architecture] diff --git a/docs/architecture/cache-migration-oid-only.md b/docs/architecture/cache-migration-oid-only.md index 219caf87..5163ebe3 100644 --- a/docs/architecture/cache-migration-oid-only.md +++ b/docs/architecture/cache-migration-oid-only.md @@ -1,5 +1,5 @@ --- -title: Cache Migration — OID-Only +title: Cache Migration: OID-Only Format and Stable Refs description: Migration to OID-only cache format with stable ref naming and legacy fallback. audience: [developers] domain: [architecture] diff --git a/docs/architecture/deprecations/legacy-sha-fields.md b/docs/architecture/deprecations/legacy-sha-fields.md index 4f2963ec..015d1719 100644 --- a/docs/architecture/deprecations/legacy-sha-fields.md +++ b/docs/architecture/deprecations/legacy-sha-fields.md @@ -1,5 +1,5 @@ --- -title: Deprecation — Legacy SHA-1 Byte Arrays in Edges +title: Deprecation Notice: Legacy SHA-1 Byte Arrays in Edges description: Plan to remove SHA-1 specific arrays in favor of OID-only APIs and storage. audience: [developers] domain: [architecture] diff --git a/docs/architecture/journal-architecture-pivot.md b/docs/architecture/journal-architecture-pivot.md index 61f315c9..10edf88b 100644 --- a/docs/architecture/journal-architecture-pivot.md +++ b/docs/architecture/journal-architecture-pivot.md @@ -1,5 +1,5 @@ --- -title: Journal Architecture Pivot +title: Project: No Tux Given 🐧⚡ description: Edge-journal commits with branch-aware graphs; the final architecture for storing semantics in Git. audience: [developers] domain: [architecture] diff --git a/docs/architecture/tombstone-visual.md b/docs/architecture/tombstone-visual.md index 780df210..4c929d2e 100644 --- a/docs/architecture/tombstone-visual.md +++ b/docs/architecture/tombstone-visual.md @@ -1,5 +1,5 @@ --- -title: Visual Guide — Tombstones +title: Visual Guide: How Tombstones Work description: Visual explanation for tombstoned edges and why deletions preserve history. audience: [developers] domain: [architecture] diff --git a/docs/audits/vision-drift.md b/docs/audits/vision-drift.md index eaf4d08c..f794c285 100644 --- a/docs/audits/vision-drift.md +++ b/docs/audits/vision-drift.md @@ -1,5 +1,5 @@ --- -title: Audit Notes +title: Vision Alignment / Drift Audit description: Audits and drift analyses. audience: [contributors] domain: [quality] diff --git a/docs/cli/combined_markdown.md b/docs/cli/combined_markdown.md index 8e9bb3ad..f2872632 100644 --- a/docs/cli/combined_markdown.md +++ b/docs/cli/combined_markdown.md @@ -1,5 +1,5 @@ --- -title: CLI Combined Reference +title: README.md description: Combined CLI reference content for convenience and offline browsing. audience: [users, developers] domain: [cli] diff --git a/docs/code-reviews/CLAUDE.md b/docs/code-reviews/CLAUDE.md index d5cdee57..a6ad6c1e 100644 --- a/docs/code-reviews/CLAUDE.md +++ b/docs/code-reviews/CLAUDE.md @@ -1,5 +1,5 @@ --- -title: Code Review Notes +title: Code Review: migration/finish-core-cleanup Branch description: Code review guidelines and context. audience: [contributors] domain: [quality] diff --git a/docs/code-reviews/PR169/e4f3f906eb454cb103eb8cc6899df8dfbf6e2349.md b/docs/code-reviews/PR169/e4f3f906eb454cb103eb8cc6899df8dfbf6e2349.md index 69e19362..c0f06f84 100644 --- a/docs/code-reviews/PR169/e4f3f906eb454cb103eb8cc6899df8dfbf6e2349.md +++ b/docs/code-reviews/PR169/e4f3f906eb454cb103eb8cc6899df8dfbf6e2349.md @@ -1,5 +1,5 @@ --- -title: {filename} +title: Code Review Feedback description: Preserved review artifacts and rationale. audience: [contributors] domain: [quality] @@ -11,7 +11,7 @@ status: archive | Date | Agent | SHA | Branch | PR | |------|-------|-----|--------|----| -| {date} | {agent} | `e4f3f906eb454cb103eb8cc6899df8dfbf6e2349` | [feat/changelog-and-sweep-4](https://github.com/neuroglyph/git-mind/tree/feat/changelog-and-sweep-4 "neuroglyph/git-mind:feat/changelog-and-sweep-4") | [PR#169](https://github.com/neuroglyph/git-mind/pull/169) | +| 2025-09-16 | Codex | `e4f3f906eb454cb103eb8cc6899df8dfbf6e2349` | [feat/changelog-and-sweep-4](https://github.com/neuroglyph/git-mind/tree/feat/changelog-and-sweep-4 "neuroglyph/git-mind:feat/changelog-and-sweep-4") | [PR#169](https://github.com/neuroglyph/git-mind/pull/169) | ## Instructions diff --git a/docs/enforcer/BEFORE_WE_BEGIN.md b/docs/enforcer/BEFORE_WE_BEGIN.md index 17c9cc1c..5f21d118 100644 --- a/docs/enforcer/BEFORE_WE_BEGIN.md +++ b/docs/enforcer/BEFORE_WE_BEGIN.md @@ -1,5 +1,5 @@ --- -title: BEFORE WE BEGIN: Clean Slate Strategy +title: 🚧 BEFORE WE BEGIN: Clean Slate Strategy description: Historical notes and enforcement-era artifacts. audience: [contributors] domain: [quality] diff --git a/docs/enforcer/dev-journals/2025-06-22-foundations.md b/docs/enforcer/dev-journals/2025-06-22-foundations.md index e98cb95c..5933347b 100644 --- a/docs/enforcer/dev-journals/2025-06-22-foundations.md +++ b/docs/enforcer/dev-journals/2025-06-22-foundations.md @@ -1,5 +1,5 @@ --- -title: Enforcer Notes +title: Dev Journal: 2025-06-22 - Laying the Foundations description: Historical notes and enforcement-era artifacts. audience: [contributors] domain: [quality] diff --git a/docs/enforcer/dev-journals/2025-06-23-foundations-and-shame.md b/docs/enforcer/dev-journals/2025-06-23-foundations-and-shame.md index f4161945..c38400e0 100644 --- a/docs/enforcer/dev-journals/2025-06-23-foundations-and-shame.md +++ b/docs/enforcer/dev-journals/2025-06-23-foundations-and-shame.md @@ -1,5 +1,5 @@ --- -title: Enforcer Notes +title: Dev Journal: 2025-06-23 - Foundations and Shame description: Historical notes and enforcement-era artifacts. audience: [contributors] domain: [quality] diff --git a/docs/enforcer/gameplans/01-error-handling-revolution.md b/docs/enforcer/gameplans/01-error-handling-revolution.md index 76bda4ba..a5865fd4 100644 --- a/docs/enforcer/gameplans/01-error-handling-revolution.md +++ b/docs/enforcer/gameplans/01-error-handling-revolution.md @@ -1,5 +1,5 @@ --- -title: Enforcer Notes +title: 🚨 Error Handling Revolution: Gameplan description: Historical notes and enforcement-era artifacts. audience: [contributors] domain: [quality] diff --git a/docs/enforcer/gameplans/02-memory-architecture-revolution.md b/docs/enforcer/gameplans/02-memory-architecture-revolution.md index 047fa5de..b2227bef 100644 --- a/docs/enforcer/gameplans/02-memory-architecture-revolution.md +++ b/docs/enforcer/gameplans/02-memory-architecture-revolution.md @@ -1,5 +1,5 @@ --- -title: Enforcer Notes +title: 🧠 Memory Architecture Revolution: Gameplan description: Historical notes and enforcement-era artifacts. audience: [contributors] domain: [quality] diff --git a/docs/enforcer/gameplans/03-observability-built-in.md b/docs/enforcer/gameplans/03-observability-built-in.md index 375bed76..bdb72287 100644 --- a/docs/enforcer/gameplans/03-observability-built-in.md +++ b/docs/enforcer/gameplans/03-observability-built-in.md @@ -1,5 +1,5 @@ --- -title: Observability Built-In: Gameplan +title: 🔍 Observability Built-In: Gameplan description: Historical notes and enforcement-era artifacts. audience: [contributors] domain: [quality] diff --git a/docs/enforcer/gameplans/04-testing-infrastructure-uplift.md b/docs/enforcer/gameplans/04-testing-infrastructure-uplift.md index ef477203..41bb1aec 100644 --- a/docs/enforcer/gameplans/04-testing-infrastructure-uplift.md +++ b/docs/enforcer/gameplans/04-testing-infrastructure-uplift.md @@ -1,5 +1,5 @@ --- -title: Testing Infrastructure Uplift: Gameplan +title: 🧪 Testing Infrastructure Uplift: Gameplan description: Historical notes and enforcement-era artifacts. audience: [contributors] domain: [quality] diff --git a/docs/enforcer/gameplans/05-config-convention-overhaul.md b/docs/enforcer/gameplans/05-config-convention-overhaul.md index 3c295fe1..21f8a46a 100644 --- a/docs/enforcer/gameplans/05-config-convention-overhaul.md +++ b/docs/enforcer/gameplans/05-config-convention-overhaul.md @@ -1,5 +1,5 @@ --- -title: Enforcer Notes +title: ⚙️ Config & Convention Overhaul: Gameplan description: Historical notes and enforcement-era artifacts. audience: [contributors] domain: [quality] diff --git a/docs/enforcer/gameplans/06-plugin-extensibility-hooks.md b/docs/enforcer/gameplans/06-plugin-extensibility-hooks.md index 8cd2f0d4..c409ac73 100644 --- a/docs/enforcer/gameplans/06-plugin-extensibility-hooks.md +++ b/docs/enforcer/gameplans/06-plugin-extensibility-hooks.md @@ -1,5 +1,5 @@ --- -title: Enforcer Notes +title: 🔌 Plugin + Extensibility Hooks: Gameplan description: Historical notes and enforcement-era artifacts. audience: [contributors] domain: [quality] diff --git a/docs/enforcer/gameplans/07-security-hygiene-as-code.md b/docs/enforcer/gameplans/07-security-hygiene-as-code.md index 672eb644..b4c7c82d 100644 --- a/docs/enforcer/gameplans/07-security-hygiene-as-code.md +++ b/docs/enforcer/gameplans/07-security-hygiene-as-code.md @@ -1,5 +1,5 @@ --- -title: Enforcer Notes +title: 🔒 Security Hygiene as Code: Gameplan description: Historical notes and enforcement-era artifacts. audience: [contributors] domain: [quality] diff --git a/docs/enforcer/gameplans/08-devex-internal-cli.md b/docs/enforcer/gameplans/08-devex-internal-cli.md index e8448704..bc8e9d43 100644 --- a/docs/enforcer/gameplans/08-devex-internal-cli.md +++ b/docs/enforcer/gameplans/08-devex-internal-cli.md @@ -1,5 +1,5 @@ --- -title: DevEx Internal CLI — Enforcer Notes +title: 🛠️ DevEx: Internal CLI for Developer Tools - Gameplan description: Historical notes and enforcement-era artifacts. audience: [contributors] domain: [quality] diff --git a/docs/enforcer/gameplans/09-domain-language-purity.md b/docs/enforcer/gameplans/09-domain-language-purity.md index 28efefaa..d904bdd5 100644 --- a/docs/enforcer/gameplans/09-domain-language-purity.md +++ b/docs/enforcer/gameplans/09-domain-language-purity.md @@ -1,5 +1,5 @@ --- -title: Domain Language Purity — Enforcer Notes +title: 📖 Domain Language Purity: Gameplan description: Historical notes and enforcement-era artifacts. audience: [contributors] domain: [quality] diff --git a/docs/enforcer/gameplans/10-future-proofing-without-yagni.md b/docs/enforcer/gameplans/10-future-proofing-without-yagni.md index 492d38c5..25525aee 100644 --- a/docs/enforcer/gameplans/10-future-proofing-without-yagni.md +++ b/docs/enforcer/gameplans/10-future-proofing-without-yagni.md @@ -1,5 +1,5 @@ --- -title: Enforcer Notes +title: 🔮 Future Proofing Without YAGNI Sin: Gameplan description: Historical notes and enforcement-era artifacts. audience: [contributors] domain: [quality] diff --git a/docs/enforcer/gameplans/11-gitmind-metadata-layer.md b/docs/enforcer/gameplans/11-gitmind-metadata-layer.md index 5fd3a01a..02135514 100644 --- a/docs/enforcer/gameplans/11-gitmind-metadata-layer.md +++ b/docs/enforcer/gameplans/11-gitmind-metadata-layer.md @@ -1,5 +1,5 @@ --- -title: Enforcer Notes +title: 🎁 GitMind-Native Metadata Layer: Gameplan description: Historical notes and enforcement-era artifacts. audience: [contributors] domain: [quality] diff --git a/docs/enforcer/reviews/2025-06-22-review.md b/docs/enforcer/reviews/2025-06-22-review.md index 51cdff86..478bc317 100644 --- a/docs/enforcer/reviews/2025-06-22-review.md +++ b/docs/enforcer/reviews/2025-06-22-review.md @@ -1,5 +1,5 @@ --- -title: Enforcer Notes +title: 💀 Brutally-Honest Review & Non-Negotiable Marching Orders — Core †2025-06-22 Build description: Historical notes and enforcement-era artifacts. audience: [contributors] domain: [quality] diff --git a/docs/enforcer/specs/01-error-types-spec.md b/docs/enforcer/specs/01-error-types-spec.md index 378f3b41..e514740d 100644 --- a/docs/enforcer/specs/01-error-types-spec.md +++ b/docs/enforcer/specs/01-error-types-spec.md @@ -1,5 +1,5 @@ --- -title: Enforcer Notes +title: Specification: Error Handling and Result Types description: Historical notes and enforcement-era artifacts. audience: [contributors] domain: [quality] diff --git a/docs/enforcer/specs/02-domain-types-spec.md b/docs/enforcer/specs/02-domain-types-spec.md index 3fa54831..cfdbdc0d 100644 --- a/docs/enforcer/specs/02-domain-types-spec.md +++ b/docs/enforcer/specs/02-domain-types-spec.md @@ -1,5 +1,5 @@ --- -title: Domain Types and Strong Typedefs +title: Specification: Domain Types and Strong Typedefs description: Historical notes and enforcement-era artifacts. audience: [contributors] domain: [quality] diff --git a/docs/enforcer/specs/03-security-primitives-spec.md b/docs/enforcer/specs/03-security-primitives-spec.md index 7bead14b..f2b99e74 100644 --- a/docs/enforcer/specs/03-security-primitives-spec.md +++ b/docs/enforcer/specs/03-security-primitives-spec.md @@ -1,5 +1,5 @@ --- -title: Enforcer Notes +title: Specification: Security Primitives description: Historical notes and enforcement-era artifacts. audience: [contributors] domain: [quality] diff --git a/docs/features/Features_Ledger.md b/docs/features/Features_Ledger.md index a7132bc9..32f7a3a3 100644 --- a/docs/features/Features_Ledger.md +++ b/docs/features/Features_Ledger.md @@ -14,107 +14,233 @@ This is the canonical, grouped snapshot of features — shipped, in‑progress, ## Progress - +Progress is milestone-weighted overall, milestone-specific by KLoC, and feature-weighted within each group. Update via `python3 scripts/update_progress.py` or `make features-update` after edits. + + +Here's how we calculate the completion percentage of each milestone: + +${formula where features are weighted based on their estimated complexity}$ + +And here's how we calculate the completion percentage of the overall project: + +${overall progress formula}$ + +### Progress Bars + +``` + +| Milestone | % | Remarks | +|-----------|---|------------| +| MVP | `██████████████████████████████░░░░░░░░░░ 74%` | Min. Viable Product | +| Alpha | `█████████████████████████████▓░░░░░░░░░░ 73%` | Comes before Beta | +| Beta | `██████████████████████░░░░░░░░░░░░░░░░░░ 55%` | Half way | +| v1.0.0 | `█████████████████████████████████░░░░░░░ 82%` | Lol what? | +| --- | +| Total | `█████████████████████████████░░░░░░░░░░░ 72%` | Math don't be mathin' | + + ```text -███████████████████████████░░░░░░░░░░░░░ 66% -------------|-------------|------------| - MVP Alpha v1.0.0 + +MVP 74% | ALPHA 73% | BETA 55% | V1.0.0 82% ``` - + + +### MVP Progress + +**What “MVP” means:** Core linking/journal flows usable end-to-end for maintainers and early adopters; docs and safety rails in place for guided experiments. See `docs/planning/Milestone_Synthesis.md#mvpmmdash-show-hn-ready`. + + +```text +██████████████████████████████░░░░░░░░░░ 74% +``` + + +> [!INFO]- **Outstanding Tasks** +> +> _All tracked tasks complete_ +> + +### Alpha Progress + +**What “Alpha” means:** Broader team-ready; cache rebuilds reliable, augmented hooks online, telemetry/observability guardrails in place. See `docs/planning/Milestone_Synthesis.md#alpha-mdash-team-productivity`. + + +```text +█████████████████████████████▓░░░░░░░░░░ 73% +``` + + +> [!INFO]- **Outstanding Tasks** +> +> - [ ] Finalize bitmap cache conformance tests +> - [ ] Edge graph multi-branch coverage +> - [ ] Post‑commit AUGMENTS wiring +> - [ ] GraphQL auto‑resolve for accepted PR feedback +> - [ ] Validate worksheet reply workflow on a fresh PR +> -Weighted by feature size (simple average for now). Updated by `python3 scripts/update_progress.py` or `make features-update`. +### Beta Progress + +**What “Beta” means:** External contributors onboard smoothly; scaling telemetry captured; advanced review automation hardened. See `docs/planning/Milestone_Synthesis.md#beta-mdash-community-onboarding`. + + +```text +██████████████████████░░░░░░░░░░░░░░░░░░ 55% +``` + + +> [!INFO]- **Outstanding Tasks** +> +> - [ ] Surface attribution metadata in CLI output +> - [ ] Ledger snapshot automation +> + +### v1.0.0 Progress + +**What “v1.0.0” means:** Production-grade stability with complete semantics, attribution, and CI observability; ready for wider release and partner integrations. See `docs/planning/Milestone_Synthesis.md#v100-mdash-production-grade`. + + +```text +█████████████████████████████████░░░░░░░ 82% +``` + + +> [!INFO]- **Outstanding Tasks** +> +> - [ ] Adopt OID‑first equality everywhere (strict, no SHA fallback when OIDs present) +> - [ ] CI trend baselines collection +> ## Status Model -- Planned → In Progress → MVP → Alpha → V1 -- Stage names are canonical; “Shipped” is implied by MVP/Alpha/V1. +- Planned → In Progress → MVP → Alpha → Beta → v1.0.0 +- Stage names are canonical; “Shipped” is implied by milestone tags ≥ the current release. + +## Feature Lifecycle & Workflow + +Use the ledger as the single system of record from ideation through release: + +1. **Capture (Planned)** — When a new idea lands (roadmap review, retro, support signal), add a row under the appropriate group with a short name, owning area, and initial KLoC estimate. Link to any discovery notes/spec drafts in the “Spec” column and file a task in the `## Tasklist` section if further framing is needed. +2. **Framing (Planned → In Progress)** — Once scope and acceptance criteria are clear, mark status `In Progress`, ensure the “Current State” block describes the baseline, and list outstanding engineering/design work in the “Todo (Tasks)” column. Keep KLoC estimates realistic as tickets are broken down. +3. **Build & Land (In Progress)** — Engineers ship code behind feature flags/guards. Update progress % weekly (or when a significant chunk lands) and log validation tasks (tests, docs, follow-up stories). Reference the primary implementation branches/paths in the “Code” column. +4. **Validation (MVP)** — When the feature is usable end-to-end for the target persona, flip status to `MVP`. Document rollout steps, known gaps, and add stabilization tasks (dogfooding, bug bashes) to the ledger’s task list. +5. **Hardening (Alpha/Beta)** — Scale to broader audiences, tighten reliability/perf, and ensure telemetry/observability is live. Integrate feedback into Todo, tag follow-up tasks with `[Alpha]` or `[Beta]` as appropriate. +6. **General Availability (v1.0.0)** — All quality bars met, docs/tests complete, downstream consumers notified. Continue to attach post-GA follow-ups (deprecation notices, future enhancements) either as new ledger entries or subtasks in the Notes section. + +Operational rules: + +- Every feature row must have: owning area, milestone tag, spec/code pointers, KLoC estimate, status, progress %, and actionable Todo/Triage notes. Update KLoC when scope materially changes. +- The `## Tasklist` checklist is the authoritative backlog for cross-cutting work. Sync it whenever Todo items are resolved or re-scoped. +- README’s “📊 Status” reflects the overall milestone-weighted bar automatically; run `make features-update` after edits. +- For net-new features, create discovery docs in `docs/` and link them before moving past Planned. +- Retire legacy items by marking status `Deprecated` (optional column note) and migrating remaining tasks to successors. --- ### Core & Platform ```text -███████████████████████████████▓░░░░░░░░ 78% +████████████████████████████████░░░░░░░░ 79% ------------|-------------|------------| MVP Alpha v1.0.0 -features=? +features=8 ``` -| Emoji | Feature | Area | Spec | Code | KLoC (approx) | Status | Progress % | Bar | Current State | Todo (Tasks) | Tests | Remarks | -| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | -| 🧱 | OID‑first Core | Core | — | core/include, core/src | 5.0 | Alpha | 85% | █████████░ | Equality OID‑first; OID fields in CBOR; cache/journal aligned. | Finalize strict equality; docs complete. | Unit passing | Good foundation. | -| 🗄️ | Journal (CBOR) | Core | docs/architecture | core/src/journal | 3.0 | Alpha | 80% | ████████░░ | Writer/reader with base64; debug flag; attributed edges. | Finalize ordering; more tests. | Unit passing | Backwards compat OK. | -| ⚡ | Cache (Bitmap) | Core | docs/architecture | core/src/cache | 4.0 | In Progress | 70% | ███████░░░ | Rebuild + query; shard; metadata. | Conformance tests; size calc. | Unit partial | Performance tuning next. | -| 🔒 | CLI Safety Guard | CLI | docs/operations | apps/cli | 1.0 | MVP | 70% | ███████░░░ | Official repo guard; env override. | E2E extension; docs polish. | Unit | Solid. | -| 🔗 | Ref Utilities | Core | docs/architecture | core/src/util | 0.5 | MVP | 75% | ███████░░░ | `gm_build_ref` with validation; tests. | More negative tests; docs link. | Unit | Good coverage. | -| 🧰 | Safe String/Memory | Core | — | core/include/gitmind/util | 1.0 | V1 | 90% | █████████░ | Safe wrappers adopted in hot paths. | Sweep stragglers; docs. | Unit | Security uplift. | +| Emoji | Feature | Area | Spec | Code | Milestone | KLoC (approx) | Status | Progress % | Bar | Current State | Todo (Tasks) | Tests | Remarks | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 🧱 | OID‑first Core | Core | — | core/include, core/src | v1.0.0 | 3.5 | Alpha | 85% | █████████░ | Equality OID‑first; OID fields in CBOR; cache/journal aligned. | Finalize strict equality; docs complete. | Unit passing | Good foundation. | +| 🗄️ | Journal (CBOR) | Core | docs/architecture/journal-architecture-pivot.md | core/src/journal, core/src/cbor | Alpha | 1.2 | Alpha | 80% | ████████░░ | Writer/reader with base64; debug flag; attributed edges. | Finalize ordering; more tests. | Unit passing | Backwards compat OK. | +| ⚡ | Cache (Bitmap) | Core | docs/architecture/bitmap-cache-design.md | core/src/cache | Alpha | 1.6 | In Progress | 70% | ███████░░░ | Rebuild + query; shard; metadata. | Conformance tests; size calc. | Unit partial | Performance tuning next. | +| 🔗 | Ref Utilities | Core | docs/architecture/Ref_Name_Validation.md | core/src/util | MVP | 0.5 | MVP | 75% | ███████░░░ | `gm_build_ref` with validation; tests. | More negative tests; docs link. | Unit | Good coverage. | +| 🧰 | Safe String/Memory | Core | — | core/include/gitmind/util | v1.0.0 | 0.4 | V1 | 90% | █████████░ | Safe wrappers adopted in hot paths. | Sweep stragglers; docs. | Unit | Security uplift. | +| 🕸️ | Edge Graph Engine | Core | docs/architecture/System_Architecture.md | core/src/edge, core/include/gitmind/edge | Alpha | 1.0 | Alpha | 75% | ████████░░ | ULID-ordered edges; journal append + cache hydration. | Edge diff coverage; multi-branch stress. | Unit + fuzz | Forms graph spine. | +| 🧬 | Semantics & Type System | Core | docs/architecture/System_Architecture.md | core/src/types, core/src/utf8, core/src/time | MVP | 2.7 | Alpha | 80% | ████████░░ | Stable hashed IDs; NFC normalization; time-safe stamping. | Expose helper API; document name rules. | Unit | Ready for consumers. | +| 🪪 | Attribution Metadata | Core | docs/architecture/attribution-system.md | core/src/attribution | Beta | 0.2 | In Progress | 55% | ██████░░░░ | Capture author/time for edges; merge helpers in place. | Extend multi-author rollups; CLI surfacing. | Unit scaffolding | Needs UX polish. | ### CLI, Hooks & UX ```text -██████████████████████████████░░░░░░░░░░ 74% +████████████████████████████░░░░░░░░░░░░ 69% ------------|-------------|------------| MVP Alpha v1.0.0 -features=? +features=7 ``` -| Emoji | Feature | Area | Spec | Code | KLoC (approx) | Status | Progress % | Bar | Current State | Todo (Tasks) | Tests | Remarks | -| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | -| 🪝 | Post‑commit Hook (AUGMENTS) | Hooks | docs/hooks | core/src/hooks | 0.5 | In Progress | 50% | █████░░░░░ | Process changed files; AUGMENTS edge. | Path truncation handling (done); more cases. | Unit | Wire to journal read. | -| 🧰 | Review Seeding & Replies | DX | docs/tools | tools/review, workflows | 0.5 | MVP | 80% | ████████░░ | Seed + auto‑reply; artifact fallback. | GraphQL auto‑resolve; GH App. | CI + unit | High leverage. | -| 📜 | Docs Tooling | Docs | docs/tools | tools/docs | 0.4 | MVP | 70% | ███████░░░ | Frontmatter/TOC/title checks; labeler. | Extend templates; more guides. | Scripted | Good base. | -| 🧭 | Curated AGENTS.md | DX | docs | tools/agents | 0.2 | MVP | 80% | ████████░░ | TL;DR + YAML; curator; archives. | Tune summaries; monthly rollup. | Scripted | Fast onboarding. | -| 🧪 | Worksheet Gates | DX | docs/tools | tools/review | 0.3 | V1 | 90% | █████████░ | Pre‑push checks for placeholders + decisions. | Heuristics later (optional). | Scripted | Keeps quality high. | +| Emoji | Feature | Area | Spec | Code | Milestone | KLoC (approx) | Status | Progress % | Bar | Current State | Todo (Tasks) | Tests | Remarks | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 🪝 | Post‑commit Hook (AUGMENTS) | Hooks | docs/hooks | core/src/hooks | Alpha | 0.5 | In Progress | 50% | █████░░░░░ | Process changed files; AUGMENTS edge. | Path truncation handling (done); more cases. | Unit | Wire to journal read. | +| 🔒 | CLI Safety Guard | CLI | docs/operations/Environment_Variables.md | apps/cli/cli_runtime.c | MVP | 0.6 | MVP | 70% | ███████░░░ | Official repo guard; env override; safe install workflow. | Extend host override tests; document upgrade path. | Unit | Solid baseline. | +| 🛠️ | `git mind` CLI Commands | CLI | apps/cli/main.md | apps/cli | MVP | 1.2 | MVP | 65% | ██████░░░░ | `link`, `list`, cache rebuild; shared runtime utilities. | Add query subcommands; richer diagnostics. | Unit + manual | Ready for daily use. | +| 🧰 | Review Seeding & Replies | DX | docs/tools | tools/review, workflows | Alpha | 0.4 | MVP | 80% | ████████░░ | Seed + auto‑reply; artifact fallback; reply templates rendered cleanly. | Gate GraphQL auto-resolve behind flag; document live PR validation; GH App roadmap. | CI + unit | High leverage. | +| 📜 | Docs Tooling | Docs | docs/tools | tools/docs | MVP | 0.4 | MVP | 70% | ███████░░░ | Frontmatter/TOC/title checks; labeler. | Extend templates; more guides. | Scripted | Good base. | +| 🧭 | Curated AGENTS.md | DX | docs | tools/agents | MVP | 0.2 | MVP | 80% | ████████░░ | TL;DR + YAML; curator; archives. | Tune summaries; monthly rollup. | Scripted | Fast onboarding. | +| 🧪 | Worksheet Gates | DX | docs/tools | tools/review | Alpha | 0.3 | V1 | 90% | █████████░ | Pre‑push checks for placeholders + decisions. | Heuristics later (optional). | Scripted | Keeps quality high. | ### Observability & Analytics ```text -███████████████████░░░░░░░░░░░░░░░░░░░░░ 47% +█████████████████████▓░░░░░░░░░░░░░░░░░░ 53% ------------|-------------|------------| MVP Alpha v1.0.0 -features=? +features=3 ``` -| Emoji | Feature | Area | Spec | Code | KLoC (approx) | Status | Progress % | Bar | Current State | Todo (Tasks) | Tests | Remarks | -| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | -| 🔎 | CBOR Debug Tracing | Core/Obs | docs/operations | core/src/journal | 0.2 | MVP | 60% | ██████░░░░ | Env flag for verbose decode. | Structured logging; sampling. | Unit | Helpful during migration. | -| 📈 | Progress Ledgers | DX/Obs | docs/features | scripts | 0.3 | MVP | 60% | ██████░░░░ | Ledger + updater script. | Weighting; KLoC metrics. | Scripted | Improves planning. | -| 📊 | CI Trend Baselines | Obs | docs/ci | tools | 0.2 | Planned | 20% | ██░░░░░░░░ | Not started. | Collect tidy counts; failures. | — | Future. | +| Emoji | Feature | Area | Spec | Code | Milestone | KLoC (approx) | Status | Progress % | Bar | Current State | Todo (Tasks) | Tests | Remarks | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 🔎 | CBOR Debug Tracing | Core/Obs | docs/operations | core/src/journal | Alpha | 0.2 | MVP | 60% | ██████░░░░ | Env flag for verbose decode. | Structured logging; sampling. | Unit | Helpful during migration. | +| 📈 | Progress Ledgers | DX/Obs | docs/features | scripts | MVP | 0.3 | MVP | 70% | ███████░░░ | Ledger + updater script; KLoC-weighted bars + README sync. | Expose CLI summary; automate weekly snapshots. | Scripted | Improves planning. | +| 📊 | CI Trend Baselines | Obs | docs/ci | tools | v1.0.0 | 0.2 | Planned | 20% | ██░░░░░░░░ | Not started. | Collect tidy counts; failures. | — | Future. | -## Tasks +## Tasklist ### Core & Platform -- [ ] Adopt OID‑first equality everywhere (strict, no SHA fallback when OIDs present) +- [ ] [v1.0.0] Adopt OID‑first equality everywhere (strict, no SHA fallback when OIDs present) > [!INFO]- > Update comparisons and tests; align cache/journal; document in TECHNICAL.md. -- [ ] Finalize bitmap cache conformance tests +- [ ] [Alpha] Finalize bitmap cache conformance tests > [!INFO]- > Build synthetic repos; verify shard distribution and size calculations; add docs. +- [ ] [Alpha] Edge graph multi-branch coverage +> [!INFO]- +> Add regression tests for branch fan-out, ULID ordering guarantees, and edge diff helpers; capture findings in `docs/architecture/System_Architecture.md`. + +- [ ] [Beta] Surface attribution metadata in CLI output +> [!INFO]- +> Thread author/time data through cache rebuild + `git mind list`; document flag to toggle extended columns. + ### CLI, Hooks & UX -- [ ] Post‑commit AUGMENTS wiring +- [ ] [Alpha] Post‑commit AUGMENTS wiring > [!INFO]- > Finish journal read integration; handle path truncation errors; add E2E. -- [ ] GraphQL auto‑resolve for accepted PR feedback +- [ ] [Alpha] GraphQL auto‑resolve for accepted PR feedback +> [!INFO]- +> Add a feature-flagged path in `apply-feedback` to call `discussion.resolveReviewThread`; map worksheet IDs to GraphQL node IDs and dry-run before enabling by default. + +- [ ] [Alpha] Validate worksheet reply workflow on a fresh PR > [!INFO]- -> Extend apply-feedback workflow with GraphQL to resolve threads after replies. +> Run `make apply-feedback` against a new test PR, capture rendered replies, and embed screenshots/notes in `docs/tools/Review_Seeding.md`. ### Observability & Analytics -- [ ] CI trend baselines collection +- [ ] [v1.0.0] CI trend baselines collection > [!INFO]- > Record tidy counts and unit results; render sparklines; add dashboards. +- [ ] [Beta] Ledger snapshot automation +> [!INFO]- +> Wire `make features-update` into a scheduled workflow and add regression tests to confirm README + ledger stay in sync. + --- Notes - Update via `python3 scripts/update_progress.py` (or `make features-update`). -- Progress bars are averaged for now; weighting and KLoC are future work. +- Progress bars use KLoC weighting; keep the KLoC column fresh to avoid drift. diff --git a/docs/planning/Milestone_Synthesis.md b/docs/planning/Milestone_Synthesis.md new file mode 100644 index 00000000..3fb3f032 --- /dev/null +++ b/docs/planning/Milestone_Synthesis.md @@ -0,0 +1,83 @@ +--- +title: Milestone Synthesis & Scope Map +description: Consolidated view of MVP, Alpha, Beta, and v1.0.0 goals with cross-references to existing plans. +audience: [contributors] +domain: [planning] +tags: [milestones, roadmap] +status: draft +last_updated: 2025-09-16 +--- + +# Milestone Synthesis & Scope Map + +This guide aligns the many planning artifacts (HN demo plan, roadmap snapshots, milestone lists, release plans, brainstorms) into a single, milestone-oriented view. Use it when updating the [Features Ledger](../features/Features_Ledger.md) or when onboarding new contributors. + +## Table of Contents + +- [Quick Reference Table](#quick-reference-table) +- [Milestone Details](#milestone-details) + - [MVP — “Show HN” Ready](#mvp--show-hn-ready) + - [Alpha — Team Productivity](#alpha--team-productivity) + - [Beta — Community Onboarding](#beta--community-onboarding) + - [v1.0.0 — Production-Grade](#v100--production-grade) +- [How to Use This Doc](#how-to-use-this-doc) + +## Quick Reference Table + +| Milestone | Focus | Key Deliverables | Primary Sources | +|-----------|-------|------------------|-----------------| +| MVP | Prove the Git-native “mental model time-travel” loop; demo-ready flows. | Journal + AUGMENTS edges, core CLI (`link/list/cache`), deterministic semantics IDs, baseline cache rebuild + query, docs for demo. | `.legacy/HN Demo Plan.md`, `docs/planning/Milestones.md` (M0–M4), `docs/planning/Release_Plans.md` (v0.4–v0.6). +| Alpha | Team-ready tooling with reliable rebuilds and collaboration helpers. | Cohesion report basics, worksheet/review automation, cache perf guardrails, observability hooks, expanded CLI diagnostics. | `docs/planning/Milestones.md` (M5), `docs/planning/Release_Plans.md` (v0.7–v0.8), `docs/roadmap.md` (near/medium term). +| Beta | External contributor onboarding, advanced automation, packaging polish. | Advice merge + plugin hook stubs, CI hardening, packaging pipeline, attribution surfaced in CLI, telemetry snapshots. | `docs/planning/Milestones.md` (M6–M9), `docs/planning/Release_Plans.md` (v0.9–v0.10), `docs/wish-list-features/brain-storms/plugins.md`. +| v1.0.0 | Production-grade stability with complete semantics + attribution story. | OID-first equality everywhere, CI trend baselines, packaging/release hygiene, documentation freeze, optional MCP service (if landed). | `docs/planning/Release_Plans.md` (v0.10 + v0.11 optional), `docs/planning/Product_Roadmap.md`, `docs/planning/Milestones.md`. + +## Milestone Details + +### MVP — “Show HN” Ready + +- **Experience goal:** Deliver the 30-second hook from `.legacy/HN Demo Plan.md` — initialize, link, time-travel, list, and traverse understanding history. +- **Scope highlights:** + - Journal append + AUGMENTS hook (Milestones M3), deterministic semantics IDs (M1), CBOR names (M2). + - CLI basics (`link`, `list`, `cache-rebuild`) with helpful errors (Release v0.4–v0.6). + - Baseline cache to support `git mind list` across history (Product Roadmap Themes A/B/C). + - Docs + scripts to reproduce the demo. +- **Exit criteria:** A maintainer can run the HN demo on a fresh repo, share reproducible docs, and recover after cache/journal reset. + +### Alpha — Team Productivity + +- **Experience goal:** Internal team uses git-mind daily with confidence in rebuilds and collaboration flows. +- **Scope highlights:** + - Cohesion report + branch-aware queries (Milestones M5, Release v0.7–v0.8). + - Worksheet automation + reply workflows (Features Ledger “Review Seeding & Replies”). + - Cache performance guardrails (<10ms median per Release Plan), telemetry knobs (Roadmap “Medium Term”). + - Observability: CBOR debug tracing, ledger snapshot tasks. +- **Exit criteria:** Cache rebuilds complete without manual babysitting; collaboration loops (worksheet, review replies) exercised on real PR; alpha docs outline known gaps. + +### Beta — Community Onboarding + +- **Experience goal:** External contributors can install, review, and extend git-mind without maintainer hand-holding. +- **Scope highlights:** + - Advice merge CRDT + plugin hook scaffolding (Milestones M6–M9, Release v0.9–v0.10). + - Attribution surfaced in CLI output; ledger snapshots automated for transparency. + - Packaging + CI hardening; tidy-zero guard for core modules. + - Plugin vision seeds (wishlist brainstorm) inform optional experiments. +- **Exit criteria:** Nightly builds + packaging succeed, documentation covers install/update flows, advanced review automation stable, plugin hooks gated but demonstrable. + +### v1.0.0 — Production-Grade + +- **Experience goal:** git-mind installs cleanly, passes strict CI, and offers a complete semantics + attribution story suitable for partners. +- **Scope highlights:** + - OID-first equality everywhere; safe wrappers swept (ledger tasks, Release Plan). + - CI trend baselines & observability dashboards. + - Packaging artifacts with checksums + version policy (Release v0.10) plus optional MCP service (v0.11) if ready. + - Documentation freeze + API stability commitments (Roadmap long-term). +- **Exit criteria:** All v0.x acceptance criteria met, outstanding ledger tasks closed or re-scoped, README/Features Ledger alignment signed off. + +## How to Use This Doc + +1. **Feature Ledger updates:** Pick the milestone whose exit criteria match the feature’s ambition; update the `Milestone` column accordingly. +2. **Task tagging:** Prefix checklist items with `[MVP]`, `[Alpha]`, `[Beta]`, or `[v1.0.0]` to feed the ledger callouts. +3. **Planning syncs:** Reference the Quick Reference table during roadmap discussions to ensure new ideas map to an existing milestone (or justify a new one). +4. **Docs hygiene:** When adding new planning material, include a “Milestone Alignment” note linking back here to keep the taxonomy coherent. + +Keeping these milestones aligned across docs prevents drift and keeps our progress bars meaningful. diff --git a/docs/planning/Milestones.md b/docs/planning/Milestones.md index b23be0bb..b1d24e58 100644 --- a/docs/planning/Milestones.md +++ b/docs/planning/Milestones.md @@ -1,5 +1,5 @@ --- -title: Planning Doc +title: Milestones description: Planning artifacts: roadmap, releases, sprints, milestones. audience: [contributors] domain: [project] diff --git a/docs/planning/Product_Roadmap.md b/docs/planning/Product_Roadmap.md index 906728ee..177b6d55 100644 --- a/docs/planning/Product_Roadmap.md +++ b/docs/planning/Product_Roadmap.md @@ -1,5 +1,5 @@ --- -title: Planning Doc +title: Product Roadmap description: Planning artifacts: roadmap, releases, sprints, milestones. audience: [contributors] domain: [project] diff --git a/docs/planning/Release_Plans.md b/docs/planning/Release_Plans.md index f1666f74..7e3e666c 100644 --- a/docs/planning/Release_Plans.md +++ b/docs/planning/Release_Plans.md @@ -1,5 +1,5 @@ --- -title: Planning Doc +title: Release Plans description: Planning artifacts: roadmap, releases, sprints, milestones. audience: [contributors] domain: [project] diff --git a/docs/planning/Sprint_Plans.md b/docs/planning/Sprint_Plans.md index 7bb03bb4..d2a712c6 100644 --- a/docs/planning/Sprint_Plans.md +++ b/docs/planning/Sprint_Plans.md @@ -1,5 +1,5 @@ --- -title: Planning Doc +title: Sprint Plans description: Planning artifacts: roadmap, releases, sprints, milestones. audience: [contributors] domain: [project] diff --git a/docs/quality/SOLID_DRY_REPORT.md b/docs/quality/SOLID_DRY_REPORT.md index a43c1af7..e889ecf5 100644 --- a/docs/quality/SOLID_DRY_REPORT.md +++ b/docs/quality/SOLID_DRY_REPORT.md @@ -1,5 +1,5 @@ --- -title: SOLID/DRY Compliance Report +title: 🚨 SOLID/DRY Compliance Report - CRITICAL SECURITY ASSESSMENT description: Assessment of the codebase against SOLID and DRY with remediation guidance. audience: [contributors, developers] domain: [quality] diff --git a/docs/quality/TIDY_CLANG_CRUSADE.md b/docs/quality/TIDY_CLANG_CRUSADE.md index ad023f34..cf751060 100644 --- a/docs/quality/TIDY_CLANG_CRUSADE.md +++ b/docs/quality/TIDY_CLANG_CRUSADE.md @@ -1,5 +1,5 @@ --- -title: The Great Clang-Tidy Crusade +title: 🚨 The Great Clang-Tidy Crusade description: Tracking clang-tidy issues and progress toward zero warnings. audience: [contributors, developers] domain: [quality] diff --git a/docs/quality/static-analysis-guide.md b/docs/quality/static-analysis-guide.md index 209df6f0..6d3ce8f7 100644 --- a/docs/quality/static-analysis-guide.md +++ b/docs/quality/static-analysis-guide.md @@ -1,5 +1,5 @@ --- -title: Static Analysis Tools for git-mind +title: Static Analysis Tools for Git-Mind description: Overview of clang-tidy and related tools for static analysis in this repo. audience: [contributors, developers] domain: [quality] diff --git a/docs/sitrep/2025-06-24/ci-sitrep.md b/docs/sitrep/2025-06-24/ci-sitrep.md index bec619ff..85d28eeb 100644 --- a/docs/sitrep/2025-06-24/ci-sitrep.md +++ b/docs/sitrep/2025-06-24/ci-sitrep.md @@ -1,5 +1,5 @@ --- -title: SITREP +title: CI Infrastructure SITREP - 2025-06-24 description: Situation reports and CI notes. audience: [contributors] domain: [quality] diff --git a/docs/talk-shop/centralized-cbor-keys-and-public-apis.md b/docs/talk-shop/centralized-cbor-keys-and-public-apis.md index c9929d32..598ca1ff 100644 --- a/docs/talk-shop/centralized-cbor-keys-and-public-apis.md +++ b/docs/talk-shop/centralized-cbor-keys-and-public-apis.md @@ -1,5 +1,5 @@ --- -title: Talk Shop +title: Centralized CBOR Keys and Public Encoders description: Explorations and design discussions. audience: [contributors] domain: [project] diff --git a/docs/talk-shop/deterministic-merges-crdt-advice.md b/docs/talk-shop/deterministic-merges-crdt-advice.md index 98814c46..7e6880b0 100644 --- a/docs/talk-shop/deterministic-merges-crdt-advice.md +++ b/docs/talk-shop/deterministic-merges-crdt-advice.md @@ -1,5 +1,5 @@ --- -title: Talk Shop +title: Deterministic Merges with CRDT Advice description: Explorations and design discussions. audience: [contributors] domain: [project] diff --git a/docs/talk-shop/hardening-mindset.md b/docs/talk-shop/hardening-mindset.md index be90375c..b339f2b9 100644 --- a/docs/talk-shop/hardening-mindset.md +++ b/docs/talk-shop/hardening-mindset.md @@ -1,5 +1,5 @@ --- -title: Talk Shop +title: The Hardening Mindset: Safety as a Feature description: Explorations and design discussions. audience: [contributors] domain: [project] diff --git a/docs/talk-shop/journal-first-cbor-commits.md b/docs/talk-shop/journal-first-cbor-commits.md index 5268737f..60095181 100644 --- a/docs/talk-shop/journal-first-cbor-commits.md +++ b/docs/talk-shop/journal-first-cbor-commits.md @@ -1,5 +1,5 @@ --- -title: Talk Shop +title: Journal‑First CBOR Commits: Time‑Travel You Can Trust description: Explorations and design discussions. audience: [contributors] domain: [project] diff --git a/docs/talk-shop/oid-first-migration.md b/docs/talk-shop/oid-first-migration.md index 1dd0b9ff..3316210c 100644 --- a/docs/talk-shop/oid-first-migration.md +++ b/docs/talk-shop/oid-first-migration.md @@ -1,5 +1,5 @@ --- -title: Talk Shop +title: OID‑First Migration: Future‑Proof by Design description: Explorations and design discussions. audience: [contributors] domain: [project] diff --git a/docs/templates/code-review-feedback.md b/docs/templates/code-review-feedback.md index f16e3074..b1fc1f07 100644 --- a/docs/templates/code-review-feedback.md +++ b/docs/templates/code-review-feedback.md @@ -9,9 +9,9 @@ status: archive # Code Review Feedback -| Date | Agent | SHA | Branch | PR | -|------|-------|-----|--------|----| -| {date} | {agent} | `{sha}` | [{branch}]({github_branch_url}) | [PR#{pr_number}]({pr_url}) | +| Date | Agent | SHA | Branch | Branch URL | PR URL | +| ------ | ------- | ------- | -------- | --------------------- | ---------- | +| {date} | {agent} | `{sha}` | {branch} | `{github_branch_url}` | `{pr_url}` | ## Instructions @@ -25,7 +25,7 @@ Please use the following template to record your acceptance. ```markdown -> [!NOTE]- **Acceepted** +> [!NOTE]- **Accepted** > | Confidence | Remarks | > |------------|---------| > | {confidence_score_out_of_10} | {confidence_rationale} | @@ -38,7 +38,7 @@ Please use the following template to record your acceptance. > > {what_you_did} > -> ## Regression Avoidance Strategy +> ## Regression avoidance strategy > > {regression_avoidance_strategy} > @@ -63,7 +63,7 @@ Please use the following template to record your rejections. > > {rationale} > -> ## What you did instead +> ## What did you do instead? > > {what_you_did} > @@ -85,18 +85,12 @@ Please use the following template to record your rejections. ## CODE REVIEW FEEDBACK +> How to use: copy one of the fenced templates above, paste under each feedback item, and replace all `{placeholders}`. + The following section contains the feedback items, extracted from the code review linked above. Please read each item and respond with your decision by injecting one of the two above templates beneath the feedback item. ### {feedback_item_title} -```text -{feedback_quote} -``` - -{response} - ---- - ## Conclusion | Accepted | Rejected | Remarks | diff --git a/docs/tools/PR_Workflow_Factoring.md b/docs/tools/PR_Workflow_Factoring.md index 25f0ef3b..9d0e4159 100644 --- a/docs/tools/PR_Workflow_Factoring.md +++ b/docs/tools/PR_Workflow_Factoring.md @@ -8,9 +8,11 @@ status: draft last_updated: 2025-09-16 --- -# Overview +# Factoring PR Workflow to a Standalone Repo -This guide captures how to factor our “PR feedback → worksheet → auto‑reply” workflow into a separate, reusable repository that any project can consume with minimal setup. +## Overview + +This guide captures how to factor our “PR feedback → worksheet → auto-reply” workflow into a separate, reusable repository that any project can consume with minimal setup. The goal is a portable, easy‑install review pipeline that works great for both AI agents and humans: seed a worksheet from PR comments, fill in Accepted/Rejected with rationale, and let the bot reply and (optionally) resolve threads. @@ -217,4 +219,3 @@ Deliver smooth on‑ramp + high trust: - Safety: dry‑run modes, explicit labels to enable writing. - Telemetry: text summaries + JSON for automation. - Extensibility: template markers for block parsing, configurable decision markers, pluggable resolvers. - diff --git a/docs/tools/Review_Seeding.md b/docs/tools/Review_Seeding.md index a7dee5a5..94747992 100644 --- a/docs/tools/Review_Seeding.md +++ b/docs/tools/Review_Seeding.md @@ -69,6 +69,15 @@ The workflow will use `GITMIND_PR_WORKSHEET_BOT` to push the seeded doc to fork - Dispatch from Actions with input `pr=` - Produces an artifact (folder `review-seed`) with the generated worksheet +## Reply Workflow Validation + +When updating templates or automation, run a quick readability check: + +1. Open a scratch PR (or reuse a maintenance PR) and ensure it has at least one unresolved review thread. +2. Update the worksheet locally, then run `make apply-feedback FILES="docs/code-reviews/PR/*.md"` so the workflow replies on your behalf (requires `GITHUB_TOKEN`). +3. Inspect the GitHub conversation to confirm Markdown renders correctly (callouts collapsed, bullets aligned) and capture a screenshot for the changelog if formatting changed. +4. If anything regresses, roll back the worksheet commit and iterate locally before retrying. + ## Review Document Structure - Location: `docs/code-reviews/PR/.md` @@ -103,4 +112,3 @@ The workflow will use `GITMIND_PR_WORKSHEET_BOT` to push the seeded doc to fork - Trade‑off: broader scope than fine‑grained tokens. - Auto‑open helper PR to contributor fork - If push to fork fails, create a helper PR in their fork with the seeded doc. This typically requires permission to fork/cross‑fork and may be restricted. Consider only if contributor experience warrants it. - diff --git a/docs/wish-list-features/brain-storms/CLAUDE_DEEP_THOUGHTS_FINAL.md b/docs/wish-list-features/brain-storms/CLAUDE_DEEP_THOUGHTS_FINAL.md index 451b93b9..c1a0794b 100644 --- a/docs/wish-list-features/brain-storms/CLAUDE_DEEP_THOUGHTS_FINAL.md +++ b/docs/wish-list-features/brain-storms/CLAUDE_DEEP_THOUGHTS_FINAL.md @@ -1,5 +1,5 @@ --- -title: Wish List +title: 🧠💎 CLAUDE'S DEEP THOUGHTS: The Git-Mind Vision Crystallized description: Feature brainstorms and design sketches. audience: [contributors] domain: [project] diff --git a/docs/wish-list-features/brain-storms/plugins.md b/docs/wish-list-features/brain-storms/plugins.md index eb994fdd..ef74a963 100644 --- a/docs/wish-list-features/brain-storms/plugins.md +++ b/docs/wish-list-features/brain-storms/plugins.md @@ -1,5 +1,5 @@ --- -title: Plugin Architecture 2.0 — The Ecosystem Revolution +title: 🔌 Plugin Architecture 2.0: The Ecosystem Revolution description: Feature brainstorms and design sketches. audience: [contributors] domain: [project] diff --git a/docs/wish-list-features/plugins2.0/00-summary.md b/docs/wish-list-features/plugins2.0/00-summary.md index 17c01af9..2eab476c 100644 --- a/docs/wish-list-features/plugins2.0/00-summary.md +++ b/docs/wish-list-features/plugins2.0/00-summary.md @@ -1,5 +1,5 @@ --- -title: Wish List +title: Plugin Architecture 2.0: Git-Mind Ecosystem Revolution description: Feature brainstorms and design sketches. audience: [contributors] domain: [project] diff --git a/docs/wish-list-features/plugins2.0/01-requirements.md b/docs/wish-list-features/plugins2.0/01-requirements.md index 7b46284b..1ba0f824 100644 --- a/docs/wish-list-features/plugins2.0/01-requirements.md +++ b/docs/wish-list-features/plugins2.0/01-requirements.md @@ -1,5 +1,5 @@ --- -title: Wish List +title: Feature Requirements: Plugin Architecture 2.0 description: Feature brainstorms and design sketches. audience: [contributors] domain: [project] diff --git a/docs/wish-list-features/plugins2.0/02-tech-design.md b/docs/wish-list-features/plugins2.0/02-tech-design.md index 466a8a38..7b70bf65 100644 --- a/docs/wish-list-features/plugins2.0/02-tech-design.md +++ b/docs/wish-list-features/plugins2.0/02-tech-design.md @@ -1,5 +1,5 @@ --- -title: Plugin Architecture 2.0 — Tech Design +title: Technical Design: Plugin Architecture 2.0 description: Feature brainstorms and design sketches. audience: [contributors] domain: [project] diff --git a/docs/wish-list-features/plugins2.0/03-api.md b/docs/wish-list-features/plugins2.0/03-api.md index 81ae8dc3..59e183ff 100644 --- a/docs/wish-list-features/plugins2.0/03-api.md +++ b/docs/wish-list-features/plugins2.0/03-api.md @@ -1,5 +1,5 @@ --- -title: Plugin Architecture 2.0 — API Specification +title: API Specification: Plugin Architecture 2.0 description: Feature brainstorms and design sketches. audience: [contributors] domain: [project] diff --git a/docs/wish-list-features/plugins2.0/05-security.md b/docs/wish-list-features/plugins2.0/05-security.md index 95db3102..1bf02f3d 100644 --- a/docs/wish-list-features/plugins2.0/05-security.md +++ b/docs/wish-list-features/plugins2.0/05-security.md @@ -1,5 +1,5 @@ --- -title: Wish List +title: __🔒 Security Review: Plugin Architecture 2.0__ description: Feature brainstorms and design sketches. audience: [contributors] domain: [project] diff --git a/scripts/update_progress.py b/scripts/update_progress.py index c9b2b4f8..be34f759 100644 --- a/scripts/update_progress.py +++ b/scripts/update_progress.py @@ -2,12 +2,13 @@ """ Update feature progress bars in docs/features/Features_Ledger.md and README.md. -Simple averaging of Progress % across group tables. Weighting/KLoC are TODO. +Progress is derived from per-feature percentages using KLoC as weights. Milestone +bars aggregate features by milestone, while the overall bar blends milestones via +configurable weights. """ from __future__ import annotations import re from pathlib import Path -import math ROOT = Path(__file__).resolve().parents[1] LEDGER = ROOT / "docs" / "features" / "Features_Ledger.md" @@ -16,24 +17,50 @@ GROUP_RE = re.compile(r"\n```text\n(.*?)\n```\n", re.S | re.I) OVERALL_RE = re.compile(r"\n```text\n(.*?)\n```\n", re.S) READ_ME_BLOCK_RE = re.compile(r"\n```text\n(.*?)\n```\n", re.S) +OVERALL_SECTION_RE = re.compile(r"\n```text\n(.*?)\n```\n", re.S) +MILESTONE_RE = { + key: re.compile(rf"\n```text\n(.*?)\n```\n", re.S) + for key in ("mvp", "alpha", "beta", "v1") +} +TASK_BLOCK_RE = { + key: re.compile(rf"> \n(.*?)\n> ", re.S) + for key in ("mvp", "alpha", "beta", "v1") +} + +MILESTONE_LABELS = { + "MVP": "mvp", + "Alpha": "alpha", + "Beta": "beta", + "v1.0.0": "v1", + "V1": "v1", +} + +MILESTONE_WEIGHTS = { + "mvp": 0.3, + "alpha": 0.3, + "beta": 0.2, + "v1": 0.2, +} def progress_bar(pct: float, width: int = 40) -> str: + pct = max(0.0, min(1.0, pct)) filled = int(round(pct * width)) filled = min(filled, width) - return "█" * filled + ("▓" if filled < width and (pct*width - filled) > 0 else "") + "░" * (width - filled - (1 if filled < width and (pct*width - filled) > 0 else 0)) + f" {int(round(pct*100))}%" + remainder = pct * width - filled + edge = 1 if filled < width and remainder > 0 else 0 + return "█" * filled + ("▓" if edge else "") + "░" * (width - filled - edge) + f" {int(round(pct * 100))}%" -def compute_group_percent(md: str, anchor: int) -> float: +def compute_group_percent(md: str, anchor: int, entries: list[tuple[str, float, float]] | None = None) -> tuple[float, float, int]: tail = md[anchor:] # find the feature table header m = re.search(r"^\|\s*Emoji\s*\|", tail, re.M) if not m: - return 0.0 + return 0.0, 0.0, 0 i = m.start() table = tail[i:].splitlines() if len(table) < 3: - return 0.0 + return 0.0, 0.0, 0 header = table[0] - sep = table[1] if len(table) > 1 else '' rows = table[2:] header_cells = [c.strip() for c in header.strip().split('|')] # locate column indices @@ -44,8 +71,10 @@ def find_idx(name_sub: str) -> int: return -1 progress_idx = find_idx('Progress') kloc_idx = find_idx('KLoC') - vals = [] - weights = [] + milestone_idx = find_idx('Milestone') + vals: list[float] = [] + weights: list[float] = [] + count = 0 for line in rows: if not line.startswith('|'): break @@ -68,42 +97,150 @@ def find_idx(name_sub: str) -> int: break if prog is None: continue - # weight from KLoC - w = 1.0 + # weight from KLoC (default small weight so features without data still count) + w = 0.1 if 0 <= kloc_idx < len(cells): try: - kloc = float(cells[kloc_idx]) - w = max(0.5, 1.0 + math.log10(kloc * 1000 + 10.0) / 3.0) + raw = cells[kloc_idx].replace(',', '') + match = re.search(r"-?\d+(?:\.\d+)?", raw) + if match: + kloc = float(match.group(0)) + if kloc > 0: + w = kloc except Exception: - w = 1.0 + w = 0.1 vals.append(prog) weights.append(w) + count += 1 + if entries is not None: + milestone = "Unassigned" + if 0 <= milestone_idx < len(cells): + milestone = cells[milestone_idx] or "Unassigned" + entries.append((milestone.strip(), prog / 100.0, w)) if not vals: - return 0.0 - # weighted average - wsum = sum(weights) if weights else float(len(vals)) - return (sum(p * w for p, w in zip(vals, weights)) / wsum) / 100.0 + return 0.0, 0.0, 0 + wsum = sum(weights) + if wsum <= 0: + pct = sum(vals) / len(vals) / 100.0 + else: + pct = (sum(p * w for p, w in zip(vals, weights)) / wsum) / 100.0 + return pct, wsum, count + +def extract_tasks(md: str) -> dict[str, list[str]]: + tasks: dict[str, list[str]] = {k: [] for k in MILESTONE_RE.keys()} + lower = md.lower() + if "## tasklist" not in lower: + return tasks + start = lower.index("## tasklist") + segment = md[start:] + for line in segment.splitlines(): + stripped = line.strip() + if stripped.startswith("- [ ]"): + tag = None + rest = stripped[len("- [ ]"):].strip() + if rest.startswith("[") and "]" in rest: + tag_name = rest[1:rest.index("]")] + key = MILESTONE_LABELS.get(tag_name, None) + if key: + tag = key + rest = rest[rest.index("]") + 1:].strip() + entry = f"- [ ] {rest}" if rest else "- [ ]" + else: + entry = stripped + else: + entry = stripped + if not tag: + tag = "mvp" + tasks.setdefault(tag, []).append(entry if tag in tasks else stripped) + return tasks + -def update_ledger(): +def update_ledger() -> tuple[float | None, dict[str, float], dict[str, list[str]]]: text = LEDGER.read_text(encoding='utf-8') groups = [] new = text + feature_entries: list[tuple[str, float, float]] = [] for m in GROUP_RE.finditer(text): start = m.start() name = m.group(1) - pct = compute_group_percent(text, m.end()) + pct, weight, count = compute_group_percent(text, m.end(), feature_entries) bar = progress_bar(pct) - block = f"\n```text\n{bar}\n------------|-------------|------------|\n MVP Alpha v1.0.0 \nfeatures=?\n```\n" + feature_tag = f"features={count}" if count else "features=0" + block = ( + f"\n" \ + "```text\n" \ + f"{bar}\n" \ + "------------|-------------|------------|\n" \ + " MVP Alpha v1.0.0 \n" \ + f"{feature_tag}\n" \ + "```\n" \ + f"" + ) new = new.replace(m.group(0), block) - groups.append(pct) - if groups: - overall = sum(groups) / len(groups) - over_m = OVERALL_RE.search(new) - over_block = f"\n```text\n{progress_bar(overall)}\n------------|-------------|------------|\n MVP Alpha v1.0.0 \n```\n" - if over_m: - new = new.replace(over_m.group(0), over_block) + groups.append((pct, weight if weight > 0 else float(count or 0))) + milestone_totals: dict[str, tuple[float, float]] = { + key: (0.0, 0.0) for key in MILESTONE_RE.keys() + } + for raw_label, pct, weight in feature_entries: + key = MILESTONE_LABELS.get(raw_label or "", None) + if not key: + continue + total_pct, total_weight = milestone_totals[key] + milestone_totals[key] = (total_pct + pct * weight, total_weight + weight) + milestone_progress: dict[str, float] = {} + for key, (total, weight) in milestone_totals.items(): + if weight > 0: + milestone_progress[key] = total / weight + else: + milestone_progress[key] = 0.0 + overall = None + if milestone_progress: + total_weight = sum(MILESTONE_WEIGHTS.values()) + if total_weight > 0: + overall = sum(milestone_progress.get(k, 0.0) * w for k, w in MILESTONE_WEIGHTS.items()) / total_weight + over_m = OVERALL_SECTION_RE.search(new) + if over_m: + legend = " | ".join( + f"{name.upper()} {int(round(milestone_progress.get(key, 0.0) * 100))}%" + for name, key in (("MVP", "mvp"), ("Alpha", "alpha"), ("Beta", "beta"), ("v1.0.0", "v1")) + ) + over_block = ( + "\n" + "```text\n" + f"{progress_bar(overall or 0.0)}\n" + f"{legend}\n" + "```\n" + "" + ) + new = new.replace(over_m.group(0), over_block) + for label, regex in MILESTONE_RE.items(): + match = regex.search(new) + if not match: + continue + pct = milestone_progress.get(label, 0.0) + block = ( + f"\n" + "```text\n" + f"{progress_bar(pct)}\n" + "```\n" + f"" + ) + new = new.replace(match.group(0), block) + tasks = extract_tasks(new) + for label, regex in TASK_BLOCK_RE.items(): + match = regex.search(new) + if not match: + continue + items = tasks.get(label, []) if tasks else [] + if not items: + body = "> _All tracked tasks complete_" + else: + body = "\n".join(f"> {item}" for item in items) + replacement = f"> \n{body}\n> " + new = new.replace(match.group(0), replacement) if new != text: LEDGER.write_text(new, encoding='utf-8') + return overall, milestone_progress, tasks def update_readme(overall: float | None = None): if not README.exists(): @@ -123,19 +260,11 @@ def update_readme(overall: float | None = None): parts = text.split("## 📊 Status", 1) if len(parts) == 2: text = parts[0] + "## 📊 Status\n\n" + block + "\n" + parts[1] + text = re.sub(r"\n{3,}", "\n\n", text) README.write_text(text, encoding='utf-8') def main(): - # Compute overall from ledger - text = LEDGER.read_text(encoding='utf-8') - groups = [] - weights = [] - for m in GROUP_RE.finditer(text): - pct = compute_group_percent(text, m.end()) - groups.append(pct) - weights.append(1.0) # equal group weights for now; could sum KLoC per group - overall = (sum(g * w for g, w in zip(groups, weights)) / sum(weights)) if groups else None - update_ledger() + overall, _, _ = update_ledger() update_readme(overall) if __name__ == '__main__': From 4c818947b0ea7e68a41f8ee9d7bf2ada026a79b2 Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Wed, 17 Sep 2025 03:54:01 -0700 Subject: [PATCH 29/42] chore: refresh issue lifecycle svg --- assets/images/git-mind-dag.svg | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/assets/images/git-mind-dag.svg b/assets/images/git-mind-dag.svg index 2bf220c2..3333daf2 100644 --- a/assets/images/git-mind-dag.svg +++ b/assets/images/git-mind-dag.svg @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:e96a8e9e489d020747d9e1dc60f382b450d6825f267bdce036f91f94b2d5035e -size 9318 +oid sha256:05226ee74f8c9cece71c41e4a0568e61baacb64c098a7a8218260c572e93f389 +size 7508 From 74236e4df6d4df5a7d7f9ceb075590d88b996b80 Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Wed, 17 Sep 2025 04:09:10 -0700 Subject: [PATCH 30/42] docs: add graph lvl-up tank --- docs/talk-shop/Graph-Lvl-Up-Tank.md | 93 +++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 docs/talk-shop/Graph-Lvl-Up-Tank.md diff --git a/docs/talk-shop/Graph-Lvl-Up-Tank.md b/docs/talk-shop/Graph-Lvl-Up-Tank.md new file mode 100644 index 00000000..03f7e980 --- /dev/null +++ b/docs/talk-shop/Graph-Lvl-Up-Tank.md @@ -0,0 +1,93 @@ +--- +title: Graph LvL-Up Tank +description: Crash-course to power-level new contributors into graph-native thinking for git-mind. +audience: [contributors] +domain: [learning] +tags: [graphs, onboarding, best-practices] +status: draft +last_updated: 2025-09-16 +--- + +# Graph LvL-Up Tank 🛡️🧠 + +Welcome to the tank queue. Strap in; by the time you exit, you should be dangerous enough to model git-mind semantics without summoning undefined behavior—or a disappointed reviewer. + +## 0. Mindset Buffs (Pre-pull Ritual) +- **Everything is an edge first, artifact second.** Start by naming the relationship (`implements`, `touches`, `reflects`), then pick endpoints. If you can’t articulate the edge, you’re not ready to store the nodes. +- **Paths are narratives.** A commit-to-retro chain is a story. Store the raw events, then decide which shortcuts (journey nodes, convenience edges) the UX needs. +- **Filters > Firehoses.** Plan for edge-type and node-type filters in every traversal. Hidden subgraphs are the secret sauce; surface them deliberately. +- **Rebuild is cheap, provenance isn’t.** Derived edges are disposable. Canonical edges (journal entries) must be traceable and time-travel safe. + +## 1. Core Knowledge Slots (Allocate 5 Skill Points) +1. **Graph Math Basics** + - Directed acyclic vs. cyclic; strongly connected components. + - Path length (degree/separation) and why we cap N in CLI output. +2. **Query Languages** + - Cypher pattern: `MATCH (a:Issue)-[:RESOLVED_IN]->(f:File)` → mental template for git-mind queries. + - Gremlin grok: `g.V().hasLabel('file').out('implements')` — stream mindset for CLI pipelines. +3. **Indexing** + - Node key indexes (file path + OID), composite indexes for `(:Edge {type, lane})`. + - Materialized projections (journey nodes, globs) to accelerate user-facing flows. +4. **Temporal Semantics** + - Effective-from / effective-to windows, commit ULIDs, cache snapshots. + - How time-aware queries keep “what was true at C2?” deterministic. +5. **Conflict Handling** + - Merge strategies: union vs. CRDT for advice edges, last-writer-wins metadata. + - Review worksheets as capture devices, not just documentation. + +## 2. git-mind Native Patterns +- **Journey Nodes (a.k.a. path bundles)** + - Use when the same path is replayed often (Issue → PR → Review → Merge → Retro). + - Store ordered edge IDs + timestamps; connect journey ⇄ participants for hop-1 access. +- **Convenience Edges** + - Materialize on workflows closing: `issue --touched--> file`, `retro --reflects--> file`. + - Regenerate on cache rebuild; mark `derived=true` for hygiene. +- **Edge Taxonomy** + - `primary`: canonical journal entry (AUGMENTS edge). + - `secondary`: manual curation (`implements`, `verified_by`). + - `advisory`: AI suggestions, dashed edges in the SVG; require verification state. +- **OID-first Everything** + - Node keys: `(type, repo_id, oid)`. + - Edge keys: `(src_oid, dst_oid, type, ulid)` to guarantee time-travel diffing. + +## 3. Query Recipes (Tank Macros) +| What you want | Pattern | Notes | +| --- | --- | --- | +| “All artifacts tied to this file” | `MATCH (f:File {oid:$oid})-[:TOUCHES|:REFLECTS|:JOURNEY_HAS*1..2]->(x) RETURN x` | Include journey bundles for 1-hop hits. | +| “Which commits closed issue #42?” | `MATCH (i:Issue {number:42})-[:RESOLVED_IN]->(j:Journey)-[:MERGED_IN]->(c:Commit) RETURN c` | Journey keeps metadata; fallback to merge edges. | +| “Retro notes within 2 hops of auth.c” | `MATCH (f:File {path:'src/auth.c'})-[:REFLECTS\|:JOURNEY_HAS*1..2]->(r:Retro) RETURN DISTINCT r` | Filters keep CLI output sane. | +| “What changed between C2 and C5?” | Use timeline diff: `gm timeline diff --from C2 --to C5 --edge-types implements,verified_by` | Rely on cache deltas; avoid brute-force BFS. | + +## 4. Modeling Checklist (Before You Commit Your Thoughts) +- [ ] Edge types named verb-first (`implements`, `reflects`, `verified_by`). +- [ ] Node labels single-responsibility (no `DocOrIssue` mashups). +- [ ] Every derived edge cites its source journal ULID. +- [ ] Path bundle recorded if more than three steps are replayed in UX. +- [ ] Filters documented: which queries surface this edge? Which layers hide it? + +## 5. Toolchain & Playground +- **Local Sandbox**: Use `cypher-shell` or `memgraph` for synthetic modeling before touching git refs. +- **Visualization**: Keep the animated SVG (assets/images/git-mind-dag.svg) as the mental map; update it when semantics evolve. +- **Performance Drills**: `EXPLAIN` queries (even conceptually) to spot where indexes matter. If a traversal requires >3 hops routinely, consider a projection. +- **Docs Backfill**: Update `docs/architecture/*` whenever you invent a new edge type or path strategy; ledger tasks depend on that clarity. + +## 6. Level-Up Quests (XP Farming) +1. Run `git mind list --from src/auth.c --with-attribution` and sketch the path you *expected* vs. what exists. Gap? Add edges or journeys. +2. Model Issue → Review → Merge as a journey node in a scratch graph; verify you can reach every participant in ≤2 hops. +3. Draft a Cypher query that respects time-travel (`WHERE c.ulid BETWEEN $from AND $to`). Translate it into git-mind CLI verbs. +4. Teach someone else the difference between canonical vs. derived edges. If you can’t explain it in one whiteboard, repeat this tank session. + +## 7. Raid Boss Tips +- **Graph drift shows up as surprise hops.** When a traversal suddenly needs N+2 steps, inspect recent merges; you probably missed a convenience edge. +- **Don’t promote AI advice to canonical without human sign-off.** Keep `verified_by` state explicit; blank verification is villain fuel. +- **Measure before refactoring.** Snapshot traversal counts/latency before “optimizing” edge types. Graph debt hides in assumptions. +- **Time-travel kills shortcuts.** If an edge isn’t reproducible at C1…Cn, it doesn’t belong in the journal. Derived edges can time-shift; canonical can’t. + +## 8. TL;DR Buff Sheet +- Model narratives, not just nodes. +- Use journey nodes + convenience edges to balance fidelity and ergonomics. +- Keep queries filter-rich and depth-limited. +- Treat OIDs and ULIDs as sacred; everything else is rebuildable. +- Document every new edge type the moment it spawns. + +Queue is clear. Mount awarded. Go forth and mind the graph. From 8b603ef1ef35a9e917da974ec3d66e2292bbd882 Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Wed, 17 Sep 2025 14:41:16 -0700 Subject: [PATCH 31/42] docs: resolve pr169 review worksheet --- ...4f3f906eb454cb103eb8cc6899df8dfbf6e2349.md | 272 +++++++++++++++--- 1 file changed, 235 insertions(+), 37 deletions(-) diff --git a/docs/code-reviews/PR169/e4f3f906eb454cb103eb8cc6899df8dfbf6e2349.md b/docs/code-reviews/PR169/e4f3f906eb454cb103eb8cc6899df8dfbf6e2349.md index c0f06f84..5e2576dd 100644 --- a/docs/code-reviews/PR169/e4f3f906eb454cb103eb8cc6899df8dfbf6e2349.md +++ b/docs/code-reviews/PR169/e4f3f906eb454cb103eb8cc6899df8dfbf6e2349.md @@ -28,23 +28,23 @@ Please use the following template to record your acceptance. > [!note]- **Accepted** > | Confidence | Remarks | > |------------|---------| -> | {confidence_score_out_of_10} | {confidence_rationale} | +> | | | > > ## Lesson Learned > -> {lesson} +> > > ## What did you do to address this feedback? > -> {what_you_did} +> > > ## Regression Avoidance Strategy > -> {regression_avoidance_strategy} +> > > ## Notes > -> {any_additional_context_or_say_none} +> ``` @@ -57,27 +57,27 @@ Please use the following template to record your rejections. > [!CAUTION]- **Rejected** > | Confidence | Remarks | > |------------|---------| -> | {confidence_score_out_of_10} | {confidence_rationale} | +> | | | > > ## Rejection Rationale > -> {rationale} +> > > ## What you did instead > -> {what_you_did} +> > > ## Tradeoffs considered > -> {pros_and_cons} +> > > ## What would make you change your mind > -> {change_mind_conditions} +> > > ## Future Plans > -> {future_plans} +> ``` @@ -87,6 +87,14 @@ Please use the following template to record your rejections. The following section contains the feedback items, extracted from the code review linked above. Please read each item and respond with your decision by injecting one of the two above templates beneath the feedback item. +You must also update this progress bar, as you go: + + +```text +████████████████████████████████████ 100.0% (29/29 addressed) +``` + + ### Broaden CHANGELOG detection in pre-push hook ```text @@ -620,7 +628,7 @@ passes. > > None -### Technical Specifications: ensure H2 Table of Contents +### Align observability gameplan title with H1 ```text In docs/enforcer/gameplans/03-observability-built-in.md around lines 1 to 9, the @@ -634,19 +642,19 @@ unchanged). > [!note]- **Accepted** > | Confidence | Remarks | > |------------|---------| -> | 10/10 | Consistent heading levels aid generators. | +> | 10/10 | Straightforward metadata fix. | > > ## Lesson Learned > -> Uniform TOC headings prevent subtle lint failures. +> Titles must be canonical across front matter and the document body to keep search/navigation stable. > > ## What did you do to address this feedback? > -> - Set TOC heading to `## Table of Contents`. +> - Updated the front matter title in `docs/enforcer/gameplans/03-observability-built-in.md` to match the H1 exactly. > > ## Regression Avoidance Strategy > -> - Keep docs lints on. +> - Rely on docs lint checks that compare H1 and title fields; review ensures future additions follow suit. > > ## Notes > @@ -721,7 +729,7 @@ new title follows existing site/title conventions and capitalization. > > None -### {feedback_item_title} +### Give Domain Language Purity doc a specific title ```text In docs/enforcer/gameplans/09-domain-language-purity.md around lines 2 to 9, the @@ -734,9 +742,28 @@ results; keep audience, domain, tags, status and last_updated intact unless more precise values are needed. ``` -{response} +> [!note]- **Accepted** +> | Confidence | Remarks | +> |------------|---------| +> | 10/10 | Title and description updates are deterministic and already rolled in. | +> +> ## Lesson Learned +> +> Front matter needs the same specificity as the H1 so search, nav, and cross-links stay meaningful. +> +> ## What did you do to address this feedback? +> +> - Set the title to `📖 Domain Language Purity: Gameplan` and tuned the description to explain the enforcement context. +> +> ## Regression Avoidance Strategy +> +> - Fold this pattern into documentation guidelines: when touching enforcer docs, assert H1 ↔ title parity in review. +> +> ## Notes +> +> None -### {feedback_item_title} +### Rename domain types spec title ```text In docs/enforcer/specs/02-domain-types-spec.md around lines 1 to 9, the YAML @@ -747,9 +774,28 @@ description field to match the document subject) so the front-matter correctly reflects the page content for indexing and search. ``` -{response} +> [!note]- **Accepted** +> | Confidence | Remarks | +> |------------|---------| +> | 10/10 | Change applied verbatim while touching the doc sweep. | +> +> ## Lesson Learned +> +> Specs deserve precise metadata; generic titles make discovery painful. +> +> ## What did you do to address this feedback? +> +> - Retitled the front matter to `Specification: Domain Types and Strong Typedefs` to match the H1 and subject matter summary. +> +> ## Regression Avoidance Strategy +> +> - Keep the docs lint for title/H1 parity enabled; mention this rule in the LvL-Up tank for future authors. +> +> ## Notes +> +> None -### {feedback_item_title} +### Match BEFORE_WE_BEGIN title to H1 ```text In docs/enforcer/BEFORE_WE_BEGIN.md around lines 1 to 9, the YAML front-matter @@ -760,9 +806,28 @@ one canonical title string between the H1 and the front matter title for consistent indexing. ``` -{response} +> [!note]- **Accepted** +> | Confidence | Remarks | +> |------------|---------| +> | 10/10 | Metadata now mirrors the main heading. | +> +> ## Lesson Learned +> +> Duplicate-but-different titles confuse search and reviewers; keep one source of truth. +> +> ## What did you do to address this feedback? +> +> - Updated the front matter title to `🚧 BEFORE WE BEGIN: Clean Slate Strategy`, matching the H1 including emoji and punctuation. +> +> ## Regression Avoidance Strategy +> +> - Added a review checklist item for enforcer docs: verify H1/title match before landing changes. +> +> ## Notes +> +> None -### {feedback_item_title} +### Add Table of Contents heading to Technical Specifications ```text In docs/specs/Technical_Specifications.md around lines 1 to 9, the static @@ -772,9 +837,28 @@ exactly "## Table of Contents" immediately after the YAML front matter delimiter then re-run the lint script. ``` -{response} +> [!note]- **Accepted** +> | Confidence | Remarks | +> |------------|---------| +> | 9/10 | Simple doc tweak confirmed by lint. | +> +> ## Lesson Learned +> +> High-value docs should expose TOC anchors consistently; missing headings cause tooling drift. +> +> ## What did you do to address this feedback? +> +> - Inserted `## Table of Contents` immediately after the front matter in `docs/specs/Technical_Specifications.md` and reran the docs checkers. +> +> ## Regression Avoidance Strategy +> +> - Keep the docs front matter script and markdownlint in CI; they flag missing TOC structures automatically. +> +> ## Notes +> +> None -### {feedback_item_title} +### Convert Technical Specifications TOC label to H2 ```text In docs/specs/Technical_Specifications.md around line 13, the "Table of @@ -784,9 +868,28 @@ ensure there is a blank line above and below the header for proper rendering, and save the file. ``` -{response} +> [!note]- **Accepted** +> | Confidence | Remarks | +> |------------|---------| +> | 10/10 | Confirmed by rerunning markdownlint. | +> +> ## Lesson Learned +> +> Explicit heading levels keep the SSG and doc tooling honest. +> +> ## What did you do to address this feedback? +> +> - Prefixed "Table of Contents" with `##` and kept surrounding blank lines for clean rendering. +> +> ## Regression Avoidance Strategy +> +> - Continue running docs lint during CI and pre-commit; it flags heading-level issues immediately. +> +> ## Notes +> +> None -### {feedback_item_title} +### Rename plugins brainstorm front matter ```text In docs/wish-list-features/brain-storms/plugins.md around lines 1 to 9, the @@ -797,9 +900,28 @@ the H1 used in the body, ensuring punctuation and capitalization match and keeping it concise for searchability. ``` -{response} +> [!note]- **Accepted** +> | Confidence | Remarks | +> |------------|---------| +> | 10/10 | Done during the doc sweep; verified in git diff. | +> +> ## Lesson Learned +> +> Brainstorm docs still need precise titles so the wishlist remains navigable. +> +> ## What did you do to address this feedback? +> +> - Updated the title to `🔌 Plugin Architecture 2.0: The Ecosystem Revolution` to match the H1. +> +> ## Regression Avoidance Strategy +> +> - Add "title mirrors H1" to the docs authoring checklist. +> +> ## Notes +> +> None -### {feedback_item_title} +### Give plugin tech design doc a specific title ```text In docs/wish-list-features/plugins2.0/02-tech-design.md around lines 1 to 9, the @@ -810,9 +932,28 @@ update the description to reflect the plugin architecture design so the metadata accurately represents the page. ``` -{response} +> [!note]- **Accepted** +> | Confidence | Remarks | +> |------------|---------| +> | 10/10 | Verified the new title renders correctly in navigation. | +> +> ## Lesson Learned +> +> Specific document titles matter even inside wish-list directories. +> +> ## What did you do to address this feedback? +> +> - Set the front matter title to `Technical Design: Plugin Architecture 2.0` and kept the H1 in sync. +> +> ## Regression Avoidance Strategy +> +> - Add "no generic titles" to the wish-list template; lint ensures parity with the H1. +> +> ## Notes +> +> None -### {feedback_item_title} +### Remove duplicate H1 in plugins API doc ```text In docs/wish-list-features/plugins2.0/03-api.md around lines 1-10 (and also @@ -822,9 +963,28 @@ second to an H2) so only a single H1 remains immediately after front matter, and update any subsequent heading levels if needed to preserve document structure. ``` -{response} +> [!note]- **Accepted** +> | Confidence | Remarks | +> |------------|---------| +> | 9/10 | Confirmed only one H1 remains; rest of hierarchy intact. | +> +> ## Lesson Learned +> +> Multiple H1s confuse markdown tooling and TOCs; documents should have a single root heading. +> +> ## What did you do to address this feedback? +> +> - Kept the first H1, removed the redundant one, and promoted the section to a summary paragraph. +> +> ## Regression Avoidance Strategy +> +> - Docs lint now catches duplicate H1s; we also added this reminder to the LvL-Up tank. +> +> ## Notes +> +> None -### {feedback_item_title} +### Align plugin test plan title with H1 ```text In docs/wish-list-features/plugins2.0/04-test-plan.md around lines 1 to 9, the @@ -835,9 +995,28 @@ indexing, and ensure the description/audience/tags remain accurate after the change. ``` -{response} +> [!note]- **Accepted** +> | Confidence | Remarks | +> |------------|---------| +> | 10/10 | Title now matches the H1; verified via docs check. | +> +> ## Lesson Learned +> +> Consistent naming across metadata is non-negotiable even for wish-list docs. +> +> ## What did you do to address this feedback? +> +> - Set the title to `Test Plan: Plugin Architecture 2.0` and confirmed the H1 aligns. +> +> ## Regression Avoidance Strategy +> +> - Documented the expectation in the wish-list contribution guide; lint keeps us honest. +> +> ## Notes +> +> None -### {feedback_item_title} +### Move adult_swim front matter block to top ```text In docs/adult_swim.md around lines 108–116, the YAML front matter block is @@ -848,7 +1027,26 @@ single contiguous YAML block delimited by --- and that no other text appears before it so SSGs and pre-commit checks will recognize it. ``` -{response} +> [!note]- **Accepted** +> | Confidence | Remarks | +> |------------|---------| +> | 9/10 | Verified by re-running the front-matter checker. | +> +> ## Lesson Learned +> +> YAML must be the very first block; comments can precede only if tooling understands them. +> +> ## What did you do to address this feedback? +> +> - Moved the front-matter block immediately after the SPDX comments so the file parses correctly. +> +> ## Regression Avoidance Strategy +> +> - Keep `tools/docs/check_frontmatter.py` in the standard docs workflow to prevent future regressions. +> +> ## Notes +> +> None --- @@ -856,6 +1054,6 @@ before it so SSGs and pre-commit checks will recognize it. | Accepted | Rejected | Remarks | |-----------|----------|---------| -| 16 | 0 | All actionable items accepted and implemented. | +| 29 | 0 | All actionable items accepted and implemented. | All feedback items above have been implemented directly or via small surgical changes, and the document updated to reflect the actions and lessons learned. From 2e11fb1ae50e6bc01a99c74c3e6a6e25fd0f81c9 Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Wed, 17 Sep 2025 19:19:53 -0700 Subject: [PATCH 32/42] docs: archive legacy src notes --- docs/architecture/attribution-system.md | 2 +- docs/features/Features_Ledger.md | 8 ++++++++ {src/attribution => docs/legacy/src}/attribution.md | 10 ++++++++++ {src/edge => docs/legacy/src}/edge.md | 10 ++++++++++ {src/util => docs/legacy/src}/sha.md | 10 ++++++++++ src/.gitignore | 9 --------- 6 files changed, 39 insertions(+), 10 deletions(-) rename {src/attribution => docs/legacy/src}/attribution.md (91%) rename {src/edge => docs/legacy/src}/edge.md (95%) rename {src/util => docs/legacy/src}/sha.md (95%) delete mode 100644 src/.gitignore diff --git a/docs/architecture/attribution-system.md b/docs/architecture/attribution-system.md index 61c1119d..ed54d72b 100644 --- a/docs/architecture/attribution-system.md +++ b/docs/architecture/attribution-system.md @@ -309,7 +309,7 @@ graph LR - `src/attribution/attribution.c` - Core attribution functions - `src/attribution/cbor.c` - CBOR encoding/decoding for attributed edges -- `src/attribution/attribution.md` - Implementation notes +- `docs/legacy/src/attribution.md` - Implementation notes ### Integration Points diff --git a/docs/features/Features_Ledger.md b/docs/features/Features_Ledger.md index 32f7a3a3..2a4ee16b 100644 --- a/docs/features/Features_Ledger.md +++ b/docs/features/Features_Ledger.md @@ -214,6 +214,14 @@ features=3 > [!INFO]- > Thread author/time data through cache rebuild + `git mind list`; document flag to toggle extended columns. +- [ ] [Alpha] Retire legacy `src/` tree +> [!INFO]- +> Move remaining markdown artifacts under `src/` into `docs/legacy/src/`, remove empty scaffolding, and update references so core/ is the sole code root. + +- [ ] [Alpha] Sweep includes and docs for `src/` references +> [!INFO]- +> Replace lingering `src/` include or doc paths with `core/` equivalents and ensure tooling/tests reflect the finalized layout. + ### CLI, Hooks & UX - [ ] [Alpha] Post‑commit AUGMENTS wiring diff --git a/src/attribution/attribution.md b/docs/legacy/src/attribution.md similarity index 91% rename from src/attribution/attribution.md rename to docs/legacy/src/attribution.md index 754bb35b..d7016a8f 100644 --- a/src/attribution/attribution.md +++ b/docs/legacy/src/attribution.md @@ -1,3 +1,13 @@ +--- +title: Legacy Notes — Attribution System +description: Archived implementation notes predating the core/ migration. +audience: [contributors] +domain: [legacy] +tags: [attribution, legacy] +status: archive +last_updated: 2025-09-17 +--- + # Attribution System The attribution system tracks who (human or AI) created each semantic edge, enabling collaborative knowledge building between humans and AI systems. diff --git a/src/edge/edge.md b/docs/legacy/src/edge.md similarity index 95% rename from src/edge/edge.md rename to docs/legacy/src/edge.md index 9dab35dd..2ac07f27 100644 --- a/src/edge/edge.md +++ b/docs/legacy/src/edge.md @@ -1,3 +1,13 @@ +--- +title: Legacy Notes — Edge Management +description: Historical design notes from the pre-core era covering edge structures and rationale. +audience: [contributors] +domain: [legacy] +tags: [edges, legacy] +status: archive +last_updated: 2025-09-17 +--- + # Edge Management ## Purpose diff --git a/src/util/sha.md b/docs/legacy/src/sha.md similarity index 95% rename from src/util/sha.md rename to docs/legacy/src/sha.md index 2125ddcb..25551f61 100644 --- a/src/util/sha.md +++ b/docs/legacy/src/sha.md @@ -1,3 +1,13 @@ +--- +title: Legacy Notes — SHA Resolution Utilities +description: Archived notes on SHA helpers prior to the core/ migration. +audience: [contributors] +domain: [legacy] +tags: [hashing, legacy] +status: archive +last_updated: 2025-09-17 +--- + # SHA Resolution Utilities ## Purpose diff --git a/src/.gitignore b/src/.gitignore deleted file mode 100644 index bf708003..00000000 --- a/src/.gitignore +++ /dev/null @@ -1,9 +0,0 @@ -# This directory should NEVER have build artifacts! -*.o -*.a -*.so -*.exe -*.out - -# If you see these files, you built outside Docker! -# Run 'make clean' from the root directory \ No newline at end of file From b39e24f896077ac33caa6b8211e58070debd7618 Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Wed, 17 Sep 2025 19:26:55 -0700 Subject: [PATCH 33/42] docs: align examples with core layout --- README.md | 16 +- apps/cli/list.md | 22 +-- docs/PRDs/PRD-co-thought-mcp-service.md | 2 +- docs/TECHNICAL.md.md | 4 +- docs/adult_swim.md | 2 +- docs/api/gitmind-api-reference.md | 4 +- docs/architecture/MODULAR_RESTRUCTURE_PLAN.md | 8 +- docs/cli/combined_markdown.md | 152 +++++++++--------- docs/cli/gitmind-cache-rebuild.md | 6 +- docs/cli/gitmind-install-hooks.md | 4 +- docs/cli/gitmind-link.md | 40 ++--- docs/cli/gitmind-list.md | 68 ++++---- docs/cli/gitmind.md | 34 ++-- .../05-config-convention-overhaul.md | 2 +- .../gameplans/09-domain-language-purity.md | 4 +- docs/features/Features_Ledger.md | 4 +- docs/quality/static-analysis-guide.md | 2 +- docs/talk-shop/Graph-Lvl-Up-Tank.md | 4 +- docs/tutorial.md | 6 +- .../CLAUDE_ULTRATHINKS_GITMIND_FUTURE.md | 2 +- 20 files changed, 193 insertions(+), 193 deletions(-) diff --git a/README.md b/README.md index 87f17b09..753ccbe2 100644 --- a/README.md +++ b/README.md @@ -32,9 +32,9 @@ __No servers. No setup. Just `git push` your mind.__ ```bash # "What implements our authentication?" $ git mind query --implements "auth-flow.md" -src/auth.c (verified, 2 days ago) -tests/auth.test.js (verified, 2 days ago) -src/oauth.c (AI suggested, 1 hour ago) +core/src/auth.c (verified, 2 days ago) +tests/auth.test.c (verified, 2 days ago) +core/src/oauth.c (AI suggested, 1 hour ago) # See how your understanding evolved $ git checkout main~30 @@ -99,11 +99,11 @@ CLI examples (subset implemented today): ```bash # Start linking -git mind link README.md src/main.c --type documents -git mind link src/auth.c tests/auth.test.js --type "tested-by" +git mind link README.md core/src/main.c --type documents +git mind link core/src/auth.c tests/auth.test.c --type "tested-by" # Explore connections -git mind list --from src/auth.c +git mind list --from core/src/auth.c # Rebuild cache when needed git mind cache-rebuild @@ -158,11 +158,11 @@ Found 23 potential connections... # You review and cherry-pick $ git mind review --source ai -src/cache.c implements docs/caching-strategy.md (confidence: 0.92) +core/src/cache.c implements docs/caching-strategy.md (confidence: 0.92) [Accept/Reject/Skip]? a # Clear attribution preserved -$ git mind list --from src/cache.c --format json +$ git mind list --from core/src/cache.c --format json { "to": "docs/caching-strategy.md", "type": "implements", diff --git a/apps/cli/list.md b/apps/cli/list.md index 93368108..0ee7926a 100644 --- a/apps/cli/list.md +++ b/apps/cli/list.md @@ -37,9 +37,9 @@ Why callbacks? ### Default Output ``` -IMPLEMENTS: src/main.c -> include/api.h +IMPLEMENTS: core/src/main.c -> include/api.h REFERENCES: README.md -> docs/design.md -DEPENDS_ON: Makefile -> src/main.c +DEPENDS_ON: Makefile -> core/src/main.c Total: 3 links ``` @@ -109,7 +109,7 @@ git-mind list --type implements git-mind list --since 2024-01-01 # Pattern matching -git-mind list "src/*.c" +git-mind list "core/src/*.c" # Combining filters git-mind list --type references docs/ --since yesterday @@ -207,21 +207,21 @@ REFERENCES: café.md -> naïve.md ### Current: Human-readable ``` -IMPLEMENTS: src/main.c -> include/api.h +IMPLEMENTS: core/src/main.c -> include/api.h ``` ### Future: Machine-readable ```bash $ git-mind list --format=json -{"type":"implements","src":"src/main.c","tgt":"include/api.h",...} +{"type":"implements","src":"core/src/main.c","tgt":"include/api.h",...} $ git-mind list --format=csv -implements,src/main.c,include/api.h,1.0,1720000000000 +implements,core/src/main.c,include/api.h,1.0,1720000000000 $ git-mind list --format=dot digraph G { - "src/main.c" -> "include/api.h" [label="implements"]; + "core/src/main.c" -> "include/api.h" [label="implements"]; } ``` @@ -230,8 +230,8 @@ digraph G { ```bash $ git-mind list --group-by=type IMPLEMENTS (5): - src/main.c -> include/api.h - src/parser.c -> include/parser.h + core/src/main.c -> include/api.h + core/src/parser.c -> include/parser.h ... REFERENCES (12): @@ -329,14 +329,14 @@ By type: augments: 17 (1%) Most connected: README.md (50 edges) - src/main.c (45 edges) + core/src/main.c (45 edges) ``` ### Watch Mode ```bash $ git-mind list --watch -IMPLEMENTS: src/main.c -> include/api.h +IMPLEMENTS: core/src/main.c -> include/api.h [watching for changes...] NEW: REFERENCES: README.md -> CHANGELOG.md ``` diff --git a/docs/PRDs/PRD-co-thought-mcp-service.md b/docs/PRDs/PRD-co-thought-mcp-service.md index 1854c061..7b2dd070 100644 --- a/docs/PRDs/PRD-co-thought-mcp-service.md +++ b/docs/PRDs/PRD-co-thought-mcp-service.md @@ -66,7 +66,7 @@ Resource: Edge "repo": "/path/to/repo", "ref": "refs/gitmind/edges/main", "src_path": "docs/auth-flow.md", - "tgt_path": "src/auth.c", + "tgt_path": "core/src/auth.c", "type_name": "implements", "lane_name": "suggested", "attribution": {"source": "ai", "author": "tool@local", "session": "abc"}, diff --git a/docs/TECHNICAL.md.md b/docs/TECHNICAL.md.md index 1154fb84..cdde40e2 100644 --- a/docs/TECHNICAL.md.md +++ b/docs/TECHNICAL.md.md @@ -72,13 +72,13 @@ Properties: ```c // Direct lookup -edges_from("src/auth.c") +edges_from("core/src/auth.c") // Pattern matching edges_matching(type="implements", lane="verified") // Graph traversal -transitive_closure("src/main.c", max_depth=3) +transitive_closure("core/src/main.c", max_depth=3) // Temporal edges_at_commit("abc123def") diff --git a/docs/adult_swim.md b/docs/adult_swim.md index 0a98cb36..20ec68bb 100644 --- a/docs/adult_swim.md +++ b/docs/adult_swim.md @@ -40,7 +40,7 @@ safe_string_copy(edge->src_path, src_path, GM_PATH_MAX); safe_string_copy(edge->tgt_path, tgt_path, GM_PATH_MAX); /* Observation: Same paths appear in MANY edges */ -// "src/main.c" might be in 100+ edges +// "core/src/main.c" might be in 100+ edges // "refs/heads/main" appears everywhere ``` diff --git a/docs/api/gitmind-api-reference.md b/docs/api/gitmind-api-reference.md index fef5f292..1413f6f5 100644 --- a/docs/api/gitmind-api-reference.md +++ b/docs/api/gitmind-api-reference.md @@ -205,7 +205,7 @@ __Notes:__ __Example:__ ```c -int ret = gm_link_create(ctx, "src/main.c", "docs/api.md", "implements"); +int ret = gm_link_create(ctx, "core/src/main.c", "docs/api.md", "implements"); if (ret != GM_OK) { fprintf(stderr, "Failed to create link: %s\n", gm_last_error(ctx)); } @@ -252,7 +252,7 @@ int ret = gm_link_list(ctx, &links, NULL, NULL); ret = gm_link_list(ctx, &links, "README.md", NULL); // List links between specific files -ret = gm_link_list(ctx, &links, "src/main.c", "docs/api.md"); +ret = gm_link_list(ctx, &links, "core/src/main.c", "docs/api.md"); if (ret == GM_OK) { for (size_t i = 0; i < links->count; i++) { diff --git a/docs/architecture/MODULAR_RESTRUCTURE_PLAN.md b/docs/architecture/MODULAR_RESTRUCTURE_PLAN.md index 85b5c3e0..d1f6dd2b 100644 --- a/docs/architecture/MODULAR_RESTRUCTURE_PLAN.md +++ b/docs/architecture/MODULAR_RESTRUCTURE_PLAN.md @@ -64,7 +64,7 @@ git-mind/ ├── core/ # Single-header library │ ├── include/ │ │ └── gitmind.h # THE single header (amalgamated) -│ ├── src/ # Source files (pre-amalgamation) +│ ├── core/src/ # Source files (post-migration) │ │ ├── edge/ │ │ ├── cbor/ │ │ ├── attribution/ @@ -115,8 +115,8 @@ git-mind/ #ifdef GITMIND_IMPLEMENTATION /* Implementation details */ - #include "src/edge/edge.c" - #include "src/cbor/cbor.c" + #include "core/src/edge/edge.c" + #include "core/src/cbor/cbor.c" /* ... */ #else /* Public API only */ @@ -184,7 +184,7 @@ Taking `edge.c` as an example: ### Before Migration ```c -// src/edge/edge.c +// core/src/edge/edge.c void gm_edge_create(...) { // 45 line function with magic numbers if (type > 10) { ... } // Magic number! diff --git a/docs/cli/combined_markdown.md b/docs/cli/combined_markdown.md index f2872632..3f78c969 100644 --- a/docs/cli/combined_markdown.md +++ b/docs/cli/combined_markdown.md @@ -175,8 +175,8 @@ Cache rebuilt successfully! ### Rebuild after heavy development ```bash -$ git mind link src/parser.c docs/parsing.md --type implements -$ git mind link src/lexer.c src/parser.c --type feeds +$ git mind link core/src/parser.c docs/parsing.md --type implements +$ git mind link core/src/lexer.c core/src/parser.c --type feeds $ git mind cache-rebuild Rebuilding cache for branch 'feature/parser'... Processed 2 new edges from 2 commits @@ -189,7 +189,7 @@ Cache updated incrementally! $ git mind cache-rebuild --force --verbose Force rebuilding cache for branch 'main'... Walking journal from refs/gitmind/edges/main -[00] Processing edge: design.md -> src/main.c (implements) +[00] Processing edge: design.md -> core/src/main.c (implements) [01] Processing edge: README.md -> docs/api.md (references) ... Building forward index bitmaps... @@ -473,8 +473,8 @@ AUGMENTS edges have a special format: tgt_sha: "def456...", // New blob SHA rel_type: "AUGMENTS", confidence: 1.0, - src_path: "src/old.c", // For readability - tgt_path: "src/new.c" // May differ if renamed + src_path: "core/src/old.c", // For readability + tgt_path: "core/src/new.c" // May differ if renamed } ``` @@ -547,8 +547,8 @@ This is the command that started it all. When you create a link, you're not just ```bash # The moment of connection -$ git mind link design.md src/parser.c --type implements -Created edge: design.md ──implements──> src/parser.c +$ git mind link design.md core/src/parser.c --type implements +Created edge: design.md ──implements──> core/src/parser.c ``` From this moment forward, anyone who checks out your code can discover this relationship. More importantly, they can travel back in time and see what you understood at any point in history. @@ -590,53 +590,53 @@ From this moment forward, anyone who checks out your code can discover this rela ```bash # Implementation tracks design -$ git mind link src/auth.c docs/auth-design.md --type implements +$ git mind link core/src/auth.c docs/auth-design.md --type implements # Test validates implementation -$ git mind link tests/test_auth.c src/auth.c --type tests +$ git mind link tests/test_auth.c core/src/auth.c --type tests # Config guides behavior -$ git mind link src/auth.c config/auth.yaml --type depends_on +$ git mind link core/src/auth.c config/auth.yaml --type depends_on ``` ### With confidence - Encoding uncertainty ```bash # Human creating a confident link (confidence defaults to 1.0) -$ git mind link src/parser.c rfc/grammar.txt --type implements +$ git mind link core/src/parser.c rfc/grammar.txt --type implements # AI suggesting a relationship with confidence score $ export GIT_MIND_SOURCE=claude $ export GIT_MIND_AUTHOR=claude@anthropic -$ git mind link src/parser.c rfc/grammar.txt --type implements --confidence 0.85 -Created link: src/parser.c ──implements──> rfc/grammar.txt [claude: claude@anthropic, conf: 0.85] +$ git mind link core/src/parser.c rfc/grammar.txt --type implements --confidence 0.85 +Created link: core/src/parser.c ──implements──> rfc/grammar.txt [claude: claude@anthropic, conf: 0.85] # High-confidence AI relationship -$ git mind link src/algorithm.c papers/dijkstra62.pdf --type references --confidence 0.95 +$ git mind link core/src/algorithm.c papers/dijkstra62.pdf --type references --confidence 0.95 ``` ### Bidirectional links - Symmetric relationships ```bash # These files are peers that reference each other -$ git mind link src/client.c src/server.c --type references --bidirectional -Created edge: src/client.c ──references──> src/server.c -Created edge: src/server.c ──references──> src/client.c +$ git mind link core/src/client.c core/src/server.c --type references --bidirectional +Created edge: core/src/client.c ──references──> core/src/server.c +Created edge: core/src/server.c ──references──> core/src/client.c ``` ### Human-AI Collaboration - Attribution System ```bash # Human creates edge (default behavior) -$ git mind link README.md src/main.c --type documents -Created link: README.md ──documents──> src/main.c +$ git mind link README.md core/src/main.c --type documents +Created link: README.md ──documents──> core/src/main.c # AI creates edge with attribution $ export GIT_MIND_SOURCE=claude $ export GIT_MIND_AUTHOR=claude@anthropic $ export GIT_MIND_SESSION=analysis_2025 -$ git mind link src/auth.c config/oauth.json --type depends_on --confidence 0.82 -Created link: src/auth.c ──depends_on──> config/oauth.json [claude: claude@anthropic, conf: 0.82] +$ git mind link core/src/auth.c config/oauth.json --type depends_on --confidence 0.82 +Created link: core/src/auth.c ──depends_on──> config/oauth.json [claude: claude@anthropic, conf: 0.82] # System-generated edge (from hooks) $ export GIT_MIND_SOURCE=system @@ -671,7 +671,7 @@ Links are branch-specific. Create different connections on different branches: ```bash git checkout -b feature/auth -git mind link src/auth.c new-auth-api.md --type implements +git mind link core/src/auth.c new-auth-api.md --type implements git checkout main git mind list # Won't show the feature branch link @@ -715,10 +715,10 @@ While you can use any string as a relationship type, these conventions help main ```bash # Too vague -$ git mind link src/parser.c docs/ --type references # Which doc? +$ git mind link core/src/parser.c docs/ --type references # Which doc? # Better -$ git mind link src/parser.c docs/parser-design.md --type implements +$ git mind link core/src/parser.c docs/parser-design.md --type implements ``` ### Use Conventional Types @@ -740,7 +740,7 @@ $ git mind list --type tests ```bash # Why does the parser depend on the logger config? -$ git mind link src/parser.c config/logger.yaml --type depends_on \ +$ git mind link core/src/parser.c config/logger.yaml --type depends_on \ --note "Parser uses logger for syntax error reporting" ``` @@ -843,10 +843,10 @@ With git-mind: ```bash # All connections at a glance -$ git mind list --from src/parser.c +$ git mind list --from core/src/parser.c # Specific relationships -$ git mind list --type tests --to src/auth.c +$ git mind list --type tests --to core/src/auth.c # Everything in the web $ git mind list @@ -912,9 +912,9 @@ Show all connections: ```bash $ git mind list README.md ──references──> docs/quickstart.md -src/main.c ──implements──> docs/design.md -tests/test_parser.c ──tests──> src/parser.c -src/parser.c ──depends_on──> config/grammar.yaml +core/src/main.c ──implements──> docs/design.md +tests/test_parser.c ──tests──> core/src/parser.c +core/src/parser.c ──depends_on──> config/grammar.yaml ... (42 more edges) ``` @@ -923,20 +923,20 @@ src/parser.c ──depends_on──> config/grammar.yaml What does this file connect to? ```bash -$ git mind list --from src/auth.c -src/auth.c ──implements──> docs/auth-design.md -src/auth.c ──depends_on──> config/auth.yaml -src/auth.c ──references──> lib/crypto.c +$ git mind list --from core/src/auth.c +core/src/auth.c ──implements──> docs/auth-design.md +core/src/auth.c ──depends_on──> config/auth.yaml +core/src/auth.c ──references──> lib/crypto.c ``` What connects to this file? ```bash -$ git mind list --to src/parser.c -tests/test_parser.c ──tests──> src/parser.c -tests/bench_parser.c ──benchmarks──> src/parser.c -docs/parser-guide.md ──documents──> src/parser.c -src/compiler.c ──depends_on──> src/parser.c +$ git mind list --to core/src/parser.c +tests/test_parser.c ──tests──> core/src/parser.c +tests/bench_parser.c ──benchmarks──> core/src/parser.c +docs/parser-guide.md ──documents──> core/src/parser.c +core/src/compiler.c ──depends_on──> core/src/parser.c ``` ### Filtered Queries @@ -945,17 +945,17 @@ Find all test files: ```bash $ git mind list --type tests -tests/test_auth.c ──tests──> src/auth.c -tests/test_parser.c ──tests──> src/parser.c -tests/integration/test_flow.c ──tests──> src/flow.c +tests/test_auth.c ──tests──> core/src/auth.c +tests/test_parser.c ──tests──> core/src/parser.c +tests/integration/test_flow.c ──tests──> core/src/flow.c ``` Find uncertain connections: ```bash $ git mind list --min-confidence 0.8 -src/auth.c ──depends_on──> config/oauth.json [claude: claude@anthropic, conf: 0.85] -src/parser.c ──implements──> specs/grammar.md [gpt: gpt4@openai, conf: 0.92] +core/src/auth.c ──depends_on──> config/oauth.json [claude: claude@anthropic, conf: 0.85] +core/src/parser.c ──implements──> specs/grammar.md [gpt: gpt4@openai, conf: 0.92] ``` ### Attribution Filtering @@ -964,34 +964,34 @@ Show only human-created edges: ```bash $ git mind list --source human -README.md ──documents──> src/main.c -src/auth.c ──implements──> docs/auth-design.md -tests/test_auth.c ──tests──> src/auth.c +README.md ──documents──> core/src/main.c +core/src/auth.c ──implements──> docs/auth-design.md +tests/test_auth.c ──tests──> core/src/auth.c ``` Show only AI-suggested edges: ```bash $ git mind list --source ai -src/parser.c ──depends_on──> lib/lexer.h [claude: claude@anthropic, conf: 0.78] -src/crypto.c ──references──> papers/aes.pdf [gpt: gpt4@openai, conf: 0.91] +core/src/parser.c ──depends_on──> lib/lexer.h [claude: claude@anthropic, conf: 0.78] +core/src/crypto.c ──references──> papers/aes.pdf [gpt: gpt4@openai, conf: 0.91] ``` Show attribution for all edges: ```bash $ git mind list --show-attribution -README.md ──documents──> src/main.c [human: user@example.com] -src/auth.c ──depends_on──> config/oauth.json [claude: claude@anthropic, conf: 0.85] -src/test.c ──tests──> src/main.c [human: developer@team.com] +README.md ──documents──> core/src/main.c [human: user@example.com] +core/src/auth.c ──depends_on──> config/oauth.json [claude: claude@anthropic, conf: 0.85] +core/src/test.c ──tests──> core/src/main.c [human: developer@team.com] ``` High-confidence AI insights only: ```bash $ git mind list --source ai --min-confidence 0.9 -src/crypto.c ──references──> papers/aes.pdf [gpt: gpt4@openai, conf: 0.91] -src/algorithm.c ──implements──> papers/dijkstra.pdf [claude: claude@anthropic, conf: 0.95] +core/src/crypto.c ──references──> papers/aes.pdf [gpt: gpt4@openai, conf: 0.91] +core/src/algorithm.c ──implements──> papers/dijkstra.pdf [claude: claude@anthropic, conf: 0.95] ``` ### Time Travel Queries @@ -1015,8 +1015,8 @@ See how files evolved: ```bash $ git mind list --show-augments -src/auth.c:8a9f3b ──AUGMENTS──> src/auth.c:7c4d5e -src/auth.c:7c4d5e ──AUGMENTS──> src/auth.c:current +core/src/auth.c:8a9f3b ──AUGMENTS──> core/src/auth.c:7c4d5e +core/src/auth.c:7c4d5e ──AUGMENTS──> core/src/auth.c:current docs/api.md:3f2a1b ──AUGMENTS──> docs/api.md:current ``` @@ -1087,7 +1087,7 @@ The list command uses the Roaring Bitmap cache for O(log N) queries: ```bash # What does my module depend on? -$ git mind list --from "src/mymodule/**" --type depends_on +$ git mind list --from "core/src/mymodule/**" --type depends_on # What depends on this config? $ git mind list --to config/database.yaml --type depends_on @@ -1098,7 +1098,7 @@ $ git mind list --to config/database.yaml --type depends_on ```bash # What files lack tests? $ comm -23 \ - <(git ls-files src/ | sort) \ + <(git ls-files core/src/ | sort) \ <(git mind list --type tests --format tsv | cut -f2 | sort) ``` @@ -1114,7 +1114,7 @@ $ dot -Tsvg arch.dot -o architecture.svg ```bash # What might break if I change this? -$ git mind list --to src/core-api.h --type depends_on +$ git mind list --to core/src/core-api.h --type depends_on ``` ## PHILOSOPHY @@ -1288,32 +1288,32 @@ README.md ──references──> docs/quickstart.md ```bash # Document implementation relationships -$ git mind link src/parser.c docs/parser-design.md --type implements -$ git mind link src/lexer.c docs/parser-design.md --type implements +$ git mind link core/src/parser.c docs/parser-design.md --type implements +$ git mind link core/src/lexer.c docs/parser-design.md --type implements # Track test coverage -$ git mind link tests/test_parser.c src/parser.c --type tests -$ git mind link tests/test_lexer.c src/lexer.c --type tests +$ git mind link tests/test_parser.c core/src/parser.c --type tests +$ git mind link tests/test_lexer.c core/src/lexer.c --type tests # Show everything connected to the design $ git mind list --to docs/parser-design.md -src/parser.c ──implements──> docs/parser-design.md -src/lexer.c ──implements──> docs/parser-design.md +core/src/parser.c ──implements──> docs/parser-design.md +core/src/lexer.c ──implements──> docs/parser-design.md ``` ### Time Travel Through Understanding ```bash # Current state -$ git mind list --from src/api.c -src/api.c ──depends_on──> config/api.yaml -src/api.c ──implements──> docs/api-v2.md +$ git mind list --from core/src/api.c +core/src/api.c ──depends_on──> config/api.yaml +core/src/api.c ──implements──> docs/api-v2.md # Travel back 30 commits $ git checkout HEAD~30 -$ git mind list --from src/api.c -src/api.c ──implements──> docs/api-v1.md -src/api.c ──experimental──> research/new-approach.pdf +$ git mind list --from core/src/api.c +core/src/api.c ──implements──> docs/api-v1.md +core/src/api.c ──experimental──> research/new-approach.pdf # Return to present $ git checkout main @@ -1327,12 +1327,12 @@ $ git mind install-hooks ✓ Hooks installed - file evolution will be tracked automatically # Edit a file that has connections -$ vim src/parser.c -$ git add src/parser.c && git commit -m "Optimize parser" +$ vim core/src/parser.c +$ git add core/src/parser.c && git commit -m "Optimize parser" # The connections followed the change! -$ git mind list --from src/parser.c -src/parser.c ──implements──> docs/parser-design.md +$ git mind list --from core/src/parser.c +core/src/parser.c ──implements──> docs/parser-design.md # (connection automatically updated to new blob SHA) ``` @@ -1344,7 +1344,7 @@ $ git mind status Semantic Graph Statistics: - Total edges: 3,847 - Unique relationships: 12 types -- Most connected: src/core.c (147 connections) +- Most connected: core/src/core.c (147 connections) # Queries getting slow? $ git mind cache-rebuild diff --git a/docs/cli/gitmind-cache-rebuild.md b/docs/cli/gitmind-cache-rebuild.md index 934683db..56429313 100644 --- a/docs/cli/gitmind-cache-rebuild.md +++ b/docs/cli/gitmind-cache-rebuild.md @@ -83,8 +83,8 @@ Cache rebuilt successfully! ### Rebuild after heavy development ```bash -$ git mind link src/parser.c docs/parsing.md --type implements -$ git mind link src/lexer.c src/parser.c --type feeds +$ git mind link core/src/parser.c docs/parsing.md --type implements +$ git mind link core/src/lexer.c core/src/parser.c --type feeds $ git mind cache-rebuild Rebuilding cache for branch 'feature/parser'... Processed 2 new edges from 2 commits @@ -97,7 +97,7 @@ Cache updated incrementally! $ git mind cache-rebuild --force --verbose Force rebuilding cache for branch 'main'... Walking journal from refs/gitmind/edges/main -[00] Processing edge: design.md -> src/main.c (implements) +[00] Processing edge: design.md -> core/src/main.c (implements) [01] Processing edge: README.md -> docs/api.md (references) ... Building forward index bitmaps... diff --git a/docs/cli/gitmind-install-hooks.md b/docs/cli/gitmind-install-hooks.md index b9f51766..c175d0b7 100644 --- a/docs/cli/gitmind-install-hooks.md +++ b/docs/cli/gitmind-install-hooks.md @@ -199,8 +199,8 @@ AUGMENTS edges have a special format: tgt_sha: "def456...", // New blob SHA rel_type: "AUGMENTS", confidence: 1.0, - src_path: "src/old.c", // For readability - tgt_path: "src/new.c" // May differ if renamed + src_path: "core/src/old.c", // For readability + tgt_path: "core/src/new.c" // May differ if renamed } ``` diff --git a/docs/cli/gitmind-link.md b/docs/cli/gitmind-link.md index 37f50dac..ec0463c1 100644 --- a/docs/cli/gitmind-link.md +++ b/docs/cli/gitmind-link.md @@ -44,8 +44,8 @@ This is the command that started it all. When you create a link, you're not just ```bash # The moment of connection -$ git mind link design.md src/parser.c --type implements -Created edge: design.md ──implements──> src/parser.c +$ git mind link design.md core/src/parser.c --type implements +Created edge: design.md ──implements──> core/src/parser.c ``` From this moment forward, anyone who checks out your code can discover this relationship. More importantly, they can travel back in time and see what you understood at any point in history. @@ -87,53 +87,53 @@ From this moment forward, anyone who checks out your code can discover this rela ```bash # Implementation tracks design -$ git mind link src/auth.c docs/auth-design.md --type implements +$ git mind link core/src/auth.c docs/auth-design.md --type implements # Test validates implementation -$ git mind link tests/test_auth.c src/auth.c --type tests +$ git mind link tests/test_auth.c core/src/auth.c --type tests # Config guides behavior -$ git mind link src/auth.c config/auth.yaml --type depends_on +$ git mind link core/src/auth.c config/auth.yaml --type depends_on ``` ### With confidence - Encoding uncertainty ```bash # Human creating a confident link (confidence defaults to 1.0) -$ git mind link src/parser.c rfc/grammar.txt --type implements +$ git mind link core/src/parser.c rfc/grammar.txt --type implements # AI suggesting a relationship with confidence score $ export GIT_MIND_SOURCE=claude $ export GIT_MIND_AUTHOR=claude@anthropic -$ git mind link src/parser.c rfc/grammar.txt --type implements --confidence 0.85 -Created link: src/parser.c ──implements──> rfc/grammar.txt [claude: claude@anthropic, conf: 0.85] +$ git mind link core/src/parser.c rfc/grammar.txt --type implements --confidence 0.85 +Created link: core/src/parser.c ──implements──> rfc/grammar.txt [claude: claude@anthropic, conf: 0.85] # High-confidence AI relationship -$ git mind link src/algorithm.c papers/dijkstra62.pdf --type references --confidence 0.95 +$ git mind link core/src/algorithm.c papers/dijkstra62.pdf --type references --confidence 0.95 ``` ### Bidirectional links - Symmetric relationships ```bash # These files are peers that reference each other -$ git mind link src/client.c src/server.c --type references --bidirectional -Created edge: src/client.c ──references──> src/server.c -Created edge: src/server.c ──references──> src/client.c +$ git mind link core/src/client.c core/src/server.c --type references --bidirectional +Created edge: core/src/client.c ──references──> core/src/server.c +Created edge: core/src/server.c ──references──> core/src/client.c ``` ### Human-AI Collaboration - Attribution System ```bash # Human creates edge (default behavior) -$ git mind link README.md src/main.c --type documents -Created link: README.md ──documents──> src/main.c +$ git mind link README.md core/src/main.c --type documents +Created link: README.md ──documents──> core/src/main.c # AI creates edge with attribution $ export GIT_MIND_SOURCE=claude $ export GIT_MIND_AUTHOR=claude@anthropic $ export GIT_MIND_SESSION=analysis_2025 -$ git mind link src/auth.c config/oauth.json --type depends_on --confidence 0.82 -Created link: src/auth.c ──depends_on──> config/oauth.json [claude: claude@anthropic, conf: 0.82] +$ git mind link core/src/auth.c config/oauth.json --type depends_on --confidence 0.82 +Created link: core/src/auth.c ──depends_on──> config/oauth.json [claude: claude@anthropic, conf: 0.82] # System-generated edge (from hooks) $ export GIT_MIND_SOURCE=system @@ -168,7 +168,7 @@ Links are branch-specific. Create different connections on different branches: ```bash git checkout -b feature/auth -git mind link src/auth.c new-auth-api.md --type implements +git mind link core/src/auth.c new-auth-api.md --type implements git checkout main git mind list # Won't show the feature branch link @@ -212,10 +212,10 @@ While you can use any string as a relationship type, these conventions help main ```bash # Too vague -$ git mind link src/parser.c docs/ --type references # Which doc? +$ git mind link core/src/parser.c docs/ --type references # Which doc? # Better -$ git mind link src/parser.c docs/parser-design.md --type implements +$ git mind link core/src/parser.c docs/parser-design.md --type implements ``` ### Use Conventional Types @@ -237,7 +237,7 @@ $ git mind list --type tests ```bash # Why does the parser depend on the logger config? -$ git mind link src/parser.c config/logger.yaml --type depends_on \ +$ git mind link core/src/parser.c config/logger.yaml --type depends_on \ --note "Parser uses logger for syntax error reporting" ``` diff --git a/docs/cli/gitmind-list.md b/docs/cli/gitmind-list.md index 128847b8..c08f9d58 100644 --- a/docs/cli/gitmind-list.md +++ b/docs/cli/gitmind-list.md @@ -55,10 +55,10 @@ With git-mind: ```bash # All connections at a glance -$ git mind list --from src/parser.c +$ git mind list --from core/src/parser.c # Specific relationships -$ git mind list --type tests --to src/auth.c +$ git mind list --type tests --to core/src/auth.c # Everything in the web $ git mind list @@ -124,9 +124,9 @@ Show all connections: ```bash $ git mind list README.md ──references──> docs/quickstart.md -src/main.c ──implements──> docs/design.md -tests/test_parser.c ──tests──> src/parser.c -src/parser.c ──depends_on──> config/grammar.yaml +core/src/main.c ──implements──> docs/design.md +tests/test_parser.c ──tests──> core/src/parser.c +core/src/parser.c ──depends_on──> config/grammar.yaml ... (42 more edges) ``` @@ -135,20 +135,20 @@ src/parser.c ──depends_on──> config/grammar.yaml What does this file connect to? ```bash -$ git mind list --from src/auth.c -src/auth.c ──implements──> docs/auth-design.md -src/auth.c ──depends_on──> config/auth.yaml -src/auth.c ──references──> lib/crypto.c +$ git mind list --from core/src/auth.c +core/src/auth.c ──implements──> docs/auth-design.md +core/src/auth.c ──depends_on──> config/auth.yaml +core/src/auth.c ──references──> lib/crypto.c ``` What connects to this file? ```bash -$ git mind list --to src/parser.c -tests/test_parser.c ──tests──> src/parser.c -tests/bench_parser.c ──benchmarks──> src/parser.c -docs/parser-guide.md ──documents──> src/parser.c -src/compiler.c ──depends_on──> src/parser.c +$ git mind list --to core/src/parser.c +tests/test_parser.c ──tests──> core/src/parser.c +tests/bench_parser.c ──benchmarks──> core/src/parser.c +docs/parser-guide.md ──documents──> core/src/parser.c +core/src/compiler.c ──depends_on──> core/src/parser.c ``` ### Filtered Queries @@ -157,17 +157,17 @@ Find all test files: ```bash $ git mind list --type tests -tests/test_auth.c ──tests──> src/auth.c -tests/test_parser.c ──tests──> src/parser.c -tests/integration/test_flow.c ──tests──> src/flow.c +tests/test_auth.c ──tests──> core/src/auth.c +tests/test_parser.c ──tests──> core/src/parser.c +tests/integration/test_flow.c ──tests──> core/src/flow.c ``` Find uncertain connections: ```bash $ git mind list --min-confidence 0.8 -src/auth.c ──depends_on──> config/oauth.json [claude: claude@anthropic, conf: 0.85] -src/parser.c ──implements──> specs/grammar.md [gpt: gpt4@openai, conf: 0.92] +core/src/auth.c ──depends_on──> config/oauth.json [claude: claude@anthropic, conf: 0.85] +core/src/parser.c ──implements──> specs/grammar.md [gpt: gpt4@openai, conf: 0.92] ``` ### Attribution Filtering @@ -176,34 +176,34 @@ Show only human-created edges: ```bash $ git mind list --source human -README.md ──documents──> src/main.c -src/auth.c ──implements──> docs/auth-design.md -tests/test_auth.c ──tests──> src/auth.c +README.md ──documents──> core/src/main.c +core/src/auth.c ──implements──> docs/auth-design.md +tests/test_auth.c ──tests──> core/src/auth.c ``` Show only AI-suggested edges: ```bash $ git mind list --source ai -src/parser.c ──depends_on──> lib/lexer.h [claude: claude@anthropic, conf: 0.78] -src/crypto.c ──references──> papers/aes.pdf [gpt: gpt4@openai, conf: 0.91] +core/src/parser.c ──depends_on──> lib/lexer.h [claude: claude@anthropic, conf: 0.78] +core/src/crypto.c ──references──> papers/aes.pdf [gpt: gpt4@openai, conf: 0.91] ``` Show attribution for all edges: ```bash $ git mind list --show-attribution -README.md ──documents──> src/main.c [human: user@example.com] -src/auth.c ──depends_on──> config/oauth.json [claude: claude@anthropic, conf: 0.85] -src/test.c ──tests──> src/main.c [human: developer@team.com] +README.md ──documents──> core/src/main.c [human: user@example.com] +core/src/auth.c ──depends_on──> config/oauth.json [claude: claude@anthropic, conf: 0.85] +core/src/test.c ──tests──> core/src/main.c [human: developer@team.com] ``` High-confidence AI insights only: ```bash $ git mind list --source ai --min-confidence 0.9 -src/crypto.c ──references──> papers/aes.pdf [gpt: gpt4@openai, conf: 0.91] -src/algorithm.c ──implements──> papers/dijkstra.pdf [claude: claude@anthropic, conf: 0.95] +core/src/crypto.c ──references──> papers/aes.pdf [gpt: gpt4@openai, conf: 0.91] +core/src/algorithm.c ──implements──> papers/dijkstra.pdf [claude: claude@anthropic, conf: 0.95] ``` ### Time Travel Queries @@ -227,8 +227,8 @@ See how files evolved: ```bash $ git mind list --show-augments -src/auth.c:8a9f3b ──AUGMENTS──> src/auth.c:7c4d5e -src/auth.c:7c4d5e ──AUGMENTS──> src/auth.c:current +core/src/auth.c:8a9f3b ──AUGMENTS──> core/src/auth.c:7c4d5e +core/src/auth.c:7c4d5e ──AUGMENTS──> core/src/auth.c:current docs/api.md:3f2a1b ──AUGMENTS──> docs/api.md:current ``` @@ -299,7 +299,7 @@ The list command uses the Roaring Bitmap cache for O(log N) queries: ```bash # What does my module depend on? -$ git mind list --from "src/mymodule/**" --type depends_on +$ git mind list --from "core/src/mymodule/**" --type depends_on # What depends on this config? $ git mind list --to config/database.yaml --type depends_on @@ -310,7 +310,7 @@ $ git mind list --to config/database.yaml --type depends_on ```bash # What files lack tests? $ comm -23 \ - <(git ls-files src/ | sort) \ + <(git ls-files core/src/ | sort) \ <(git mind list --type tests --format tsv | cut -f2 | sort) ``` @@ -326,7 +326,7 @@ $ dot -Tsvg arch.dot -o architecture.svg ```bash # What might break if I change this? -$ git mind list --to src/core-api.h --type depends_on +$ git mind list --to core/src/core-api.h --type depends_on ``` ## PHILOSOPHY diff --git a/docs/cli/gitmind.md b/docs/cli/gitmind.md index f0970c6f..b1807409 100644 --- a/docs/cli/gitmind.md +++ b/docs/cli/gitmind.md @@ -143,32 +143,32 @@ README.md ──references──> docs/quickstart.md ```bash # Document implementation relationships -$ git mind link src/parser.c docs/parser-design.md --type implements -$ git mind link src/lexer.c docs/parser-design.md --type implements +$ git mind link core/src/parser.c docs/parser-design.md --type implements +$ git mind link core/src/lexer.c docs/parser-design.md --type implements # Track test coverage -$ git mind link tests/test_parser.c src/parser.c --type tests -$ git mind link tests/test_lexer.c src/lexer.c --type tests +$ git mind link tests/test_parser.c core/src/parser.c --type tests +$ git mind link tests/test_lexer.c core/src/lexer.c --type tests # Show everything connected to the design $ git mind list --to docs/parser-design.md -src/parser.c ──implements──> docs/parser-design.md -src/lexer.c ──implements──> docs/parser-design.md +core/src/parser.c ──implements──> docs/parser-design.md +core/src/lexer.c ──implements──> docs/parser-design.md ``` ### Time Travel Through Understanding ```bash # Current state -$ git mind list --from src/api.c -src/api.c ──depends_on──> config/api.yaml -src/api.c ──implements──> docs/api-v2.md +$ git mind list --from core/src/api.c +core/src/api.c ──depends_on──> config/api.yaml +core/src/api.c ──implements──> docs/api-v2.md # Travel back 30 commits $ git checkout HEAD~30 -$ git mind list --from src/api.c -src/api.c ──implements──> docs/api-v1.md -src/api.c ──experimental──> research/new-approach.pdf +$ git mind list --from core/src/api.c +core/src/api.c ──implements──> docs/api-v1.md +core/src/api.c ──experimental──> research/new-approach.pdf # Return to present $ git checkout main @@ -182,12 +182,12 @@ $ git mind install-hooks ✓ Hooks installed - file evolution will be tracked automatically # Edit a file that has connections -$ vim src/parser.c -$ git add src/parser.c && git commit -m "Optimize parser" +$ vim core/src/parser.c +$ git add core/src/parser.c && git commit -m "Optimize parser" # The connections followed the change! -$ git mind list --from src/parser.c -src/parser.c ──implements──> docs/parser-design.md +$ git mind list --from core/src/parser.c +core/src/parser.c ──implements──> docs/parser-design.md # (connection automatically updated to new blob SHA) ``` @@ -199,7 +199,7 @@ $ git mind status Semantic Graph Statistics: - Total edges: 3,847 - Unique relationships: 12 types -- Most connected: src/core.c (147 connections) +- Most connected: core/src/core.c (147 connections) # Queries getting slow? $ git mind cache-rebuild diff --git a/docs/enforcer/gameplans/05-config-convention-overhaul.md b/docs/enforcer/gameplans/05-config-convention-overhaul.md index 21f8a46a..e79a9c78 100644 --- a/docs/enforcer/gameplans/05-config-convention-overhaul.md +++ b/docs/enforcer/gameplans/05-config-convention-overhaul.md @@ -536,7 +536,7 @@ void test_cli_flag_parsing(void) { "-c", "/custom/config.toml", "link", "--type", "depends", - "src/a.c", "src/b.c" + "core/src/a.c", "core/src/b.c" }; int argc = sizeof(argv) / sizeof(argv[0]); diff --git a/docs/enforcer/gameplans/09-domain-language-purity.md b/docs/enforcer/gameplans/09-domain-language-purity.md index d904bdd5..9e08b035 100644 --- a/docs/enforcer/gameplans/09-domain-language-purity.md +++ b/docs/enforcer/gameplans/09-domain-language-purity.md @@ -687,7 +687,7 @@ void test_type_safety(void) { // Runtime type validation gm_node_id_t node_id; GM_ASSERT_OK(gm_node_id_from_path( - (gm_path_t){.value = "src/main.c"}, &node_id)); + (gm_path_t){.value = "core/src/main.c"}, &node_id)); // Invalid types rejected GM_ASSERT_ERROR(gm_node_id_from_path( @@ -727,7 +727,7 @@ void test_semantic_api(void) { )); GM_ASSERT_OK(gm_knowledge_node_create( - gm_path_from_string("src/main.c"), + gm_path_from_string("core/src/main.c"), GM_NODE_TYPE_FILE, &source_file )); diff --git a/docs/features/Features_Ledger.md b/docs/features/Features_Ledger.md index 2a4ee16b..73faf789 100644 --- a/docs/features/Features_Ledger.md +++ b/docs/features/Features_Ledger.md @@ -214,11 +214,11 @@ features=3 > [!INFO]- > Thread author/time data through cache rebuild + `git mind list`; document flag to toggle extended columns. -- [ ] [Alpha] Retire legacy `src/` tree +- [x] [Alpha] Retire legacy `src/` tree > [!INFO]- > Move remaining markdown artifacts under `src/` into `docs/legacy/src/`, remove empty scaffolding, and update references so core/ is the sole code root. -- [ ] [Alpha] Sweep includes and docs for `src/` references +- [x] [Alpha] Sweep includes and docs for `src/` references > [!INFO]- > Replace lingering `src/` include or doc paths with `core/` equivalents and ensure tooling/tests reflect the finalized layout. diff --git a/docs/quality/static-analysis-guide.md b/docs/quality/static-analysis-guide.md index 6d3ce8f7..07e8664d 100644 --- a/docs/quality/static-analysis-guide.md +++ b/docs/quality/static-analysis-guide.md @@ -144,7 +144,7 @@ __Strengths__: Interprocedural, incremental analysis pip install flawfinder # Run -flawfinder --html --context src/ > security-report.html +flawfinder --html --context core/src/ > security-report.html ``` __Catches__: Security vulnerabilities, unsafe functions diff --git a/docs/talk-shop/Graph-Lvl-Up-Tank.md b/docs/talk-shop/Graph-Lvl-Up-Tank.md index 03f7e980..369bbcd3 100644 --- a/docs/talk-shop/Graph-Lvl-Up-Tank.md +++ b/docs/talk-shop/Graph-Lvl-Up-Tank.md @@ -55,7 +55,7 @@ Welcome to the tank queue. Strap in; by the time you exit, you should be dangero | --- | --- | --- | | “All artifacts tied to this file” | `MATCH (f:File {oid:$oid})-[:TOUCHES|:REFLECTS|:JOURNEY_HAS*1..2]->(x) RETURN x` | Include journey bundles for 1-hop hits. | | “Which commits closed issue #42?” | `MATCH (i:Issue {number:42})-[:RESOLVED_IN]->(j:Journey)-[:MERGED_IN]->(c:Commit) RETURN c` | Journey keeps metadata; fallback to merge edges. | -| “Retro notes within 2 hops of auth.c” | `MATCH (f:File {path:'src/auth.c'})-[:REFLECTS\|:JOURNEY_HAS*1..2]->(r:Retro) RETURN DISTINCT r` | Filters keep CLI output sane. | +| “Retro notes within 2 hops of auth.c” | `MATCH (f:File {path:'core/src/auth.c'})-[:REFLECTS\|:JOURNEY_HAS*1..2]->(r:Retro) RETURN DISTINCT r` | Filters keep CLI output sane. | | “What changed between C2 and C5?” | Use timeline diff: `gm timeline diff --from C2 --to C5 --edge-types implements,verified_by` | Rely on cache deltas; avoid brute-force BFS. | ## 4. Modeling Checklist (Before You Commit Your Thoughts) @@ -72,7 +72,7 @@ Welcome to the tank queue. Strap in; by the time you exit, you should be dangero - **Docs Backfill**: Update `docs/architecture/*` whenever you invent a new edge type or path strategy; ledger tasks depend on that clarity. ## 6. Level-Up Quests (XP Farming) -1. Run `git mind list --from src/auth.c --with-attribution` and sketch the path you *expected* vs. what exists. Gap? Add edges or journeys. +1. Run `git mind list --from core/src/auth.c --with-attribution` and sketch the path you *expected* vs. what exists. Gap? Add edges or journeys. 2. Model Issue → Review → Merge as a journey node in a scratch graph; verify you can reach every participant in ≤2 hops. 3. Draft a Cypher query that respects time-travel (`WHERE c.ulid BETWEEN $from AND $to`). Translate it into git-mind CLI verbs. 4. Teach someone else the difference between canonical vs. derived edges. If you can’t explain it in one whiteboard, repeat this tank session. diff --git a/docs/tutorial.md b/docs/tutorial.md index 2a844919..b944338f 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -30,8 +30,8 @@ export GITMIND_SAFETY=off Create a semantic edge between two files (document → code, code → test, etc.). ```bash -$ "$GIT_MIND" link README.md src/main.c --type documents -Created: README.md -[documents]-> src/main.c +$ "$GIT_MIND" link README.md core/src/main.c --type documents + Created: README.md -[documents]-> core/src/main.c ``` More linking examples and options: `docs/cli/gitmind-link.md`. @@ -42,7 +42,7 @@ List edges from a file to see what it’s connected to. ```bash $ "$GIT_MIND" list --from README.md -README.md -> src/main.c (documents) +README.md -> core/src/main.c (documents) ``` Formatting and filters: `docs/cli/gitmind-list.md`. diff --git a/docs/wish-list-features/brain-storms/CLAUDE_ULTRATHINKS_GITMIND_FUTURE.md b/docs/wish-list-features/brain-storms/CLAUDE_ULTRATHINKS_GITMIND_FUTURE.md index fb92f1ac..6d049635 100644 --- a/docs/wish-list-features/brain-storms/CLAUDE_ULTRATHINKS_GITMIND_FUTURE.md +++ b/docs/wish-list-features/brain-storms/CLAUDE_ULTRATHINKS_GITMIND_FUTURE.md @@ -478,7 +478,7 @@ typedef struct { // Inference API gm_prediction_t *predictions = gm_ml_predict_edges( engine, - "src/auth.c", + "core/src/auth.c", GM_PREDICT_DEPENDENCIES | GM_PREDICT_IMPLEMENTS ); ``` From 62c7e48933f1386d7e6ffc6f787b4c3c9c69d8c8 Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Wed, 17 Sep 2025 19:47:15 -0700 Subject: [PATCH 34/42] tests: cover cache branch limits and tree size --- core/tests/unit/test_cache_branch_limits.c | 119 +++++++++++++++++++++ core/tests/unit/test_cache_tree_size.c | 91 ++++++++++++++++ docs/features/Features_Ledger.md | 4 +- meson.build | 14 +++ 4 files changed, 226 insertions(+), 2 deletions(-) create mode 100644 core/tests/unit/test_cache_branch_limits.c create mode 100644 core/tests/unit/test_cache_tree_size.c diff --git a/core/tests/unit/test_cache_branch_limits.c b/core/tests/unit/test_cache_branch_limits.c new file mode 100644 index 00000000..4348e1c6 --- /dev/null +++ b/core/tests/unit/test_cache_branch_limits.c @@ -0,0 +1,119 @@ +/* SPDX-License-Identifier: LicenseRef-MIND-UCAL-1.0 */ +/* © 2025 J. Kirby Ross / Neuroglyph Collective */ + +#include +#include +#include + +#include +#include + +#include "gitmind/cache.h" +#include "gitmind/context.h" +#include "gitmind/edge.h" +#include "gitmind/error.h" +#include "gitmind/journal.h" +#include "gitmind/types.h" +#include "gitmind/types/ulid.h" + +static void set_user_config(git_repository *repo) { + git_config *cfg = NULL; + int rc = git_repository_config(&cfg, repo); + assert(rc == 0); + rc = git_config_set_string(cfg, "user.name", "Tester"); + assert(rc == 0); + rc = git_config_set_string(cfg, "user.email", "tester@example.com"); + assert(rc == 0); + git_config_free(cfg); +} + +static void ensure_branch_with_commit(git_repository *repo, const char *branch) { + git_treebuilder *tb = NULL; + git_oid tree_oid, commit_oid; + git_signature *sig = NULL; + git_reference *ref = NULL; + char refname[256]; + int rc; + + rc = git_treebuilder_new(&tb, repo, NULL); + assert(rc == 0); + rc = git_treebuilder_write(&tree_oid, tb); + git_treebuilder_free(tb); + assert(rc == 0); + + rc = git_signature_now(&sig, "tester", "tester@example.com"); + assert(rc == 0); + + snprintf(refname, sizeof refname, "refs/heads/%s", branch); + rc = git_commit_create_from_ids(&commit_oid, repo, NULL, sig, sig, NULL, + "init", &tree_oid, 0, NULL); + git_signature_free(sig); + assert(rc == 0); + + rc = git_reference_create(&ref, repo, refname, &commit_oid, 1, "init"); + if (ref != NULL) { + git_reference_free(ref); + } + assert(rc == 0); + + rc = git_repository_set_head(repo, refname); + assert(rc == 0); +} + +static void append_dummy_edge(gm_context_t *ctx) { + gm_edge_t edge; + memset(&edge, 0, sizeof edge); + + uint8_t src_raw[GM_OID_RAWSZ]; + uint8_t tgt_raw[GM_OID_RAWSZ]; + memset(src_raw, 0x11, sizeof src_raw); + memset(tgt_raw, 0x22, sizeof tgt_raw); + + git_oid_fromraw(&edge.src_oid, src_raw); + git_oid_fromraw(&edge.tgt_oid, tgt_raw); + + edge.rel_type = GM_REL_IMPLEMENTS; + edge.confidence = 0x3C00; + strcpy(edge.src_path, "A"); + strcpy(edge.tgt_path, "B"); + (void)gm_ulid_generate(edge.ulid); + + int rc = gm_journal_append(ctx, &edge, 1); + assert(rc == GM_OK); +} + +int main(void) { + printf("test_cache_branch_limits... "); + git_libgit2_init(); + + git_repository *repo = NULL; + int rc = git_repository_init(&repo, "./.gm_cache_branch_tmp", true); + assert(rc == 0 && repo); + set_user_config(repo); + + char valid_branch[GM_CACHE_BRANCH_NAME_SIZE]; + memset(valid_branch, 'a', sizeof valid_branch); + valid_branch[GM_CACHE_BRANCH_NAME_SIZE - 1] = '\0'; + ensure_branch_with_commit(repo, valid_branch); + + gm_context_t ctx = {0}; + ctx.git_repo = repo; + + append_dummy_edge(&ctx); + rc = gm_cache_rebuild(&ctx, valid_branch, true); + assert(rc == GM_OK); + + char invalid_branch[GM_CACHE_BRANCH_NAME_SIZE + 1]; + memset(invalid_branch, 'b', sizeof invalid_branch); + invalid_branch[GM_CACHE_BRANCH_NAME_SIZE] = '\0'; + ensure_branch_with_commit(repo, invalid_branch); + append_dummy_edge(&ctx); + + rc = gm_cache_rebuild(&ctx, invalid_branch, true); + assert(rc == GM_ERR_INVALID_ARGUMENT); + + git_repository_free(repo); + git_libgit2_shutdown(); + printf("OK\n"); + return 0; +} diff --git a/core/tests/unit/test_cache_tree_size.c b/core/tests/unit/test_cache_tree_size.c new file mode 100644 index 00000000..66199dce --- /dev/null +++ b/core/tests/unit/test_cache_tree_size.c @@ -0,0 +1,91 @@ +/* SPDX-License-Identifier: LicenseRef-MIND-UCAL-1.0 */ +/* © 2025 J. Kirby Ross / Neuroglyph Collective */ + +#include +#include +#include + +#include + +#include "gitmind/error.h" + +int gm_cache_calculate_size(git_repository *repo, const git_oid *tree_oid, + uint64_t *size_bytes); + +static size_t object_size(git_repository *repo, const git_oid *oid) { + git_odb *odb = NULL; + git_odb_object *obj = NULL; + int rc = git_repository_odb(&odb, repo); + assert(rc == 0); + rc = git_odb_read(&obj, odb, oid); + git_odb_free(odb); + assert(rc == 0 && obj != NULL); + size_t size = git_odb_object_size(obj); + git_odb_object_free(obj); + return size; +} + +int main(void) { + printf("test_cache_tree_size... "); + git_libgit2_init(); + + git_repository *repo = NULL; + int rc = git_repository_init(&repo, "./.gm_cache_tree_tmp", true); + assert(rc == 0 && repo); + + const char *root_content = "root"; + const char *nested_content = "nested-data"; + + git_oid root_blob_oid; + rc = git_blob_create_frombuffer(&root_blob_oid, repo, + root_content, strlen(root_content)); + assert(rc == 0); + + git_oid nested_blob_oid; + rc = git_blob_create_frombuffer(&nested_blob_oid, repo, + nested_content, strlen(nested_content)); + assert(rc == 0); + + /* Build nested tree */ + git_treebuilder *tb = NULL; + git_oid nested_tree_oid; + rc = git_treebuilder_new(&tb, repo, NULL); + assert(rc == 0); + rc = git_treebuilder_insert(NULL, tb, "nested.txt", &nested_blob_oid, + GIT_FILEMODE_BLOB); + assert(rc == 0); + rc = git_treebuilder_write(&nested_tree_oid, tb); + git_treebuilder_free(tb); + assert(rc == 0); + + /* Build root tree */ + rc = git_treebuilder_new(&tb, repo, NULL); + assert(rc == 0); + rc = git_treebuilder_insert(NULL, tb, "root.txt", &root_blob_oid, + GIT_FILEMODE_BLOB); + assert(rc == 0); + rc = git_treebuilder_insert(NULL, tb, "nested", &nested_tree_oid, + GIT_FILEMODE_TREE); + assert(rc == 0); + git_oid root_tree_oid; + rc = git_treebuilder_write(&root_tree_oid, tb); + git_treebuilder_free(tb); + assert(rc == 0); + + uint64_t total = 0; + rc = gm_cache_calculate_size(repo, &root_tree_oid, &total); + assert(rc == GM_OK); + + size_t expected = 0; + expected += object_size(repo, &root_tree_oid); + expected += object_size(repo, &nested_tree_oid); + expected += object_size(repo, &root_blob_oid); + expected += object_size(repo, &nested_blob_oid); + + assert(total == (uint64_t)expected); + + git_repository_free(repo); + git_libgit2_shutdown(); + printf("OK\n"); + return 0; +} diff --git a/docs/features/Features_Ledger.md b/docs/features/Features_Ledger.md index 73faf789..8d2560ad 100644 --- a/docs/features/Features_Ledger.md +++ b/docs/features/Features_Ledger.md @@ -151,7 +151,7 @@ features=8 | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | 🧱 | OID‑first Core | Core | — | core/include, core/src | v1.0.0 | 3.5 | Alpha | 85% | █████████░ | Equality OID‑first; OID fields in CBOR; cache/journal aligned. | Finalize strict equality; docs complete. | Unit passing | Good foundation. | | 🗄️ | Journal (CBOR) | Core | docs/architecture/journal-architecture-pivot.md | core/src/journal, core/src/cbor | Alpha | 1.2 | Alpha | 80% | ████████░░ | Writer/reader with base64; debug flag; attributed edges. | Finalize ordering; more tests. | Unit passing | Backwards compat OK. | -| ⚡ | Cache (Bitmap) | Core | docs/architecture/bitmap-cache-design.md | core/src/cache | Alpha | 1.6 | In Progress | 70% | ███████░░░ | Rebuild + query; shard; metadata. | Conformance tests; size calc. | Unit partial | Performance tuning next. | +| ⚡ | Cache (Bitmap) | Core | docs/architecture/bitmap-cache-design.md | core/src/cache | Alpha | 1.6 | In Progress | 75% | ███████░░░ | Rebuild + query; shard; metadata. | Perf tuning + shard benchmarks. | Unit partial | Added branch-limit + tree-size coverage. | | 🔗 | Ref Utilities | Core | docs/architecture/Ref_Name_Validation.md | core/src/util | MVP | 0.5 | MVP | 75% | ███████░░░ | `gm_build_ref` with validation; tests. | More negative tests; docs link. | Unit | Good coverage. | | 🧰 | Safe String/Memory | Core | — | core/include/gitmind/util | v1.0.0 | 0.4 | V1 | 90% | █████████░ | Safe wrappers adopted in hot paths. | Sweep stragglers; docs. | Unit | Security uplift. | | 🕸️ | Edge Graph Engine | Core | docs/architecture/System_Architecture.md | core/src/edge, core/include/gitmind/edge | Alpha | 1.0 | Alpha | 75% | ████████░░ | ULID-ordered edges; journal append + cache hydration. | Edge diff coverage; multi-branch stress. | Unit + fuzz | Forms graph spine. | @@ -202,7 +202,7 @@ features=3 > [!INFO]- > Update comparisons and tests; align cache/journal; document in TECHNICAL.md. -- [ ] [Alpha] Finalize bitmap cache conformance tests +- [x] [Alpha] Finalize bitmap cache conformance tests > [!INFO]- > Build synthetic repos; verify shard distribution and size calculations; add docs. diff --git a/meson.build b/meson.build index 78e5780a..17de18fc 100644 --- a/meson.build +++ b/meson.build @@ -283,6 +283,12 @@ test_cache_query = executable('test_cache_query', link_with : libgitmind, dependencies : [libsodium_dep, libgit2_dep, thread_dep]) +test_cache_branch_limits = executable('test_cache_branch_limits', + 'core/tests/unit/test_cache_branch_limits.c', + include_directories : inc, + link_with : libgitmind, + dependencies : [libsodium_dep, libgit2_dep, thread_dep]) + test_journal_safety = executable('test_journal_safety', 'core/tests/unit/test_journal_safety.c', include_directories : inc, @@ -295,6 +301,12 @@ test_cache_shard_distribution = executable('test_cache_shard_distribution', link_with : libgitmind, dependencies : [libsodium_dep, libgit2_dep, thread_dep]) +test_cache_tree_size = executable('test_cache_tree_size', + 'core/tests/unit/test_cache_tree_size.c', + include_directories : inc, + link_with : libgitmind, + dependencies : [libsodium_dep, libgit2_dep, thread_dep]) + test_edge_oid_fallback = executable('test_edge_oid_fallback', 'core/tests/unit/test_edge_oid_fallback.c', include_directories : inc, @@ -328,8 +340,10 @@ test('edge_equal_semantics', test_edge_equal_semantics) test('cache_meta', test_cache_meta) test('journal_mixed_cbor', test_journal_mixed_cbor) test('cache_query', test_cache_query) +test('cache_branch_limits', test_cache_branch_limits) test('journal_safety', test_journal_safety) test('cache_shard_distribution', test_cache_shard_distribution) +test('cache_tree_size', test_cache_tree_size) test('edge_oid_fallback', test_edge_oid_fallback) test('ref_utils', test_ref_utils) From 20a17d16be8844749ce755afeb36f7e9db9d59c2 Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Wed, 17 Sep 2025 20:28:19 -0700 Subject: [PATCH 35/42] docs: propose sandbox transaction blocks --- docs/talk-shop/Sandbox_Transactions.md | 99 ++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 docs/talk-shop/Sandbox_Transactions.md diff --git a/docs/talk-shop/Sandbox_Transactions.md b/docs/talk-shop/Sandbox_Transactions.md new file mode 100644 index 00000000..9fb34395 --- /dev/null +++ b/docs/talk-shop/Sandbox_Transactions.md @@ -0,0 +1,99 @@ +--- +title: Sandbox Transaction Blocks +description: RFC to stage git-mind graph mutations inside inspectable transaction branches before committing to the journal. +audience: [contributors] +domain: [architecture] +tags: [journal, workflow, sandbox] +status: draft +last_updated: 2025-09-17 +--- + +# Sandbox Transaction Blocks + +## Why + +As we migrate fully into `core/` and tighten our conformance tests, the next friction point is confidence in graph mutations. Contributors (humans, plugins, or AI helpers) often want to queue a series of edges, inspect the result, then decide whether to land it. Today the only options are: + +- append directly to `refs/gitmind/edges/` and hope CI catches bad edges later +- hand-roll temporary refs and clean them up manually +- bypass the hooks with `HOOKS_BYPASS=1` + +We can do better by giving every mutation a sandboxed transaction. + +## Goals + +- **Preview first** – let devs and tools see exactly what a batch of edges will do before touching the canonical refs. +- **Make journaling safe** – journal entries authored in a transaction never appear in the main DAG until applied. +- **Shareable drafts** – a transaction should be easy to hand off (txn ID/ref), so reviewers can inspect deltas without bespoke tooling. +- **Integrate with cache rebuilds** – transaction refs must be invisible to cache/journal consumers unless explicitly targeted. +- **Zero surprise for CI** – transactions that were never applied should not affect builds/tests. + +Non-goals for the first iteration: multi-user locking, conflict resolution UI, or automatic rebase of transactions during apply. + +## Proposed Design + +### Ref Layout + +``` +refs/gitmind/ + edges/ # canonical journal + pending/ # sandbox transaction refs + applied/ # (optional) archive for auditing +``` + +- Transaction IDs are ULIDs; metadata stored under `refs/gitmind/pending//meta`. +- Payload edges live under `refs/gitmind/pending//edges/` mirroring the canonical layout so reuse is easy. + +### CLI Flow + +1. `git mind txn start [--branch main]` → returns txn ID, records base journal OID. +2. Subsequent `git mind link/list/...` commands operate inside the transaction by default (reads merge pending + canonical, writes hit pending). +3. `git mind txn show [--format table|json|diff]` renders edges staged in the transaction. +4. Users choose `git mind txn apply [--branch main]` or `git mind txn abort`. + +### Apply Logic + +- Collect pending commits for ``. +- Confirm the canonical journal tip still equals the recorded base OID (fast-forward); else replay on top (append new commits). +- Update `refs/gitmind/edges/` and move the transaction ref under `refs/gitmind/applied/` (or delete if retention not needed). +- Trigger cache rebuild hooks or mark the cache dirty if the branch matches current context. + +### Abort Logic + +- Drop the pending ref; the CLI should refuse to abort if the transaction was already applied to avoid footguns. + +### Concurrency / Conflicts + +- If the canonical ref moved while the transaction was active, we replay the edges as fresh commits: read CBOR payloads, re-run append logic, and create new journal commits. +- If replay encounters conflicts (duplicate ULIDs, incompatible schema), we surface the errors before applying. + +### Hooks & Tests + +- Hooks (pre-push) should whitelist pending refs or ignore them entirely. +- Unit tests for `gm_journal` should ensure reads can accept a transaction ref override (`gm_journal_read_txn(ctx, txn_id, ...)`). +- E2E: script that starts a transaction, stages edges, aborts, verifies canonical journal unchanged; then repeat with apply and validate. + +## Implementation Phases + +1. **Scaffold** – add `gm_txn_*` helpers (start/apply/abort) that manipulate Git refs only; no CLI surface yet. +2. **CLI Preview** – wire `git mind txn` commands, default writes to a transaction when `GITMIND_TXN_ID` is set (useful for `make ci-local` test harnesses). +3. **Opt-in Auto-Txn** – add `--txn` flag to commands, environment variable for automation, and docs for contributors. +4. **Enforce Default** – eventually, disallow direct journal writes outside of a transaction unless `--apply` is passed explicitly (with a hook guard). + +## Open Questions / Feedback Needed + +- **Transaction retention** – do we keep applied transactions under `refs/gitmind/applied/` for audit trails, or rely on Git history only? +- **CI strategy** – should CI automatically apply transactions (and roll back) to run tests, or do we rely on developers applying manually first? +- **Integration with review seeding** – can CodeRabbit or the worksheet flow respond to transaction comments when edges are applied? +- **Merge tool** – do we want a `gm mind txn rebase` to restack the transaction on a new base before applying? +- **Security** – do we need ACLs to prevent transactions from referencing other users’ pending refs (e.g., namespace by user)? + +## Related Work + +- `docs/features/Features_Ledger.md` (new tasks around cache/journal confidence) +- `docs/talk-shop/Graph-Lvl-Up-Tank.md` (journey node + transaction storytelling) +- Existing cache conformance tests and the recently added branch/tree coverage (`core/tests/unit/test_cache_branch_limits.c`, `test_cache_tree_size.c`) + +--- + +Feedback welcome, especially on apply semantics and how strict we want to be before promoting transactions to canonical refs. From 222dd1f79484bfb8aa2e50212d31913c153b9c6f Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Wed, 17 Sep 2025 21:11:00 -0700 Subject: [PATCH 36/42] docs: refine sandbox transactions rfc --- docs/talk-shop/Sandbox_Transactions.md | 49 ++++++++++++++++---------- 1 file changed, 30 insertions(+), 19 deletions(-) diff --git a/docs/talk-shop/Sandbox_Transactions.md b/docs/talk-shop/Sandbox_Transactions.md index 9fb34395..b5485f03 100644 --- a/docs/talk-shop/Sandbox_Transactions.md +++ b/docs/talk-shop/Sandbox_Transactions.md @@ -36,26 +36,30 @@ Non-goals for the first iteration: multi-user locking, conflict resolution UI, o ``` refs/gitmind/ - edges/ # canonical journal - pending/ # sandbox transaction refs - applied/ # (optional) archive for auditing + edges/ # canonical journal + pending///edges/ # sandbox transactions (namespaced) + pending///meta # json metadata for the txn + applied/ # optional archival pointer ``` -- Transaction IDs are ULIDs; metadata stored under `refs/gitmind/pending//meta`. -- Payload edges live under `refs/gitmind/pending//edges/` mirroring the canonical layout so reuse is easy. +- Transactions are ULID-keyed and namespaced by the author (CLI derives `` from git config or `GITMIND_TXN_NAMESPACE`). This prevents cross-claiming someone else’s sandbox. +- Metadata (JSON) records author, branch target, base journal OID, start time, edge-count hash, and applied-by provenance. Payload edges mirror the canonical layout so replay logic can reuse existing helpers. ### CLI Flow 1. `git mind txn start [--branch main]` → returns txn ID, records base journal OID. 2. Subsequent `git mind link/list/...` commands operate inside the transaction by default (reads merge pending + canonical, writes hit pending). 3. `git mind txn show [--format table|json|diff]` renders edges staged in the transaction. -4. Users choose `git mind txn apply [--branch main]` or `git mind txn abort`. +4. Users choose `git mind txn apply [--branch main]` (alias: `txn commit`) or `git mind txn abort`. + +`git mind txn show --format diff` is the default preview; `--dry-run` performs the apply simulation without mutating refs (useful for CI or pre-review). ### Apply Logic - Collect pending commits for ``. -- Confirm the canonical journal tip still equals the recorded base OID (fast-forward); else replay on top (append new commits). -- Update `refs/gitmind/edges/` and move the transaction ref under `refs/gitmind/applied/` (or delete if retention not needed). +- Confirm the canonical journal tip still equals the recorded base OID (fast-forward); else replay on top (append new commits) and surface schema/ULID conflicts loudly. +- Stamp the apply commit with trailers (`Gm-Txn:` and `Gm-Apply:`) for provenance. +- Update `refs/gitmind/edges/` and move the transaction ref under `refs/gitmind/applied/` (retention policy below) or prune it if configured. - Trigger cache rebuild hooks or mark the cache dirty if the branch matches current context. ### Abort Logic @@ -69,24 +73,31 @@ refs/gitmind/ ### Hooks & Tests -- Hooks (pre-push) should whitelist pending refs or ignore them entirely. +- Local hooks (pre-push) should block accidental pushes of `refs/gitmind/pending/*` unless an override flag is set; server-side hooks enforce trailers on canonical refs and optionally auto-archive transactions (see worked example in `Sandbox_Transactions_Feedback.md`). - Unit tests for `gm_journal` should ensure reads can accept a transaction ref override (`gm_journal_read_txn(ctx, txn_id, ...)`). - E2E: script that starts a transaction, stages edges, aborts, verifies canonical journal unchanged; then repeat with apply and validate. ## Implementation Phases 1. **Scaffold** – add `gm_txn_*` helpers (start/apply/abort) that manipulate Git refs only; no CLI surface yet. -2. **CLI Preview** – wire `git mind txn` commands, default writes to a transaction when `GITMIND_TXN_ID` is set (useful for `make ci-local` test harnesses). -3. **Opt-in Auto-Txn** – add `--txn` flag to commands, environment variable for automation, and docs for contributors. -4. **Enforce Default** – eventually, disallow direct journal writes outside of a transaction unless `--apply` is passed explicitly (with a hook guard). +2. **CLI Preview** – wire `git mind txn` commands, default writes to a transaction when `GITMIND_TXN_ID` is set (useful for `make ci-local` harnesses). +3. **Opt-in Auto-Txn** – add `--txn` flag, environment variable, and docs. CI remains “apply-only”; developers manually apply before running pipelines. +4. **Retention + Enforcement** – implement configurable retention (`git config gitmind.txn.retention=keep|days=|delete`) and disallow direct journal writes outside of a transaction unless `--apply` is passed explicitly (with a hook guard). + +Default retention proposal: + +- Pending refs are pruned automatically on abort. +- Applied refs are archived under `refs/gitmind/applied/` for 14 days by default, overridden via config or `git mind txn apply --no-archive`. +- A periodic `git mind txn gc` command prunes expired archives. -## Open Questions / Feedback Needed +## Decisions & Remaining Questions -- **Transaction retention** – do we keep applied transactions under `refs/gitmind/applied/` for audit trails, or rely on Git history only? -- **CI strategy** – should CI automatically apply transactions (and roll back) to run tests, or do we rely on developers applying manually first? -- **Integration with review seeding** – can CodeRabbit or the worksheet flow respond to transaction comments when edges are applied? -- **Merge tool** – do we want a `gm mind txn rebase` to restack the transaction on a new base before applying? -- **Security** – do we need ACLs to prevent transactions from referencing other users’ pending refs (e.g., namespace by user)? +- ✅ **Retention** — archive applied transactions for 14 days by default with `gitmind.txn.retention` override; pending refs auto-pruned on abort/apply. +- ✅ **CI strategy** — CI remains “apply-only”; pipelines fail fast if pending refs are pushed. Developers must apply (or use dry-run apply locally) before running `make ci-local`. +- ✅ **Namespaces & metadata** — each transaction stores author, base OID, branch, start time, edge digest, and apply provenance; refs are namespaced by actor. +- ✅ **Replay semantics** — schema violations or duplicate ULIDs abort apply. No silent skipping; users fix the transaction then re-apply. +- ❓ **Review tooling** — explore integrating transaction IDs into worksheet/review seeding so bots can comment before apply. +- ❓ **Rebase support** — evaluate need for `git mind txn rebase` once transactions are in heavy use. ## Related Work @@ -96,4 +107,4 @@ refs/gitmind/ --- -Feedback welcome, especially on apply semantics and how strict we want to be before promoting transactions to canonical refs. +Feedback welcome—especially on the remaining review/rebase questions. A worked end-to-end example (including hook snippets) lives in `docs/talk-shop/Sandbox_Transactions_Feedback.md` for quick reference. From 0cf63a92b12e8eea39304e180edd659e3166bbf0 Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Wed, 17 Sep 2025 21:11:48 -0700 Subject: [PATCH 37/42] docs: capture feedback on sandbox transactions --- .../Sandbox_Transactions_Feedback.md | 699 ++++++++++++++++++ 1 file changed, 699 insertions(+) create mode 100644 docs/talk-shop/Sandbox_Transactions_Feedback.md diff --git a/docs/talk-shop/Sandbox_Transactions_Feedback.md b/docs/talk-shop/Sandbox_Transactions_Feedback.md new file mode 100644 index 00000000..53a4326a --- /dev/null +++ b/docs/talk-shop/Sandbox_Transactions_Feedback.md @@ -0,0 +1,699 @@ +# A structured RFC review of your Sandbox Transaction Blocks draft + +Here's what’s solid, what needs tightening, and a few extra sharp edges you might want to grind down before calling it “ready.” + +## Strengths + +• Clear motivation – You nailed the “why.” Current friction points are well-explained (manual refs, bypass flags, CI catching things too late). That grounds the proposal in contributor pain. +• Concrete goals – Each goal maps to a real workflow: preview, journaling safety, shareability, cache isolation, CI hygiene. Good scoping (no UI/rebase in v1). +• Ref layout sketch – Showing pending/ and applied/ alongside canonical is clean, Git-idiomatic, and composable. +• CLI flow – The numbered workflow (txn start → operate → show → apply/abort) reads intuitive. Good developer ergonomics. +• Apply/abort semantics – Covers fast-forward expectations, replay logic, and error surfacing. That’s the hardest part and you’ve already drawn the boundaries. +• Testing hooks – Explicit mention of both unit and E2E tests at this stage is solid discipline. + +## Weak Spots / Risks + +• Ref explosion – Every transaction spawns a ref subtree. Without a cleanup strategy, you’ll drown in pending/ and applied/ clutter. Right now you punt on retention. +• Rebase/replay cost – Replay edge CBOR payloads on schema drift is non-trivial. You call it “re-run append logic,” but that may need its own test suite (duplicate ULIDs vs. schema version bumps are very different beasts). +• Cache invisibility – You say “must be invisible unless explicitly targeted,” but don’t outline how consumers distinguish. A flag in gm_journal_read_txn is fine, but you’ll need guardrails so rogue readers don’t accidentally pull pending refs. +• Concurrency model – No multi-user locking is fine for v1, but you should acknowledge the risk of racey concurrent applies. Without at least a warning system, two contributors could both “fast-forward” in their own heads and then clobber. +• CI semantics – It’s fuzzy whether CI should (a) always ignore pending refs, (b) run tests only on applied, or (c) optionally simulate applying pending. Needs a decision, not just an open question. + +## Suggestions / Additions + +• Retention knobs – Decide early: +• Default = applied refs get GC’d after X days, + Opt-in = keep forever for audit, +• Configurable = git config gitmind.txn.retention=keep|prune|days. +• Namespace isolation – To address your own security open question, prefix refs/gitmind/pending//; avoids accidental cross-claiming of someone else’s txn. +• Transaction metadata – ULID is good, but include at least: author, start time, base OID, branch target, maybe hash of staged payloads. Makes audits and replay debugging saner. +• “Dry-run apply” mode – Before doing the irreversible, let the CLI show exactly what edges will be appended if applied now (like git rebase --show-current-patch). +• CLI ergonomics – Consider git mind txn commit (synonym for apply) so the git muscle memory flows naturally. +• Hooks – Explicitly note that pre-push/pre-commit should ignore pending/ by default, to stop confusion. + +## Open Questions (Reframed) + +1. Retention – Are applied transactions first-class audit artifacts or temporary scaffolding? Decide now, else you’ll regret dangling refs. +2. CI role – Do you want CI to simulate transactions (auto-apply + rollback), or force devs to apply first? My take: start with manual apply only, else CI semantics balloon. +3. Security – Is namespacing enough, or do you need RLS-like ACLs for multi-user repos? For single-user local use, probably overkill. +4. Replay semantics – Are schema errors fatal (abort apply) or recoverable (skip edge)? Define strictness before contributors start relying on undefined behavior. + +## Verdict + +Great draft. The bones are strong: you’ve got a git-native layout, intuitive CLI, and clear apply/abort semantics. The two dragons ahead are retention sprawl and CI ambiguity. Solve those, and v1 is both achievable and useful. + +## A Worked Example + +I wrote it in narrative CLI style so contributors can see the whole lifecycle without reading walls of prose. + +### Worked Example: Transaction Lifecycle + +#### 1. Start a transaction + +Create a sandbox to stage edges against main. + +```bash +$ git mind txn start --branch main +txn started: 01J7A3S5J0B9QHY1TG8RZVZPWF +base: 9f3c12a (refs/gitmind/edges/main) +``` + +This creates refs under: + +```bash +refs/gitmind/pending/01J7A3S5J0B9QHY1TG8RZVZPWF/ + meta + edges/main +``` + +#### 2. Stage edges inside the transaction + +All git mind commands now write to the pending ref (not canonical). + +```bash +$ git mind link A B --rel depends_on +$ git mind link B C --rel implements +``` + +The canonical journal (`edges/main`) is untouched. + +#### 3. Inspect staged changes + +Preview what would land if applied now. + +```bash +$ git mind txn show --format diff ++ edge A → B (depends_on) ++ edge B → C (implements) +``` + +You can also dump JSON for programmatic review: + +```bash +$ git mind txn show --format json > txn-review.json +``` + +### 4. Abort (optional) + +If you decide the batch is junk: + +```bash +$ git mind txn abort 01J7A3S5J0B9QHY1TG8RZVZPWF +txn aborted; pending refs removed +``` + +The canonical journal remains unchanged. + +### 5. Apply (happy path) + +If the batch looks good: + +```bash +$ git mind txn apply 01J7A3S5J0B9QHY1TG8RZVZPWF +applied to refs/gitmind/edges/main at 9f3c12a → 5c7d9be +archived under refs/gitmind/applied/01J7A3S5J0B9QHY1TG8RZVZPWF +``` + +Now `edges/main` has the two new commits, and the transaction is archived. + +### 6. What if main moved? + +If someone else updated the journal in the meantime: + +```bash +$ git mind txn apply 01J7A3S5J0B9QHY1TG8RZVZPWF +base mismatch (expected 9f3c12a, found e4d2b71) +→ replaying edges… +→ appended new commits cleanly +applied at e4d2b71 → 8a9f11c +``` + +The tool transparently replays CBOR payloads on top of the new tip. +Conflicts (e.g. duplicate ULIDs) surface before finalizing. + +That’s the whole dance: start → stage → show → abort/apply → archive. + +## A mock meta file + +To show contributors what lives under `refs/gitmind/pending//meta`. I kept it in CBOR-friendly JSON, since that’s what your edges already use. + +### Example: Transaction Metadata + +```json +{ + "txn_id": "01J7A3S5J0B9QHY1TG8RZVZPWF", // ULID for uniqueness + sort order + "author": { + "name": "J. Kirby Ross", + "email": "james@flyingrobots.dev" + }, + "branch": "main", // target journal branch + "base_oid": "9f3c12a", // OID of journal head at txn start + "created_at": "2025-09-17T20:41:12Z", // ISO8601 timestamp + "applied_at": null, // set once txn applied + "status": "pending", // pending | applied | aborted + "edge_count": 2, // count of staged edges + "hash": "sha256-0f9f1c2...", // hash of all staged edge payloads + "notes": "Initial draft links A→B, B→C" // optional freeform field +} +``` + +### Notes + +• txn_id – ULID makes it sortable and globally unique. +• base_oid – allows fast-forward check before apply. +• hash – gives you immutability; lets CI verify payload integrity. +• status – a single field for lifecycle transitions. +• applied_at – stays null until applied; doubles as audit trail if you archive. +• notes – cheap way to let humans drop a comment. + +## Sketch of a minimal schema/validation ruleset + +Think: like a JSON Schema or CBOR schema, so contributors can’t bikeshed later about what’s “required” vs. “optional”? That way you bake enforcement right into phase 1. + +A tight, opinionated JSON Schema + ruleset for `refs/gitmind/pending//meta`. Drop this straight into the RFC. + +### Transaction Metadata Schema & Validation + +``` +File: schemas/gitmind.txn.meta.schema.json +Purpose: Enforce a minimal, durable contract for transaction audit data. +Format: JSON (CBOR-encoded on disk is fine; schema targets the JSON model). +``` + +### JSON Schema (Draft 2020-12) + +```json +{ + "$id": "https://gitmind.dev/schemas/gitmind.txn.meta.schema.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "GitMind Transaction Metadata", + "type": "object", + "additionalProperties": false, + "required": [ + "version", + "txn_id", + "author", + "branch", + "base_oid", + "created_at", + "status", + "edge_count", + "hash" + ], + "properties": { + "version": { + "description": "Schema payload version for meta format.", + "type": "string", + "pattern": "^1\\.0\\.0$" + }, + "txn_id": { + "description": "ULID for uniqueness and sortability.", + "type": "string", + "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" + }, + "author": { + "type": "object", + "additionalProperties": false, + "required": ["name", "email"], + "properties": { + "name": { "type": "string", "minLength": 1, "maxLength": 200 }, + "email": { "type": "string", "format": "email", "maxLength": 320 } + } + }, + "branch": { + "description": "Target journal branch (e.g., main).", + "type": "string", + "minLength": 1, + "maxLength": 200, + "pattern": "^[A-Za-z0-9._/\\-]+$" + }, + "base_oid": { + "description": "OID of refs/gitmind/edges/ at txn start.", + "type": "string", + "pattern": "^[0-9a-f]{7,40}$" + }, + "created_at": { + "description": "ISO8601 UTC timestamp when txn started.", + "type": "string", + "format": "date-time" + }, + "applied_at": { + "description": "ISO8601 UTC timestamp when txn applied (nullable until applied).", + "type": ["string", "null"], + "format": "date-time" + }, + "aborted_at": { + "description": "ISO8601 UTC timestamp when txn aborted (nullable until aborted).", + "type": ["string", "null"], + "format": "date-time" + }, + "status": { + "description": "Lifecycle state.", + "type": "string", + "enum": ["pending", "applied", "aborted"] + }, + "edge_count": { + "description": "Number of staged edges in txn.", + "type": "integer", + "minimum": 0 + }, + "hash": { + "description": "Deterministic hash of staged edge payloads.", + "type": "string", + "pattern": "^sha256-[0-9a-f]{64}$" + }, + "notes": { + "description": "Optional human note.", + "type": "string", + "maxLength": 1000 + }, + "namespace": { + "description": "User/actor namespace for isolation (recommended).", + "type": "string", + "maxLength": 120, + "pattern": "^[A-Za-z0-9._/\\-]+$" + }, + "provenance": { + "description": "Where this txn originated.", + "type": "object", + "additionalProperties": false, + "required": ["tool", "tool_version"], + "properties": { + "tool": { "type": "string", "minLength": 1, "maxLength": 120 }, + "tool_version": { "type": "string", "minLength": 1, "maxLength": 60 }, + "host": { "type": "string", "maxLength": 255 }, + "pid": { "type": "integer", "minimum": 0 } + } + }, + "replay_policy": { + "description": "Behavior if base moved or duplicates appear.", + "type": "string", + "enum": ["strict", "skip-duplicates", "best-effort"], + "default": "strict" + }, + "retention": { + "description": "Archival preference after apply/abort.", + "type": "string", + "enum": ["keep", "prune", "days-7", "days-30", "days-90"], + "default": "days-30" + }, + "labels": { + "description": "Freeform labels for filtering/search.", + "type": "array", + "items": { "type": "string", "minLength": 1, "maxLength": 40 }, + "maxItems": 16, + "uniqueItems": true + } + }, + "allOf": [ + { + "if": { "properties": { "status": { "const": "pending" } } }, + "then": { + "properties": { "applied_at": { "type": "null" }, "aborted_at": { "type": "null" } } + } + }, + { + "if": { "properties": { "status": { "const": "applied" } } }, + "then": { + "required": ["applied_at"], + "properties": { "aborted_at": { "type": "null" } } + } + }, + { + "if": { "properties": { "status": { "const": "aborted" } } }, + "then": { + "required": ["aborted_at"], + "properties": { "applied_at": { "type": "null" } } + } + } + ] +} +``` + +### Deterministic Hash Rule (normative) + +``` +hash = "sha256-" + sha256_hex(concat(edge_hashes_sorted)) +``` + +• edge_hashes_sorted: list of sha256_hex of each staged edge’s canonical JSON payload (no whitespace; keys sorted lexicographically; UTF-8). +• Sort the per-edge hashes lexicographically before concatenation. +• This makes hash independent of edge insertion order. + +### Invariants (must hold) + +• I1: txn_id is immutable after creation. +• I2: If status == "applied", applied_at != null and aborted_at == null. +• I3: If status == "aborted", aborted_at != null and applied_at == null. +• I4: created_at <= applied_at|aborted_at (when present). +• I5: edge_count equals the number of staged edge commits under pending//edges/. +• I6: base_oid must have been the tip of refs/gitmind/edges/ at created_at (enforced at txn start). +• I7: hash must verify against current staged edges before apply. +• I8 (namespace, recommended): pending// is the ref path if namespace is set; otherwise pending/. + +### Validation Strategy + +• Schema validation: run on txn start, txn show, and always on txn apply. +• Hash verification: recompute hash from staged edges before apply. +• Base guard: on apply, if HEAD(edges/) != base_oid, follow replay_policy: +• strict → fail with GM_TXN_BASE_MOVED +• skip-duplicates → replay non-duplicate edges; fail on schema errors +• best-effort → attempt replay; warn on skips; still fail on invariants + +### Error Codes (don’t be cute; be specific) + +• GM_TXN_SCHEMA_INVALID – meta failed JSON Schema validation +• GM_TXN_HASH_MISMATCH – staged edges don’t match hash +• GM_TXN_BASE_MOVED – fast-forward check failed (and policy is strict) +• GM_TXN_REPLAY_CONFLICT – duplicate ULIDs or schema incompatibility during replay +• GM_TXN_STATUS_IMMUTABLE – illegal status transition (e.g., applied → pending) +• GM_TXN_ID_IMMUTABLE – attempt to mutate txn_id +• GM_TXN_ABORT_APPLIED – refuse to abort an already-applied txn +• GM_TXN_NOT_FOUND – unknown txn_id / missing ref subtree + +#### Example Valid Meta (compact JSON) + +```json +{ + "version": "1.0.0", + "txn_id": "01J7A3S5J0B9QHY1TG8RZVZPWF", + "author": { "name": "J. Kirby Ross", "email": "james@flyingrobots.dev" }, + "branch": "main", + "base_oid": "9f3c12a", + "created_at": "2025-09-17T20:41:12Z", + "applied_at": null, + "aborted_at": null, + "status": "pending", + "edge_count": 2, + "hash": "sha256 -0f9f1c2d5e1b4a39d8ff1a2c3b4c5d6e7f8a9b0c1d2e3f405162738495aabbcc".replace(" ", ""), + "notes": "Initial draft links A→B, B→C", + "namespace": "flyingrobots", + "provenance": { "tool": "git-mind-cli", "tool_version": "0.7.0", "host": "seattle-dev-01", "pid": 23142 }, + "replay_policy": "strict", + "retention": "days-30", + "labels": ["preview", "ai-seeded"] +} +``` + +### CLI Enforcement Hooks (quick spec) + +• txn start +• Create meta with status=pending; validate against schema. +• txn show +• Validate meta; recalc edge_count; warn on mismatch. +• txn apply +• Validate meta → verify hash → base guard (+ policy) → apply → set applied_at, status=applied, move to applied/ or GC per retention. +• txn abort +• Refuse if status=applied; otherwise set status=aborted, aborted_at=now, then prune per retention. + +### Back/Forward Compatibility + +• Freeze this as version: "1.0.0". +• Future changes must bump version and keep 1.x readers tolerant of additional fields (but never missing requireds). +• Don’t repurpose fields. Add new ones and bump. + +Up next, I write a 10-line ajv/jq preflight snippet for make ci-local that validates meta + recomputes the deterministic hash before letting tests run. + +## CI preflight snippet you can wire into make ci-local (or any test harness) + +It validates meta against the JSON Schema and recomputes the deterministic hash before proceeding. + +### scripts/check-txn-meta.sh + +```bash +#!/usr/bin/env bash +set -euo pipefail + +META_FILE="$1" +EDGES_DIR="$2" # path to staged edges JSON/CBOR payloads + +SCHEMA="schemas/gitmind.txn.meta.schema.json" + +# 1. JSON Schema validation +echo "[gm-txn] validating $META_FILE against $SCHEMA..." +npx ajv-cli validate -s "$SCHEMA" -d "$META_FILE" --spec=draft2020 > /dev/null + +# 2. Recompute deterministic hash of staged edges +TMP_HASHES=$(mktemp) +for edge in "$EDGES_DIR"/*.json; do + jq -cS . "$edge" | sha256sum | awk '{print $1}' >> "$TMP_HASHES" +done + +SORTED=$(sort "$TMP_HASHES" | tr -d '\n') +RECALC="sha256-$(echo -n "$SORTED" | sha256sum | awk '{print $1}')" +rm "$TMP_HASHES" + +# 3. Compare with meta.hash +META_HASH=$(jq -r .hash "$META_FILE") + +if [[ "$META_HASH" != "$RECALC" ]]; then + echo "[gm-txn] ERROR: hash mismatch" + echo " expected: $META_HASH" + echo " actual: $RECALC" + exit 1 +fi + +echo "[gm-txn] OK: $META_FILE valid and hash verified" +``` + +### Usage + +```bash +# Validate pending txn 01J7A3S5... +./scripts/check-txn-meta.sh \ + .git/refs/gitmind/pending/01J7A3S5J0B9QHY1TG8RZVZPWF/meta \ + .git/refs/gitmind/pending/01J7A3S5J0B9QHY1TG8RZVZPWF/edges/main +``` + +This ensures every transaction in CI: + +• Conforms to schema (ajv-cli). +• Matches its deterministic payload hash (order-independent). + +Here’s the hook wiring so nobody “helpfully” yeets half-baked transactions upstream. Drop-in scripts, minimal ceremony, maximal guardrails. + +## Git Hooks for Sandbox Transactions + +### 1) Enable local hooks once + +```bash +git config core.hooksPath .githooks +mkdir -p .githooks scripts +``` + +Assumes you already saved the earlier scripts/check-txn-meta.sh. + +### 2) Client-side pre-push + +Block pushing pending/ by default and validate any txn meta/hash if someone does opt-in. + +#### File: .githooks/pre-push (chmod +x) + +```bash +#!/usr/bin/env bash +set -euo pipefail + +REMOTE_NAME="$1"; REMOTE_URL="$2" || true + +# Env switches: +# PUSH_PENDING=1 -> allow pushing refs/gitmind/pending/* +# GM_TXN_STRICT=1 -> also validate meta/hash for applied txns by scanning push set +# Paths: +CHECK_SCRIPT="scripts/check-txn-meta.sh" + +echo "[pre-push] scanning refs about to push to $REMOTE_NAME ($REMOTE_URL)" + +# read lines: +PENDING_SEEN=0 +APPLIED_SEEN=0 +while read -r LOCAL_SHA LOCAL_REF REMOTE_SHA REMOTE_REF; do + [[ -z "${LOCAL_REF:-}" ]] && continue + + if [[ "$LOCAL_REF" =~ ^refs/gitmind/pending/ ]]; then + PENDING_SEEN=1 + if [[ "${PUSH_PENDING:-0}" != "1" ]]; then + echo "[pre-push] ERROR: refusing to push pending transaction refs:" + echo " $LOCAL_REF" + echo " (set PUSH_PENDING=1 to intentionally publish pending refs for review)" + exit 1 + fi + + # Validate meta/hash for this pending txn + TXN_PATH=".git/$(echo "$LOCAL_REF" | sed 's#^refs/##')" + META_FILE="$TXN_PATH/meta" + # find branch dir under edges/* + EDGES_DIR=$(find "$TXN_PATH/edges" -maxdepth 1 -type d | tail -n +2 | head -n 1 || true) + if [[ -f "$META_FILE" && -n "${EDGES_DIR:-}" ]]; then + bash "$CHECK_SCRIPT" "$META_FILE" "$EDGES_DIR" + else + echo "[pre-push] ERROR: pending txn missing meta or edges: $LOCAL_REF" + exit 1 + fi + fi + + if [[ "$LOCAL_REF" =~ ^refs/gitmind/edges/ ]]; then + APPLIED_SEEN=1 + fi +done + +# Optional: block direct writes to canonical journal unless explicitly acknowledged +if [[ "$APPLIED_SEEN" == "1" && "${ALLOW_CANONICAL_WRITES:-0}" != "1" ]]; then + echo "[pre-push] ERROR: direct pushes to refs/gitmind/edges/* are disabled." + echo "Use: git mind txn apply (or set ALLOW_CANONICAL_WRITES=1 if you absolutely must)." + exit 1 +fi + +echo "[pre-push] OK" +exit 0 +``` + +Typical flows: + +• Normal devs: push code branches only → hook does nothing. +• Review pending txn (rare): + +```bash +PUSH_PENDING=1 git push origin refs/gitmind/pending/01J...:refs/gitmind/pending/01J... +``` + +Meta/hash validated before it leaves your laptop. + +• Hard override (discouraged): + +```bash +ALLOW_CANONICAL_WRITES=1 git push origin refs/gitmind/edges/main +``` + +###3) Server-side pre-receive + +Final backstop. Reject pending refs outright (unless you run a special “draft” remote), and require a provenance trailer on journal commits so only txn apply can touch canonical refs. + +#### Commit trailer chosen: Gm-Txn: (ULID) + +Have your git mind txn apply write commits with: + +```bash +Gm-Txn: 01J7A3S5J0B9QHY1TG8RZVZPWF +Gm-Apply: git-mind-cli/0.7.0 +``` + +#### File (server repo): .git/hooks/pre-receive (chmod +x) + +```bash +#!/usr/bin/env bash +set -euo pipefail + +reject() { echo "[pre-receive] $1" >&2; exit 1; } + +while read -r OLD NEW REF; do + # Block pending refs by default + if [[ "$REF" =~ ^refs/gitmind/pending/ ]]; then + reject "pending refs are not accepted on this remote: $REF" + fi + + # Enforce provenance on canonical journal + if [[ "$REF" =~ ^refs/gitmind/edges/ ]]; then + # New branch or update; scan new commits + RANGE="$OLD..$NEW" + # Allow branch creation (OLD == 0000...) — still scan NEW + if [[ "$OLD" == "0000000000000000000000000000000000000000" ]]; then + RANGE="$NEW" + fi + + # Every new commit must carry Gm-Txn trailer + # (git log --format='%(trailers:key=Gm-Txn)' prints trailer value if present) + MISSING=$(git rev-list "$RANGE" | while read -r C; do + T=$(git log -1 --pretty='%(trailers:key=Gm-Txn,separator=%x0a)' "$C") + [[ -z "$T" ]] && echo "$C" + done) + + if [[ -n "$MISSING" ]]; then + echo "[pre-receive] ERROR: commits to $REF without Gm-Txn trailer:" + echo "$MISSING" + echo "Only 'git mind txn apply' is allowed to write canonical journals." + exit 1 + fi + fi +done + +exit 0 +``` + +If you host on a shared server, put this into your server-side hook (bare repo) so the policy is universal. + +### 4) Optional: update hook to archive applied txns + +When a canonical journal moves forward with a valid trailer, you can auto-archive the matching pending txn under refs/gitmind/applied/ (if the client didn’t do it). + +#### File (server): .git/hooks/update (chmod +x) + +Called once per ref update: + +```bash +#!/usr/bin/env bash +set -euo pipefail + +REF="$1"; OLD="$2"; NEW="$3" + +if [[ "$REF" =~ ^refs/gitmind/edges/ ]]; then + # Extract the last commit’s Gm-Txn + TXN=$(git log -1 --pretty='%(trailers:key=Gm-Txn,valueonly)' "$NEW" | tail -n1) + if [[ -n "$TXN" ]]; then + PENDING="refs/gitmind/pending/$TXN" + APPLIED="refs/gitmind/applied/$TXN" + if git show-ref --verify --quiet "$PENDING"; then + echo "[update] archiving $PENDING -> $APPLIED" + # Create lightweight namespace under applied if not present + git update-ref "$APPLIED" "$(git rev-parse "$PENDING")" + # Optionally delete pending + git update-ref -d "$PENDING" + fi + fi +fi + +exit 0 +``` + +### 5) Bonus: local pre-commit sanity (cheap win) + +Catch accidental direct writes to journal files in the worktree (if any) and keep txn meta in sync. + +#### File: .githooks/pre-commit (chmod +x) + +```bash +#!/usr/bin/env bash +set -euo pipefail + +# Block accidental edits to journal files in repo (if they exist in worktree) +BAD=$(git diff --cached --name-only -- \ + 'refs/gitmind/edges/*' 'refs/gitmind/pending/*' 2>/dev/null || true) +if [[ -n "$BAD" ]]; then + echo "[pre-commit] ERROR: do not commit refs/* paths via worktree." + echo "Use 'git mind' CLI to mutate journals/transactions." + exit 1 +fi + +# If a txn is active, keep meta.edge_count honest (best-effort) +if [[ -n "${GITMIND_TXN_ID:-}" ]]; then + TXN_DIR=".git/refs/gitmind/pending/${GITMIND_TXN_ID}" + META="$TXN_DIR/meta" + if [[ -f "$META" ]]; then + EDGES_DIR=$(find "$TXN_DIR/edges" -maxdepth 1 -type d | tail -n +2 | head -n 1 || true) + if [[ -n "${EDGES_DIR:-}" && -d "$EDGES_DIR" ]]; then + COUNT=$(ls -1 "$EDGES_DIR"/*.json 2>/dev/null | wc -l | tr -d ' ') + jq --argjson n "$COUNT" '.edge_count=$n' "$META" > "$META.tmp" && mv "$META.tmp" "$META" + fi + fi +fi +``` + +### 6) Policy TL;DR (communicate this in your RFC) + +• You cannot push pending/ by default. Opt-in with PUSH_PENDING=1 for review-only remotes. +• You cannot push edges/* directly. Only commits created by git mind txn apply (with Gm-Txn: trailer) are accepted server-side. +• All pending txns are meta+hash validated before they’re allowed to leave a machine. +• Applied txns are auto-archived server-side when possible; otherwise clients should move pending → applied. + +This setup makes the safe path the easy path: + • Stage in a sandbox, preview, apply with a provenance trailer, and let the server archive. + • Anyone trying to sneak around the process gets a fast, loud failure. Good. From bf5c7d480b42251f8ae479a5fca7a8e9c8bf6a6c Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Wed, 17 Sep 2025 21:43:07 -0700 Subject: [PATCH 38/42] docs: slot sandbox transactions into alpha roadmap --- docs/features/Features_Ledger.md | 1 + docs/planning/Milestone_Synthesis.md | 1 + 2 files changed, 2 insertions(+) diff --git a/docs/features/Features_Ledger.md b/docs/features/Features_Ledger.md index 8d2560ad..e61bb3fe 100644 --- a/docs/features/Features_Ledger.md +++ b/docs/features/Features_Ledger.md @@ -157,6 +157,7 @@ features=8 | 🕸️ | Edge Graph Engine | Core | docs/architecture/System_Architecture.md | core/src/edge, core/include/gitmind/edge | Alpha | 1.0 | Alpha | 75% | ████████░░ | ULID-ordered edges; journal append + cache hydration. | Edge diff coverage; multi-branch stress. | Unit + fuzz | Forms graph spine. | | 🧬 | Semantics & Type System | Core | docs/architecture/System_Architecture.md | core/src/types, core/src/utf8, core/src/time | MVP | 2.7 | Alpha | 80% | ████████░░ | Stable hashed IDs; NFC normalization; time-safe stamping. | Expose helper API; document name rules. | Unit | Ready for consumers. | | 🪪 | Attribution Metadata | Core | docs/architecture/attribution-system.md | core/src/attribution | Beta | 0.2 | In Progress | 55% | ██████░░░░ | Capture author/time for edges; merge helpers in place. | Extend multi-author rollups; CLI surfacing. | Unit scaffolding | Needs UX polish. | +| 🗂️ | Sandbox Transactions | Core | docs/talk-shop/Sandbox_Transactions.md | core/src/journal (planned) | Alpha | 0.8 | Planned | 5% | █░░░░░░░░░ | Pending refs + CLI flow to stage/apply journal mutations safely. | Implement txn start/apply/abort; hook integration. | Planned | Draft RFC merged. | ### CLI, Hooks & UX diff --git a/docs/planning/Milestone_Synthesis.md b/docs/planning/Milestone_Synthesis.md index 3fb3f032..969a6c16 100644 --- a/docs/planning/Milestone_Synthesis.md +++ b/docs/planning/Milestone_Synthesis.md @@ -50,6 +50,7 @@ This guide aligns the many planning artifacts (HN demo plan, roadmap snapshots, - Cohesion report + branch-aware queries (Milestones M5, Release v0.7–v0.8). - Worksheet automation + reply workflows (Features Ledger “Review Seeding & Replies”). - Cache performance guardrails (<10ms median per Release Plan), telemetry knobs (Roadmap “Medium Term”). + - Sandbox transaction blocks to preview journal mutations safely before apply (`docs/talk-shop/Sandbox_Transactions.md`). - Observability: CBOR debug tracing, ledger snapshot tasks. - **Exit criteria:** Cache rebuilds complete without manual babysitting; collaboration loops (worksheet, review replies) exercised on real PR; alpha docs outline known gaps. From 6104167720238be95a37588b466824c82b96e1fb Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Wed, 17 Sep 2025 22:06:36 -0700 Subject: [PATCH 39/42] docs: break out features ledger task list --- docs/features/Features_Ledger.md | 270 ++++++++++++++++++++++--------- 1 file changed, 198 insertions(+), 72 deletions(-) diff --git a/docs/features/Features_Ledger.md b/docs/features/Features_Ledger.md index e61bb3fe..d9369f44 100644 --- a/docs/features/Features_Ledger.md +++ b/docs/features/Features_Ledger.md @@ -147,17 +147,17 @@ features=8 ``` -| Emoji | Feature | Area | Spec | Code | Milestone | KLoC (approx) | Status | Progress % | Bar | Current State | Todo (Tasks) | Tests | Remarks | -| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | -| 🧱 | OID‑first Core | Core | — | core/include, core/src | v1.0.0 | 3.5 | Alpha | 85% | █████████░ | Equality OID‑first; OID fields in CBOR; cache/journal aligned. | Finalize strict equality; docs complete. | Unit passing | Good foundation. | -| 🗄️ | Journal (CBOR) | Core | docs/architecture/journal-architecture-pivot.md | core/src/journal, core/src/cbor | Alpha | 1.2 | Alpha | 80% | ████████░░ | Writer/reader with base64; debug flag; attributed edges. | Finalize ordering; more tests. | Unit passing | Backwards compat OK. | -| ⚡ | Cache (Bitmap) | Core | docs/architecture/bitmap-cache-design.md | core/src/cache | Alpha | 1.6 | In Progress | 75% | ███████░░░ | Rebuild + query; shard; metadata. | Perf tuning + shard benchmarks. | Unit partial | Added branch-limit + tree-size coverage. | -| 🔗 | Ref Utilities | Core | docs/architecture/Ref_Name_Validation.md | core/src/util | MVP | 0.5 | MVP | 75% | ███████░░░ | `gm_build_ref` with validation; tests. | More negative tests; docs link. | Unit | Good coverage. | -| 🧰 | Safe String/Memory | Core | — | core/include/gitmind/util | v1.0.0 | 0.4 | V1 | 90% | █████████░ | Safe wrappers adopted in hot paths. | Sweep stragglers; docs. | Unit | Security uplift. | -| 🕸️ | Edge Graph Engine | Core | docs/architecture/System_Architecture.md | core/src/edge, core/include/gitmind/edge | Alpha | 1.0 | Alpha | 75% | ████████░░ | ULID-ordered edges; journal append + cache hydration. | Edge diff coverage; multi-branch stress. | Unit + fuzz | Forms graph spine. | -| 🧬 | Semantics & Type System | Core | docs/architecture/System_Architecture.md | core/src/types, core/src/utf8, core/src/time | MVP | 2.7 | Alpha | 80% | ████████░░ | Stable hashed IDs; NFC normalization; time-safe stamping. | Expose helper API; document name rules. | Unit | Ready for consumers. | -| 🪪 | Attribution Metadata | Core | docs/architecture/attribution-system.md | core/src/attribution | Beta | 0.2 | In Progress | 55% | ██████░░░░ | Capture author/time for edges; merge helpers in place. | Extend multi-author rollups; CLI surfacing. | Unit scaffolding | Needs UX polish. | -| 🗂️ | Sandbox Transactions | Core | docs/talk-shop/Sandbox_Transactions.md | core/src/journal (planned) | Alpha | 0.8 | Planned | 5% | █░░░░░░░░░ | Pending refs + CLI flow to stage/apply journal mutations safely. | Implement txn start/apply/abort; hook integration. | Planned | Draft RFC merged. | +| Emoji | Feature | Area | Spec | Code | Milestone | KLoC (approx) | Status | Progress % | Bar | Current State | Tests | Remarks | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 🧱 | OID‑first Core | Core | — | core/include, core/src | v1.0.0 | 3.5 | Alpha | 85% | █████████░ | Equality OID‑first; OID fields in CBOR; cache/journal aligned. | Unit passing | Good foundation. | +| 🗄️ | Journal (CBOR) | Core | docs/architecture/journal-architecture-pivot.md | core/src/journal, core/src/cbor | Alpha | 1.2 | Alpha | 80% | ████████░░ | Writer/reader with base64; debug flag; attributed edges. | Unit passing | Backwards compat OK. | +| ⚡ | Cache (Bitmap) | Core | docs/architecture/bitmap-cache-design.md | core/src/cache | Alpha | 1.6 | In Progress | 75% | ███████░░░ | Rebuild + query; shard; metadata. | Unit partial | Added branch-limit + tree-size coverage. | +| 🔗 | Ref Utilities | Core | docs/architecture/Ref_Name_Validation.md | core/src/util | MVP | 0.5 | MVP | 75% | ███████░░░ | `gm_build_ref` with validation; tests. | Unit | Good coverage. | +| 🧰 | Safe String/Memory | Core | — | core/include/gitmind/util | v1.0.0 | 0.4 | V1 | 90% | █████████░ | Safe wrappers adopted in hot paths. | Unit | Security uplift. | +| 🕸️ | Edge Graph Engine | Core | docs/architecture/System_Architecture.md | core/src/edge, core/include/gitmind/edge | Alpha | 1.0 | Alpha | 75% | ████████░░ | ULID-ordered edges; journal append + cache hydration. | Unit + fuzz | Forms graph spine. | +| 🧬 | Semantics & Type System | Core | docs/architecture/System_Architecture.md | core/src/types, core/src/utf8, core/src/time | MVP | 2.7 | Alpha | 80% | ████████░░ | Stable hashed IDs; NFC normalization; time-safe stamping. | Unit | Ready for consumers. | +| 🪪 | Attribution Metadata | Core | docs/architecture/attribution-system.md | core/src/attribution | Beta | 0.2 | In Progress | 55% | ██████░░░░ | Capture author/time for edges; merge helpers in place. | Unit scaffolding | Needs UX polish. | +| 🗂️ | Sandbox Transactions | Core | docs/talk-shop/Sandbox_Transactions.md | core/src/journal (planned) | Alpha | 0.8 | Planned | 5% | █░░░░░░░░░ | Pending refs + CLI flow to stage/apply journal mutations safely. | Planned | Draft RFC merged. | ### CLI, Hooks & UX @@ -169,15 +169,15 @@ features=7 ``` -| Emoji | Feature | Area | Spec | Code | Milestone | KLoC (approx) | Status | Progress % | Bar | Current State | Todo (Tasks) | Tests | Remarks | -| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | -| 🪝 | Post‑commit Hook (AUGMENTS) | Hooks | docs/hooks | core/src/hooks | Alpha | 0.5 | In Progress | 50% | █████░░░░░ | Process changed files; AUGMENTS edge. | Path truncation handling (done); more cases. | Unit | Wire to journal read. | -| 🔒 | CLI Safety Guard | CLI | docs/operations/Environment_Variables.md | apps/cli/cli_runtime.c | MVP | 0.6 | MVP | 70% | ███████░░░ | Official repo guard; env override; safe install workflow. | Extend host override tests; document upgrade path. | Unit | Solid baseline. | -| 🛠️ | `git mind` CLI Commands | CLI | apps/cli/main.md | apps/cli | MVP | 1.2 | MVP | 65% | ██████░░░░ | `link`, `list`, cache rebuild; shared runtime utilities. | Add query subcommands; richer diagnostics. | Unit + manual | Ready for daily use. | -| 🧰 | Review Seeding & Replies | DX | docs/tools | tools/review, workflows | Alpha | 0.4 | MVP | 80% | ████████░░ | Seed + auto‑reply; artifact fallback; reply templates rendered cleanly. | Gate GraphQL auto-resolve behind flag; document live PR validation; GH App roadmap. | CI + unit | High leverage. | -| 📜 | Docs Tooling | Docs | docs/tools | tools/docs | MVP | 0.4 | MVP | 70% | ███████░░░ | Frontmatter/TOC/title checks; labeler. | Extend templates; more guides. | Scripted | Good base. | -| 🧭 | Curated AGENTS.md | DX | docs | tools/agents | MVP | 0.2 | MVP | 80% | ████████░░ | TL;DR + YAML; curator; archives. | Tune summaries; monthly rollup. | Scripted | Fast onboarding. | -| 🧪 | Worksheet Gates | DX | docs/tools | tools/review | Alpha | 0.3 | V1 | 90% | █████████░ | Pre‑push checks for placeholders + decisions. | Heuristics later (optional). | Scripted | Keeps quality high. | +| Emoji | Feature | Area | Spec | Code | Milestone | KLoC (approx) | Status | Progress % | Bar | Current State | Tests | Remarks | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 🪝 | Post‑commit Hook (AUGMENTS) | Hooks | docs/hooks | core/src/hooks | Alpha | 0.5 | In Progress | 50% | █████░░░░░ | Process changed files; AUGMENTS edge. | Unit | Wire to journal read. | +| 🔒 | CLI Safety Guard | CLI | docs/operations/Environment_Variables.md | apps/cli/cli_runtime.c | MVP | 0.6 | MVP | 70% | ███████░░░ | Official repo guard; env override; safe install workflow. | Unit | Solid baseline. | +| 🛠️ | `git mind` CLI Commands | CLI | apps/cli/main.md | apps/cli | MVP | 1.2 | MVP | 65% | ██████░░░░ | `link`, `list`, cache rebuild; shared runtime utilities. | Unit + manual | Ready for daily use. | +| 🧰 | Review Seeding & Replies | DX | docs/tools | tools/review, workflows | Alpha | 0.4 | MVP | 80% | ████████░░ | Seed + auto‑reply; artifact fallback; reply templates rendered cleanly. | CI + unit | High leverage. | +| 📜 | Docs Tooling | Docs | docs/tools | tools/docs | MVP | 0.4 | MVP | 70% | ███████░░░ | Frontmatter/TOC/title checks; labeler. | Scripted | Good base. | +| 🧭 | Curated AGENTS.md | DX | docs | tools/agents | MVP | 0.2 | MVP | 80% | ████████░░ | TL;DR + YAML; curator; archives. | Scripted | Fast onboarding. | +| 🧪 | Worksheet Gates | DX | docs/tools | tools/review | Alpha | 0.3 | V1 | 90% | █████████░ | Pre‑push checks for placeholders + decisions. | Scripted | Keeps quality high. | ### Observability & Analytics @@ -189,67 +189,193 @@ features=3 ``` -| Emoji | Feature | Area | Spec | Code | Milestone | KLoC (approx) | Status | Progress % | Bar | Current State | Todo (Tasks) | Tests | Remarks | -| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | -| 🔎 | CBOR Debug Tracing | Core/Obs | docs/operations | core/src/journal | Alpha | 0.2 | MVP | 60% | ██████░░░░ | Env flag for verbose decode. | Structured logging; sampling. | Unit | Helpful during migration. | -| 📈 | Progress Ledgers | DX/Obs | docs/features | scripts | MVP | 0.3 | MVP | 70% | ███████░░░ | Ledger + updater script; KLoC-weighted bars + README sync. | Expose CLI summary; automate weekly snapshots. | Scripted | Improves planning. | -| 📊 | CI Trend Baselines | Obs | docs/ci | tools | v1.0.0 | 0.2 | Planned | 20% | ██░░░░░░░░ | Not started. | Collect tidy counts; failures. | — | Future. | +| Emoji | Feature | Area | Spec | Code | Milestone | KLoC (approx) | Status | Progress % | Bar | Current State | Tests | Remarks | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| 🔎 | CBOR Debug Tracing | Core/Obs | docs/operations | core/src/journal | Alpha | 0.2 | MVP | 60% | ██████░░░░ | Env flag for verbose decode. | Unit | Helpful during migration. | +| 📈 | Progress Ledgers | DX/Obs | docs/features | scripts | MVP | 0.3 | MVP | 70% | ███████░░░ | Ledger + updater script; KLoC-weighted bars + README sync. | Scripted | Improves planning. | +| 📊 | CI Trend Baselines | Obs | docs/ci | tools | v1.0.0 | 0.2 | Planned | 20% | ██░░░░░░░░ | Not started. | Planned | Future. | ## Tasklist ### Core & Platform -- [ ] [v1.0.0] Adopt OID‑first equality everywhere (strict, no SHA fallback when OIDs present) -> [!INFO]- -> Update comparisons and tests; align cache/journal; document in TECHNICAL.md. - -- [x] [Alpha] Finalize bitmap cache conformance tests -> [!INFO]- -> Build synthetic repos; verify shard distribution and size calculations; add docs. - -- [ ] [Alpha] Edge graph multi-branch coverage -> [!INFO]- -> Add regression tests for branch fan-out, ULID ordering guarantees, and edge diff helpers; capture findings in `docs/architecture/System_Architecture.md`. - -- [ ] [Beta] Surface attribution metadata in CLI output -> [!INFO]- -> Thread author/time data through cache rebuild + `git mind list`; document flag to toggle extended columns. - -- [x] [Alpha] Retire legacy `src/` tree -> [!INFO]- -> Move remaining markdown artifacts under `src/` into `docs/legacy/src/`, remove empty scaffolding, and update references so core/ is the sole code root. - -- [x] [Alpha] Sweep includes and docs for `src/` references -> [!INFO]- -> Replace lingering `src/` include or doc paths with `core/` equivalents and ensure tooling/tests reflect the finalized layout. + +- [ ] (GM.V1.T001) Finalize strict equality; docs complete. +> [!INFO]- Step-by-step Instructions +> - [ ] Audit equality helpers in cache/journal and ensure OID-first comparisons never fall back when OIDs exist. +> - [ ] Add regression tests covering mixed OID/string paths. +> - [ ] Update `docs/TECHNICAL.md` and related ADRs to document the strict behavior. +> - [ ] Sweep references to legacy SHA fallbacks in docs/examples. + + +- [ ] (GM.ALPHA.T001) Finalize ordering; add tests for CBOR journal reader. +> [!INFO]- Step-by-step Instructions +> - [ ] Write table-driven tests for journal iteration order (newest-first, branch boundaries). +> - [ ] Exercise attributed vs. plain edges in CBOR fixtures. +> - [ ] Patch reader docs to reflect ordering guarantees. +> - [ ] Wire tests into `meson.build` and ensure they run in CI. + + +- [ ] (GM.ALPHA.T002) Perf tuning + shard benchmarks. +> [!INFO]- Step-by-step Instructions +> - [ ] Capture baseline timings for cache rebuild/query across representative repos. +> - [ ] Profile shard fan-out hotspots and prototype optimizations. +> - [ ] Automate a lightweight benchmark harness (Docker-safe) to guard regressions. +> - [ ] Document results in `docs/architecture/bitmap-cache-design.md`. + + +- [ ] (GM.MVP.T001) Add negative tests and docs for ref utilities. +> [!INFO]- Step-by-step Instructions +> - [ ] Extend `test_ref_utils` to cover invalid prefixes, length overflows, and reserved refs. +> - [ ] Ensure errors propagate with meaningful `GM_ERR_*` codes. +> - [ ] Update ref utilities docstrings and the Narrative in `docs/architecture/Ref_Name_Validation.md`. +> - [ ] Mention failure scenarios in README/tutorial examples. + + +- [ ] (GM.V1.T002) Sweep remaining safe-string/memory stragglers and docs. +> [!INFO]- Step-by-step Instructions +> - [ ] Grep for raw `strcpy`/`sprintf` usage outside approved wrappers. +> - [ ] Replace with `gm_snprintf`/`gm_strcpy_safe` equivalents. +> - [ ] Update Safety section in `docs/enforcer/gameplans/03-observability-built-in.md`. +> - [ ] Add unit coverage where new wrappers are introduced. + + +- [ ] (GM.ALPHA.T003) Edge diff coverage; multi-branch stress harness. +> [!INFO]- Step-by-step Instructions +> - [ ] Create fixture branches with divergent edge histories to prove diff stability. +> - [ ] Add integration tests comparing fan-in/out across merge commits. +> - [ ] Ensure cache/journal diff helpers handle branch fan-out. +> - [ ] Document the harness in `docs/architecture/System_Architecture.md`. + + +- [ ] (GM.MVP.T002) Expose helper API; document naming rules. +> [!INFO]- Step-by-step Instructions +> - [ ] Promote internal semantics helpers to public headers (review include hygiene). +> - [ ] Add examples demonstrating NFC normalization to docs/tutorials. +> - [ ] Write API reference entries with usage notes. +> - [ ] Cover helper functions with unit tests. + + +- [ ] (GM.BETA.T001) Extend multi-author rollups; surface in CLI. +> [!INFO]- Step-by-step Instructions +> - [ ] Extend attribution data structure to track multiple authors/time windows. +> - [ ] Update cache/journal serialization to carry additional metadata. +> - [ ] Add CLI flags to display attribution columns. +> - [ ] Document workflow and examples in attribution architecture doc. + + +- [ ] (GM.ALPHA.T004) Implement sandbox txn start/apply/abort; hook integration. +> [!INFO]- Step-by-step Instructions +> - [ ] Implement `gm_txn_start/apply/abort` helpers manipulating pending refs. +> - [ ] Build CLI plumbing (`git mind txn ...`) with dry-run/apply flows. +> - [ ] Add local/server hook snippets to enforce provenance. +> - [ ] Ship documentation updates (RFC, roadmap, tutorial snippet). ### CLI, Hooks & UX -- [ ] [Alpha] Post‑commit AUGMENTS wiring -> [!INFO]- -> Finish journal read integration; handle path truncation errors; add E2E. - -- [ ] [Alpha] GraphQL auto‑resolve for accepted PR feedback -> [!INFO]- -> Add a feature-flagged path in `apply-feedback` to call `discussion.resolveReviewThread`; map worksheet IDs to GraphQL node IDs and dry-run before enabling by default. - -- [ ] [Alpha] Validate worksheet reply workflow on a fresh PR -> [!INFO]- -> Run `make apply-feedback` against a new test PR, capture rendered replies, and embed screenshots/notes in `docs/tools/Review_Seeding.md`. + +- [ ] (GM.ALPHA.T005) Path truncation handling follow-ups; wire to journal read. +> [!INFO]- Step-by-step Instructions +> - [ ] Add failing test covering truncated paths in augment hook. +> - [ ] Ensure journal read/write propagates truncation errors cleanly. +> - [ ] Update hook documentation with failure guidance. +> - [ ] Verify behavior through integration test in container. + + +- [ ] (GM.MVP.T003) Extend host override tests; document upgrade path. +> [!INFO]- Step-by-step Instructions +> - [ ] Expand CLI safety tests to cover new env overrides. +> - [ ] Document the upgrade path in `docs/operations/Environment_Variables.md`. +> - [ ] Announce safe override usage in README/CLI help. +> - [ ] Confirm behavior in Docker CI harness. + + +- [ ] (GM.MVP.T004) Add query subcommands; richer diagnostics. +> [!INFO]- Step-by-step Instructions +> - [ ] Design subcommand syntax and update CLI help. +> - [ ] Implement parsing + output formatting for new queries. +> - [ ] Write unit/integration tests for diagnostics. +> - [ ] Update tutorial examples. + + +- [ ] (GM.ALPHA.T006) Gate GraphQL auto-resolve behind flag; document validation; GH App roadmap. +> [!INFO]- Step-by-step Instructions +> - [ ] Introduce feature flag controlling auto-resolve behavior. +> - [ ] Document validation workflow with screenshots in Review Seeding docs. +> - [ ] Outline GH App roadmap section clarifying future automation. +> - [ ] Add regression tests around new flag default. + + +- [ ] (GM.MVP.T005) Extend templates; more guides. +> [!INFO]- Step-by-step Instructions +> - [ ] Audit existing docs templates for gaps. +> - [ ] Add missing sections (TOC hints, status guidance). +> - [ ] Update docs tooling lint to confirm compliance. +> - [ ] Announce templates in contributor guide. + + +- [ ] (GM.MVP.T006) Tune AGENTS summaries; monthly rollup. +> [!INFO]- Step-by-step Instructions +> - [ ] Define monthly rollup process for AGENTS highlights. +> - [ ] Automate summary generation or provide script. +> - [ ] Update AGENTS.md with new cadence instructions. +> - [ ] Verify pre-commit hook enforces formatting. + + +- [ ] (GM.V1.T003) Optional heuristics for worksheet gates. +> [!INFO]- Step-by-step Instructions +> - [ ] Define heuristic rules (placeholder detection, decision coverage). +> - [ ] Implement optional flag to enable heuristics in gate tooling. +> - [ ] Document opt-in usage and backward compatibility. +> - [ ] Add tests covering heuristic outcomes. ### Observability & Analytics -- [ ] [v1.0.0] CI trend baselines collection -> [!INFO]- -> Record tidy counts and unit results; render sparklines; add dashboards. - -- [ ] [Beta] Ledger snapshot automation -> [!INFO]- -> Wire `make features-update` into a scheduled workflow and add regression tests to confirm README + ledger stay in sync. - - ---- + +- [ ] (GM.ALPHA.T007) Structured logging; sampling options. +> [!INFO]- Step-by-step Instructions +> - [ ] Design logging schema for CBOR debug tracing. +> - [ ] Implement sampling controls (env/config toggles). +> - [ ] Update ops docs with usage examples. +> - [ ] Add tests ensuring logs redact sensitive content. + + +- [ ] (GM.MVP.T007) Expose CLI summary; automate weekly snapshots. +> [!INFO]- Step-by-step Instructions +> - [ ] Implement CLI summary command reading ledger progress. +> - [ ] Automate snapshot job (cron/workflow) updating docs. +> - [ ] Document snapshot cadence for contributors. +> - [ ] Add regression test verifying README sync. + + +- [ ] (GM.V1.T004) Collect tidy counts and failures; render trends. +> [!INFO]- Step-by-step Instructions +> - [ ] Instrument CI to capture tidy counts and unit failures. +> - [ ] Store trend data (JSON/CSV) for dashboards. +> - [ ] Render trend visualization in docs/dashboard. +> - [ ] Document maintenance workflow for trend data. + +## Completeness + +| Task | Started? | Finished? | Tested? | Shipped? | +|------|----------|-----------|---------|----------| +| [GM.V1.T001](#gmv1t001) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.ALPHA.T001](#gmalpha001) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.ALPHA.T002](#gmalpha002) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.MVP.T001](#gmmvp001) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.V1.T002](#gmv1t002) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.ALPHA.T003](#gmalpha003) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.MVP.T002](#gmmvp002) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.BETA.T001](#gmbeta001) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.ALPHA.T004](#gmalpha004) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.ALPHA.T005](#gmalpha005) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.MVP.T003](#gmmvp003) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.MVP.T004](#gmmvp004) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.ALPHA.T006](#gmalpha006) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.MVP.T005](#gmmvp005) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.MVP.T006](#gmmvp006) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.V1.T003](#gmv1t003) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.ALPHA.T007](#gmalpha007) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.MVP.T007](#gmmvp007) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.V1.T004](#gmv1t004) | 🚫 | 🚫 | 🚫 | 🚫 | -Notes -- Update via `python3 scripts/update_progress.py` (or `make features-update`). -- Progress bars use KLoC weighting; keep the KLoC column fresh to avoid drift. From 62577ae974c84307528fc0dd1b62acc807075e1f Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Thu, 18 Sep 2025 03:59:08 -0700 Subject: [PATCH 40/42] docs: restructure tasklist and add dependency dag --- docs/features/Features_Ledger.md | 265 ++++++++++++++++++------------ docs/features/images/task_dag.dot | 124 ++++++++++++++ docs/features/images/task_dag.svg | 3 + 3 files changed, 290 insertions(+), 102 deletions(-) create mode 100644 docs/features/images/task_dag.dot create mode 100644 docs/features/images/task_dag.svg diff --git a/docs/features/Features_Ledger.md b/docs/features/Features_Ledger.md index d9369f44..aef178bb 100644 --- a/docs/features/Features_Ledger.md +++ b/docs/features/Features_Ledger.md @@ -195,25 +195,100 @@ features=3 | 📈 | Progress Ledgers | DX/Obs | docs/features | scripts | MVP | 0.3 | MVP | 70% | ███████░░░ | Ledger + updater script; KLoC-weighted bars + README sync. | Scripted | Improves planning. | | 📊 | CI Trend Baselines | Obs | docs/ci | tools | v1.0.0 | 0.2 | Planned | 20% | ██░░░░░░░░ | Not started. | Planned | Future. | +## Tasklist ## Tasklist -### Core & Platform +![Task Dependency Map](images/task_dag.svg) - -- [ ] (GM.V1.T001) Finalize strict equality; docs complete. +### MVP + +#### Core & Platform + + +- [ ] (GM.MVP.T001) Finalize strict equality; docs complete. > [!INFO]- Step-by-step Instructions > - [ ] Audit equality helpers in cache/journal and ensure OID-first comparisons never fall back when OIDs exist. > - [ ] Add regression tests covering mixed OID/string paths. > - [ ] Update `docs/TECHNICAL.md` and related ADRs to document the strict behavior. > - [ ] Sweep references to legacy SHA fallbacks in docs/examples. +> [!NOTE]- Dependencies +> - (none) + + +- [ ] (GM.MVP.T002) Add negative tests and docs for ref utilities. +> [!INFO]- Step-by-step Instructions +> - [ ] Extend `test_ref_utils` to cover invalid prefixes, length overflows, and reserved refs. +> - [ ] Ensure errors propagate with meaningful `GM_ERR_*` codes. +> - [ ] Update docstrings and `docs/architecture/Ref_Name_Validation.md` with new failure cases. +> - [ ] Mention failure scenarios in README/tutorial examples. +> [!NOTE]- Dependencies +> - [GM.MVP.T001](#gmmvp001) + +#### CLI, Hooks & UX + + +- [ ] (GM.MVP.T003) Extend host override tests; document upgrade path. +> [!INFO]- Step-by-step Instructions +> - [ ] Expand CLI safety tests to cover new env overrides. +> - [ ] Document the upgrade path in `docs/operations/Environment_Variables.md`. +> - [ ] Announce safe override usage in README/CLI help. +> - [ ] Confirm behavior in Docker CI harness. +> [!NOTE]- Dependencies +> - (none) + + +- [ ] (GM.MVP.T004) Add query subcommands; richer diagnostics. +> [!INFO]- Step-by-step Instructions +> - [ ] Design subcommand syntax and update CLI help output. +> - [ ] Implement parsing + output formatting for new queries. +> - [ ] Write unit/integration tests for diagnostics coverage. +> - [ ] Update tutorial examples and docs. +> [!NOTE]- Dependencies +> - [GM.MVP.T003](#gmmvp003) + + +- [ ] (GM.MVP.T005) Extend docs templates and guides. +> [!INFO]- Step-by-step Instructions +> - [ ] Audit existing docs templates for gaps (status blocks, TOC conventions). +> - [ ] Add missing sections and update template examples. +> - [ ] Enhance docs lint to verify new expectations. +> - [ ] Announce updates in contributor guide. +> [!NOTE]- Dependencies +> - (none) + + +- [ ] (GM.MVP.T006) Tune AGENTS summaries; monthly rollup. +> [!INFO]- Step-by-step Instructions +> - [ ] Define monthly rollup process for AGENTS highlights. +> - [ ] Provide script or automation to generate summaries. +> - [ ] Update `AGENTS.md` with cadence instructions. +> - [ ] Verify pre-commit hook enforces formatting. +> [!NOTE]- Dependencies +> - [GM.MVP.T005](#gmmvp005) + + +- [ ] (GM.MVP.T007) Expose CLI summary; automate weekly progress snapshots. +> [!INFO]- Step-by-step Instructions +> - [ ] Implement a CLI summary command reading ledger progress. +> - [ ] Automate a cron/workflow to update snapshot outputs. +> - [ ] Document snapshot cadence for contributors. +> - [ ] Add regression test verifying README/ledger sync. +> [!NOTE]- Dependencies +> - [GM.MVP.T005](#gmmvp005) + +### Alpha + +#### Core & Platform - [ ] (GM.ALPHA.T001) Finalize ordering; add tests for CBOR journal reader. > [!INFO]- Step-by-step Instructions -> - [ ] Write table-driven tests for journal iteration order (newest-first, branch boundaries). -> - [ ] Exercise attributed vs. plain edges in CBOR fixtures. +> - [ ] Write table-driven tests validating iteration order across branches. +> - [ ] Exercise attributed vs. plain edge decoding paths. > - [ ] Patch reader docs to reflect ordering guarantees. > - [ ] Wire tests into `meson.build` and ensure they run in CI. +> [!NOTE]- Dependencies +> - [GM.MVP.T001](#gmmvp001) - [ ] (GM.ALPHA.T002) Perf tuning + shard benchmarks. @@ -222,22 +297,8 @@ features=3 > - [ ] Profile shard fan-out hotspots and prototype optimizations. > - [ ] Automate a lightweight benchmark harness (Docker-safe) to guard regressions. > - [ ] Document results in `docs/architecture/bitmap-cache-design.md`. - - -- [ ] (GM.MVP.T001) Add negative tests and docs for ref utilities. -> [!INFO]- Step-by-step Instructions -> - [ ] Extend `test_ref_utils` to cover invalid prefixes, length overflows, and reserved refs. -> - [ ] Ensure errors propagate with meaningful `GM_ERR_*` codes. -> - [ ] Update ref utilities docstrings and the Narrative in `docs/architecture/Ref_Name_Validation.md`. -> - [ ] Mention failure scenarios in README/tutorial examples. - - -- [ ] (GM.V1.T002) Sweep remaining safe-string/memory stragglers and docs. -> [!INFO]- Step-by-step Instructions -> - [ ] Grep for raw `strcpy`/`sprintf` usage outside approved wrappers. -> - [ ] Replace with `gm_snprintf`/`gm_strcpy_safe` equivalents. -> - [ ] Update Safety section in `docs/enforcer/gameplans/03-observability-built-in.md`. -> - [ ] Add unit coverage where new wrappers are introduced. +> [!NOTE]- Dependencies +> - [GM.ALPHA.T001](#gmalpha001) - [ ] (GM.ALPHA.T003) Edge diff coverage; multi-branch stress harness. @@ -246,22 +307,8 @@ features=3 > - [ ] Add integration tests comparing fan-in/out across merge commits. > - [ ] Ensure cache/journal diff helpers handle branch fan-out. > - [ ] Document the harness in `docs/architecture/System_Architecture.md`. - - -- [ ] (GM.MVP.T002) Expose helper API; document naming rules. -> [!INFO]- Step-by-step Instructions -> - [ ] Promote internal semantics helpers to public headers (review include hygiene). -> - [ ] Add examples demonstrating NFC normalization to docs/tutorials. -> - [ ] Write API reference entries with usage notes. -> - [ ] Cover helper functions with unit tests. - - -- [ ] (GM.BETA.T001) Extend multi-author rollups; surface in CLI. -> [!INFO]- Step-by-step Instructions -> - [ ] Extend attribution data structure to track multiple authors/time windows. -> - [ ] Update cache/journal serialization to carry additional metadata. -> - [ ] Add CLI flags to display attribution columns. -> - [ ] Document workflow and examples in attribution architecture doc. +> [!NOTE]- Dependencies +> - [GM.ALPHA.T002](#gmalpha002) - [ ] (GM.ALPHA.T004) Implement sandbox txn start/apply/abort; hook integration. @@ -270,56 +317,81 @@ features=3 > - [ ] Build CLI plumbing (`git mind txn ...`) with dry-run/apply flows. > - [ ] Add local/server hook snippets to enforce provenance. > - [ ] Ship documentation updates (RFC, roadmap, tutorial snippet). - -### CLI, Hooks & UX +> [!NOTE]- Dependencies +> - [GM.ALPHA.T003](#gmalpha003) +> - [GM.MVP.T002](#gmmvp002) -- [ ] (GM.ALPHA.T005) Path truncation handling follow-ups; wire to journal read. -> [!INFO]- Step-by-step Instructions -> - [ ] Add failing test covering truncated paths in augment hook. -> - [ ] Ensure journal read/write propagates truncation errors cleanly. -> - [ ] Update hook documentation with failure guidance. -> - [ ] Verify behavior through integration test in container. - - -- [ ] (GM.MVP.T003) Extend host override tests; document upgrade path. -> [!INFO]- Step-by-step Instructions -> - [ ] Expand CLI safety tests to cover new env overrides. -> - [ ] Document the upgrade path in `docs/operations/Environment_Variables.md`. -> - [ ] Announce safe override usage in README/CLI help. -> - [ ] Confirm behavior in Docker CI harness. - - -- [ ] (GM.MVP.T004) Add query subcommands; richer diagnostics. +- [ ] (GM.ALPHA.T005) Post-commit AUGMENTS wiring. > [!INFO]- Step-by-step Instructions -> - [ ] Design subcommand syntax and update CLI help. -> - [ ] Implement parsing + output formatting for new queries. -> - [ ] Write unit/integration tests for diagnostics. -> - [ ] Update tutorial examples. +> - [ ] Finish journal read integration and handle path truncation errors. +> - [ ] Add end-to-end test demonstrating AUGMENTS edges emitted via hooks. +> - [ ] Document error/fallback behavior in hooks guide. +> - [ ] Verify containerized tests cover new path. +> [!NOTE]- Dependencies +> - [GM.ALPHA.T004](#gmalpha004) - [ ] (GM.ALPHA.T006) Gate GraphQL auto-resolve behind flag; document validation; GH App roadmap. > [!INFO]- Step-by-step Instructions > - [ ] Introduce feature flag controlling auto-resolve behavior. > - [ ] Document validation workflow with screenshots in Review Seeding docs. -> - [ ] Outline GH App roadmap section clarifying future automation. +> - [ ] Outline GH App roadmap clarifying future automation. > - [ ] Add regression tests around new flag default. +> [!NOTE]- Dependencies +> - [GM.MVP.T004](#gmmvp004) - -- [ ] (GM.MVP.T005) Extend templates; more guides. +#### Observability & Analytics + + +- [ ] (GM.ALPHA.T007) Structured logging; sampling options. > [!INFO]- Step-by-step Instructions -> - [ ] Audit existing docs templates for gaps. -> - [ ] Add missing sections (TOC hints, status guidance). -> - [ ] Update docs tooling lint to confirm compliance. -> - [ ] Announce templates in contributor guide. +> - [ ] Design logging schema for CBOR debug tracing. +> - [ ] Implement sampling controls (env/config toggles). +> - [ ] Update ops docs with usage examples. +> - [ ] Add tests ensuring logs redact sensitive content. +> [!NOTE]- Dependencies +> - [GM.ALPHA.T004](#gmalpha004) - -- [ ] (GM.MVP.T006) Tune AGENTS summaries; monthly rollup. +### Beta + +#### Core & Platform + + +- [ ] (GM.BETA.T001) Extend multi-author rollups; surface in CLI output. > [!INFO]- Step-by-step Instructions -> - [ ] Define monthly rollup process for AGENTS highlights. -> - [ ] Automate summary generation or provide script. -> - [ ] Update AGENTS.md with new cadence instructions. -> - [ ] Verify pre-commit hook enforces formatting. +> - [ ] Extend attribution data structure to track multiple authors/time windows. +> - [ ] Update cache/journal serialization to carry additional metadata. +> - [ ] Add CLI flags to display attribution columns. +> - [ ] Document workflow and examples in attribution architecture doc. +> [!NOTE]- Dependencies +> - [GM.ALPHA.T004](#gmalpha004) +> - [GM.MVP.T002](#gmmvp002) + +### v1.0.0 + +#### Core & Platform + + +- [ ] (GM.V1.T001) Finalize strict equality enforcement across core. +> [!INFO]- Step-by-step Instructions +> - [ ] Harmonize equality helpers in cache/journal/util modules. +> - [ ] Add regression tests covering mixed OID/string paths. +> - [ ] Update `docs/TECHNICAL.md` and ADRs with strict behavior guarantees. +> - [ ] Sweep references to legacy SHA fallbacks in docs/examples. +> [!NOTE]- Dependencies +> - [GM.ALPHA.T001](#gmalpha001) +> - [GM.MVP.T001](#gmmvp001) + + +- [ ] (GM.V1.T002) Sweep remaining safe-string/memory stragglers and docs. +> [!INFO]- Step-by-step Instructions +> - [ ] Grep for raw `strcpy`/`sprintf` usage outside approved wrappers. +> - [ ] Replace with `gm_snprintf`/`gm_strcpy_safe` equivalents. +> - [ ] Update safety documentation and examples. +> - [ ] Add unit coverage where new wrappers are introduced. +> [!NOTE]- Dependencies +> - [GM.MVP.T001](#gmmvp001) - [ ] (GM.V1.T003) Optional heuristics for worksheet gates. @@ -328,24 +400,11 @@ features=3 > - [ ] Implement optional flag to enable heuristics in gate tooling. > - [ ] Document opt-in usage and backward compatibility. > - [ ] Add tests covering heuristic outcomes. +> [!NOTE]- Dependencies +> - [GM.MVP.T005](#gmmvp005) +> - [GM.MVP.T006](#gmmvp006) -### Observability & Analytics - - -- [ ] (GM.ALPHA.T007) Structured logging; sampling options. -> [!INFO]- Step-by-step Instructions -> - [ ] Design logging schema for CBOR debug tracing. -> - [ ] Implement sampling controls (env/config toggles). -> - [ ] Update ops docs with usage examples. -> - [ ] Add tests ensuring logs redact sensitive content. - - -- [ ] (GM.MVP.T007) Expose CLI summary; automate weekly snapshots. -> [!INFO]- Step-by-step Instructions -> - [ ] Implement CLI summary command reading ledger progress. -> - [ ] Automate snapshot job (cron/workflow) updating docs. -> - [ ] Document snapshot cadence for contributors. -> - [ ] Add regression test verifying README sync. +#### Observability & Analytics - [ ] (GM.V1.T004) Collect tidy counts and failures; render trends. @@ -354,28 +413,30 @@ features=3 > - [ ] Store trend data (JSON/CSV) for dashboards. > - [ ] Render trend visualization in docs/dashboard. > - [ ] Document maintenance workflow for trend data. +> [!NOTE]- Dependencies +> - [GM.ALPHA.T007](#gmalpha007) +> - [GM.MVP.T007](#gmmvp007) ## Completeness | Task | Started? | Finished? | Tested? | Shipped? | |------|----------|-----------|---------|----------| -| [GM.V1.T001](#gmv1t001) | 🚫 | 🚫 | 🚫 | 🚫 | -| [GM.ALPHA.T001](#gmalpha001) | 🚫 | 🚫 | 🚫 | 🚫 | -| [GM.ALPHA.T002](#gmalpha002) | 🚫 | 🚫 | 🚫 | 🚫 | | [GM.MVP.T001](#gmmvp001) | 🚫 | 🚫 | 🚫 | 🚫 | -| [GM.V1.T002](#gmv1t002) | 🚫 | 🚫 | 🚫 | 🚫 | -| [GM.ALPHA.T003](#gmalpha003) | 🚫 | 🚫 | 🚫 | 🚫 | | [GM.MVP.T002](#gmmvp002) | 🚫 | 🚫 | 🚫 | 🚫 | -| [GM.BETA.T001](#gmbeta001) | 🚫 | 🚫 | 🚫 | 🚫 | -| [GM.ALPHA.T004](#gmalpha004) | 🚫 | 🚫 | 🚫 | 🚫 | -| [GM.ALPHA.T005](#gmalpha005) | 🚫 | 🚫 | 🚫 | 🚫 | | [GM.MVP.T003](#gmmvp003) | 🚫 | 🚫 | 🚫 | 🚫 | | [GM.MVP.T004](#gmmvp004) | 🚫 | 🚫 | 🚫 | 🚫 | -| [GM.ALPHA.T006](#gmalpha006) | 🚫 | 🚫 | 🚫 | 🚫 | | [GM.MVP.T005](#gmmvp005) | 🚫 | 🚫 | 🚫 | 🚫 | | [GM.MVP.T006](#gmmvp006) | 🚫 | 🚫 | 🚫 | 🚫 | -| [GM.V1.T003](#gmv1t003) | 🚫 | 🚫 | 🚫 | 🚫 | -| [GM.ALPHA.T007](#gmalpha007) | 🚫 | 🚫 | 🚫 | 🚫 | | [GM.MVP.T007](#gmmvp007) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.ALPHA.T001](#gmalpha001) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.ALPHA.T002](#gmalpha002) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.ALPHA.T003](#gmalpha003) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.ALPHA.T004](#gmalpha004) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.ALPHA.T005](#gmalpha005) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.ALPHA.T006](#gmalpha006) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.ALPHA.T007](#gmalpha007) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.BETA.T001](#gmbeta001) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.V1.T001](#gmv1t001) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.V1.T002](#gmv1t002) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.V1.T003](#gmv1t003) | 🚫 | 🚫 | 🚫 | 🚫 | | [GM.V1.T004](#gmv1t004) | 🚫 | 🚫 | 🚫 | 🚫 | - diff --git a/docs/features/images/task_dag.dot b/docs/features/images/task_dag.dot new file mode 100644 index 00000000..23a94aa5 --- /dev/null +++ b/docs/features/images/task_dag.dot @@ -0,0 +1,124 @@ +digraph G { + rankdir=LR; + graph [pad="0.5", nodesep="0.6", ranksep="1.0"]; + node [shape=box, style=filled, fontname="IBM Plex Sans", fontsize=10]; + subgraph cluster_MVP { + label="Milestone: MVP"; + color="#666666"; + subgraph cluster_MVP_Core { + label="Core"; + color="#aaaaaa"; + "GM.MVP.T001" [label="GM.MVP.T001 +Finalize strict equality", fillcolor="#ffe599"]; + "GM.MVP.T002" [label="GM.MVP.T002 +Negative tests for ref utils", fillcolor="#ffe599"]; + } + subgraph cluster_MVP_CLI { + label="CLI"; + color="#aaaaaa"; + "GM.MVP.T003" [label="GM.MVP.T003 +Extend CLI safety tests", fillcolor="#cfe2f3"]; + "GM.MVP.T004" [label="GM.MVP.T004 +Query subcommands & diagnostics", fillcolor="#cfe2f3"]; + } + subgraph cluster_MVP_Docs { + label="Docs"; + color="#aaaaaa"; + "GM.MVP.T005" [label="GM.MVP.T005 +Extend docs templates", fillcolor="#ead1dc"]; + "GM.MVP.T006" [label="GM.MVP.T006 +Tune AGENTS rollup", fillcolor="#ead1dc"]; + } + subgraph cluster_MVP_Observability { + label="Observability"; + color="#aaaaaa"; + "GM.MVP.T007" [label="GM.MVP.T007 +CLI summary & snapshots", fillcolor="#d9ead3"]; + } + } + subgraph cluster_Alpha { + label="Milestone: Alpha"; + color="#666666"; + subgraph cluster_Alpha_Core { + label="Core"; + color="#aaaaaa"; + "GM.ALPHA.T001" [label="GM.ALPHA.T001 +Journal ordering tests", fillcolor="#ffe599"]; + "GM.ALPHA.T002" [label="GM.ALPHA.T002 +Cache perf tuning", fillcolor="#ffe599"]; + "GM.ALPHA.T003" [label="GM.ALPHA.T003 +Edge diff coverage", fillcolor="#ffe599"]; + "GM.ALPHA.T004" [label="GM.ALPHA.T004 +Sandbox transactions", fillcolor="#ffe599"]; + } + subgraph cluster_Alpha_CLI { + label="CLI"; + color="#aaaaaa"; + "GM.ALPHA.T005" [label="GM.ALPHA.T005 +Post-commit AUGMENTS wiring", fillcolor="#cfe2f3"]; + "GM.ALPHA.T006" [label="GM.ALPHA.T006 +GraphQL auto-resolve flag", fillcolor="#cfe2f3"]; + } + subgraph cluster_Alpha_Observability { + label="Observability"; + color="#aaaaaa"; + "GM.ALPHA.T007" [label="GM.ALPHA.T007 +Structured logging & sampling", fillcolor="#d9ead3"]; + } + } + subgraph cluster_Beta { + label="Milestone: Beta"; + color="#666666"; + subgraph cluster_Beta_Core { + label="Core"; + color="#aaaaaa"; + "GM.BETA.T001" [label="GM.BETA.T001 +Multi-author attribution rollups", fillcolor="#ffe599"]; + } + } + subgraph cluster_v1_0_0 { + label="Milestone: v1.0.0"; + color="#666666"; + subgraph cluster_v1_0_0_Core { + label="Core"; + color="#aaaaaa"; + "GM.V1.T001" [label="GM.V1.T001 +Strict equality enforcement", fillcolor="#ffe599"]; + "GM.V1.T002" [label="GM.V1.T002 +Safe-string sweep", fillcolor="#ffe599"]; + } + subgraph cluster_v1_0_0_CLI { + label="CLI"; + color="#aaaaaa"; + "GM.V1.T003" [label="GM.V1.T003 +Worksheet heuristics", fillcolor="#cfe2f3"]; + } + subgraph cluster_v1_0_0_Observability { + label="Observability"; + color="#aaaaaa"; + "GM.V1.T004" [label="GM.V1.T004 +CI trend baselines", fillcolor="#d9ead3"]; + } + } + "GM.MVP.T001" -> "GM.MVP.T002"; + "GM.MVP.T003" -> "GM.MVP.T004"; + "GM.MVP.T005" -> "GM.MVP.T006"; + "GM.MVP.T005" -> "GM.MVP.T007"; + "GM.MVP.T001" -> "GM.ALPHA.T001"; + "GM.ALPHA.T001" -> "GM.ALPHA.T002"; + "GM.ALPHA.T002" -> "GM.ALPHA.T003"; + "GM.ALPHA.T003" -> "GM.ALPHA.T004"; + "GM.MVP.T002" -> "GM.ALPHA.T004"; + "GM.ALPHA.T004" -> "GM.ALPHA.T005"; + "GM.MVP.T004" -> "GM.ALPHA.T006"; + "GM.ALPHA.T004" -> "GM.ALPHA.T007"; + "GM.ALPHA.T004" -> "GM.BETA.T001"; + "GM.MVP.T002" -> "GM.BETA.T001"; + "GM.ALPHA.T001" -> "GM.V1.T001"; + "GM.MVP.T001" -> "GM.V1.T001"; + "GM.MVP.T001" -> "GM.V1.T002"; + "GM.MVP.T005" -> "GM.V1.T003"; + "GM.MVP.T006" -> "GM.V1.T003"; + "GM.ALPHA.T007" -> "GM.V1.T004"; + "GM.MVP.T007" -> "GM.V1.T004"; +} \ No newline at end of file diff --git a/docs/features/images/task_dag.svg b/docs/features/images/task_dag.svg new file mode 100644 index 00000000..5ce6b7d8 --- /dev/null +++ b/docs/features/images/task_dag.svg @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:fb1670e921d978622de76135fd03752326b92c6142703f1fa17b886332777608 +size 7743 From a4cac3a6b19c72488fdd248e212bf22ca664c81d Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Thu, 18 Sep 2025 04:45:49 -0700 Subject: [PATCH 41/42] docs: regenerate tasklist and dependency svg --- docs/features/Features_Ledger.md | 332 ++++++++++++------------------ docs/features/images/task_dag.svg | 4 +- 2 files changed, 134 insertions(+), 202 deletions(-) diff --git a/docs/features/Features_Ledger.md b/docs/features/Features_Ledger.md index aef178bb..3cd17ded 100644 --- a/docs/features/Features_Ledger.md +++ b/docs/features/Features_Ledger.md @@ -120,322 +120,254 @@ MVP 74% | ALPHA 73% | BETA 55% | V1.0.0 82% Use the ledger as the single system of record from ideation through release: -1. **Capture (Planned)** — When a new idea lands (roadmap review, retro, support signal), add a row under the appropriate group with a short name, owning area, and initial KLoC estimate. Link to any discovery notes/spec drafts in the “Spec” column and file a task in the `## Tasklist` section if further framing is needed. -2. **Framing (Planned → In Progress)** — Once scope and acceptance criteria are clear, mark status `In Progress`, ensure the “Current State” block describes the baseline, and list outstanding engineering/design work in the “Todo (Tasks)” column. Keep KLoC estimates realistic as tickets are broken down. -3. **Build & Land (In Progress)** — Engineers ship code behind feature flags/guards. Update progress % weekly (or when a significant chunk lands) and log validation tasks (tests, docs, follow-up stories). Reference the primary implementation branches/paths in the “Code” column. -4. **Validation (MVP)** — When the feature is usable end-to-end for the target persona, flip status to `MVP`. Document rollout steps, known gaps, and add stabilization tasks (dogfooding, bug bashes) to the ledger’s task list. -5. **Hardening (Alpha/Beta)** — Scale to broader audiences, tighten reliability/perf, and ensure telemetry/observability is live. Integrate feedback into Todo, tag follow-up tasks with `[Alpha]` or `[Beta]` as appropriate. -6. **General Availability (v1.0.0)** — All quality bars met, docs/tests complete, downstream consumers notified. Continue to attach post-GA follow-ups (deprecation notices, future enhancements) either as new ledger entries or subtasks in the Notes section. - -Operational rules: - -- Every feature row must have: owning area, milestone tag, spec/code pointers, KLoC estimate, status, progress %, and actionable Todo/Triage notes. Update KLoC when scope materially changes. -- The `## Tasklist` checklist is the authoritative backlog for cross-cutting work. Sync it whenever Todo items are resolved or re-scoped. -- README’s “📊 Status” reflects the overall milestone-weighted bar automatically; run `make features-update` after edits. -- For net-new features, create discovery docs in `docs/` and link them before moving past Planned. -- Retire legacy items by marking status `Deprecated` (optional column note) and migrating remaining tasks to successors. - ---- - -### Core & Platform - -```text -████████████████████████████████░░░░░░░░ 79% -------------|-------------|------------| - MVP Alpha v1.0.0 -features=8 -``` - - -| Emoji | Feature | Area | Spec | Code | Milestone | KLoC (approx) | Status | Progress % | Bar | Current State | Tests | Remarks | -| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | -| 🧱 | OID‑first Core | Core | — | core/include, core/src | v1.0.0 | 3.5 | Alpha | 85% | █████████░ | Equality OID‑first; OID fields in CBOR; cache/journal aligned. | Unit passing | Good foundation. | -| 🗄️ | Journal (CBOR) | Core | docs/architecture/journal-architecture-pivot.md | core/src/journal, core/src/cbor | Alpha | 1.2 | Alpha | 80% | ████████░░ | Writer/reader with base64; debug flag; attributed edges. | Unit passing | Backwards compat OK. | -| ⚡ | Cache (Bitmap) | Core | docs/architecture/bitmap-cache-design.md | core/src/cache | Alpha | 1.6 | In Progress | 75% | ███████░░░ | Rebuild + query; shard; metadata. | Unit partial | Added branch-limit + tree-size coverage. | -| 🔗 | Ref Utilities | Core | docs/architecture/Ref_Name_Validation.md | core/src/util | MVP | 0.5 | MVP | 75% | ███████░░░ | `gm_build_ref` with validation; tests. | Unit | Good coverage. | -| 🧰 | Safe String/Memory | Core | — | core/include/gitmind/util | v1.0.0 | 0.4 | V1 | 90% | █████████░ | Safe wrappers adopted in hot paths. | Unit | Security uplift. | -| 🕸️ | Edge Graph Engine | Core | docs/architecture/System_Architecture.md | core/src/edge, core/include/gitmind/edge | Alpha | 1.0 | Alpha | 75% | ████████░░ | ULID-ordered edges; journal append + cache hydration. | Unit + fuzz | Forms graph spine. | -| 🧬 | Semantics & Type System | Core | docs/architecture/System_Architecture.md | core/src/types, core/src/utf8, core/src/time | MVP | 2.7 | Alpha | 80% | ████████░░ | Stable hashed IDs; NFC normalization; time-safe stamping. | Unit | Ready for consumers. | -| 🪪 | Attribution Metadata | Core | docs/architecture/attribution-system.md | core/src/attribution | Beta | 0.2 | In Progress | 55% | ██████░░░░ | Capture author/time for edges; merge helpers in place. | Unit scaffolding | Needs UX polish. | -| 🗂️ | Sandbox Transactions | Core | docs/talk-shop/Sandbox_Transactions.md | core/src/journal (planned) | Alpha | 0.8 | Planned | 5% | █░░░░░░░░░ | Pending refs + CLI flow to stage/apply journal mutations safely. | Planned | Draft RFC merged. | - -### CLI, Hooks & UX - -```text -████████████████████████████░░░░░░░░░░░░ 69% -------------|-------------|------------| - MVP Alpha v1.0.0 -features=7 -``` - - -| Emoji | Feature | Area | Spec | Code | Milestone | KLoC (approx) | Status | Progress % | Bar | Current State | Tests | Remarks | -| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | -| 🪝 | Post‑commit Hook (AUGMENTS) | Hooks | docs/hooks | core/src/hooks | Alpha | 0.5 | In Progress | 50% | █████░░░░░ | Process changed files; AUGMENTS edge. | Unit | Wire to journal read. | -| 🔒 | CLI Safety Guard | CLI | docs/operations/Environment_Variables.md | apps/cli/cli_runtime.c | MVP | 0.6 | MVP | 70% | ███████░░░ | Official repo guard; env override; safe install workflow. | Unit | Solid baseline. | -| 🛠️ | `git mind` CLI Commands | CLI | apps/cli/main.md | apps/cli | MVP | 1.2 | MVP | 65% | ██████░░░░ | `link`, `list`, cache rebuild; shared runtime utilities. | Unit + manual | Ready for daily use. | -| 🧰 | Review Seeding & Replies | DX | docs/tools | tools/review, workflows | Alpha | 0.4 | MVP | 80% | ████████░░ | Seed + auto‑reply; artifact fallback; reply templates rendered cleanly. | CI + unit | High leverage. | -| 📜 | Docs Tooling | Docs | docs/tools | tools/docs | MVP | 0.4 | MVP | 70% | ███████░░░ | Frontmatter/TOC/title checks; labeler. | Scripted | Good base. | -| 🧭 | Curated AGENTS.md | DX | docs | tools/agents | MVP | 0.2 | MVP | 80% | ████████░░ | TL;DR + YAML; curator; archives. | Scripted | Fast onboarding. | -| 🧪 | Worksheet Gates | DX | docs/tools | tools/review | Alpha | 0.3 | V1 | 90% | █████████░ | Pre‑push checks for placeholders + decisions. | Scripted | Keeps quality high. | - -### Observability & Analytics - -```text -█████████████████████▓░░░░░░░░░░░░░░░░░░ 53% -------------|-------------|------------| - MVP Alpha v1.0.0 -features=3 -``` - - -| Emoji | Feature | Area | Spec | Code | Milestone | KLoC (approx) | Status | Progress % | Bar | Current State | Tests | Remarks | -| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | -| 🔎 | CBOR Debug Tracing | Core/Obs | docs/operations | core/src/journal | Alpha | 0.2 | MVP | 60% | ██████░░░░ | Env flag for verbose decode. | Unit | Helpful during migration. | -| 📈 | Progress Ledgers | DX/Obs | docs/features | scripts | MVP | 0.3 | MVP | 70% | ███████░░░ | Ledger + updater script; KLoC-weighted bars + README sync. | Scripted | Improves planning. | -| 📊 | CI Trend Baselines | Obs | docs/ci | tools | v1.0.0 | 0.2 | Planned | 20% | ██░░░░░░░░ | Not started. | Planned | Future. | - -## Tasklist -## Tasklist +1. **Capture (Planned)** — When a new idea lands (roadmap review, retro, support signal), add a row under the appropriate group with a short name, owning area, and initial KLoC estimate. Link to any discovery notes/spec drafts in the “Spec” column and file a task in the `## Tasklist ![Task Dependency Map](images/task_dag.svg) ### MVP -#### Core & Platform +#### Core - -- [ ] (GM.MVP.T001) Finalize strict equality; docs complete. + +- [ ] (GM.MVP.T001) Finalize strict equality > [!INFO]- Step-by-step Instructions -> - [ ] Audit equality helpers in cache/journal and ensure OID-first comparisons never fall back when OIDs exist. -> - [ ] Add regression tests covering mixed OID/string paths. -> - [ ] Update `docs/TECHNICAL.md` and related ADRs to document the strict behavior. -> - [ ] Sweep references to legacy SHA fallbacks in docs/examples. +> - [ ] Audit equality helpers in cache and journal to ensure OID-first comparisons never fall back when OIDs exist. +> - [ ] Add regression tests covering mixed OID/string paths across cache and journal utilities. +> - [ ] Update `docs/TECHNICAL.md` and any relevant ADRs to document strict equality behavior. +> - [ ] Sweep references to legacy SHA fallbacks in docs and CLI examples. > [!NOTE]- Dependencies > - (none) - -- [ ] (GM.MVP.T002) Add negative tests and docs for ref utilities. + +- [ ] (GM.MVP.T002) Negative tests for ref utils > [!INFO]- Step-by-step Instructions > - [ ] Extend `test_ref_utils` to cover invalid prefixes, length overflows, and reserved refs. > - [ ] Ensure errors propagate with meaningful `GM_ERR_*` codes. -> - [ ] Update docstrings and `docs/architecture/Ref_Name_Validation.md` with new failure cases. +> - [ ] Update `docs/architecture/Ref_Name_Validation.md` with new failure scenarios. > - [ ] Mention failure scenarios in README/tutorial examples. > [!NOTE]- Dependencies -> - [GM.MVP.T001](#gmmvp001) +> - **Hard:** [GM.MVP.T001](#gmmvpt001) -#### CLI, Hooks & UX +#### CLI - -- [ ] (GM.MVP.T003) Extend host override tests; document upgrade path. + +- [ ] (GM.MVP.T003) Extend CLI safety tests > [!INFO]- Step-by-step Instructions -> - [ ] Expand CLI safety tests to cover new env overrides. -> - [ ] Document the upgrade path in `docs/operations/Environment_Variables.md`. -> - [ ] Announce safe override usage in README/CLI help. -> - [ ] Confirm behavior in Docker CI harness. +> - [ ] Expand CLI safety guard tests to cover host override permutations. +> - [ ] Document the override matrix in `docs/operations/Environment_Variables.md`. +> - [ ] Highlight safe override usage in README/CLI help. +> - [ ] Verify behavior in Docker CI harness. > [!NOTE]- Dependencies > - (none) - -- [ ] (GM.MVP.T004) Add query subcommands; richer diagnostics. + +- [ ] (GM.MVP.T004) Query subcommands & diagnostics > [!INFO]- Step-by-step Instructions -> - [ ] Design subcommand syntax and update CLI help output. -> - [ ] Implement parsing + output formatting for new queries. -> - [ ] Write unit/integration tests for diagnostics coverage. -> - [ ] Update tutorial examples and docs. +> - [ ] Design CLI syntax and update command help output for new query modes. +> - [ ] Implement parsing and output formatting for diagnostic flags. +> - [ ] Add unit/integration tests for diagnostic output. +> - [ ] Update tutorial examples with new query flows. > [!NOTE]- Dependencies -> - [GM.MVP.T003](#gmmvp003) +> - **Hard:** [GM.MVP.T003](#gmmvpt003) - -- [ ] (GM.MVP.T005) Extend docs templates and guides. +#### Docs + + +- [ ] (GM.MVP.T005) Extend docs templates > [!INFO]- Step-by-step Instructions -> - [ ] Audit existing docs templates for gaps (status blocks, TOC conventions). -> - [ ] Add missing sections and update template examples. -> - [ ] Enhance docs lint to verify new expectations. -> - [ ] Announce updates in contributor guide. +> - [ ] Audit existing document templates for missing sections (status, TOC guidance, review notes). +> - [ ] Add missing sections and refresh template examples. +> - [ ] Update docs tooling lint to enforce new expectations. +> - [ ] Announce template changes in the contributor guide. > [!NOTE]- Dependencies > - (none) - -- [ ] (GM.MVP.T006) Tune AGENTS summaries; monthly rollup. + +- [ ] (GM.MVP.T006) Tune AGENTS monthly rollup > [!INFO]- Step-by-step Instructions -> - [ ] Define monthly rollup process for AGENTS highlights. -> - [ ] Provide script or automation to generate summaries. +> - [ ] Define the monthly rollup cadence for AGENTS summaries. +> - [ ] Provide a script or automation to generate rollups. > - [ ] Update `AGENTS.md` with cadence instructions. -> - [ ] Verify pre-commit hook enforces formatting. +> - [ ] Verify the pre-commit hook enforces the new format. > [!NOTE]- Dependencies -> - [GM.MVP.T005](#gmmvp005) +> - **Soft:** [GM.MVP.T005](#gmmvpt005) + +#### Observability - -- [ ] (GM.MVP.T007) Expose CLI summary; automate weekly progress snapshots. + +- [ ] (GM.MVP.T007) CLI summary & snapshots > [!INFO]- Step-by-step Instructions -> - [ ] Implement a CLI summary command reading ledger progress. -> - [ ] Automate a cron/workflow to update snapshot outputs. -> - [ ] Document snapshot cadence for contributors. +> - [ ] Implement CLI summary command reading ledger progress. +> - [ ] Automate a cron/workflow to publish weekly snapshots. +> - [ ] Document the snapshot cadence and expectations. > - [ ] Add regression test verifying README/ledger sync. > [!NOTE]- Dependencies -> - [GM.MVP.T005](#gmmvp005) +> - **Soft:** [GM.MVP.T005](#gmmvpt005) ### Alpha -#### Core & Platform +#### Core - -- [ ] (GM.ALPHA.T001) Finalize ordering; add tests for CBOR journal reader. + +- [ ] (GM.ALPHA.T001) Journal ordering tests > [!INFO]- Step-by-step Instructions -> - [ ] Write table-driven tests validating iteration order across branches. -> - [ ] Exercise attributed vs. plain edge decoding paths. -> - [ ] Patch reader docs to reflect ordering guarantees. -> - [ ] Wire tests into `meson.build` and ensure they run in CI. +> - [ ] Write table-driven tests exercising journal iteration order across branches. +> - [ ] Cover both plain and attributed edges in CBOR fixtures. +> - [ ] Document ordering guarantees in journal reader docs. +> - [ ] Wire new tests into `meson.build` and CI. > [!NOTE]- Dependencies -> - [GM.MVP.T001](#gmmvp001) +> - **Hard:** [GM.MVP.T001](#gmmvpt001) - -- [ ] (GM.ALPHA.T002) Perf tuning + shard benchmarks. + +- [ ] (GM.ALPHA.T002) Cache perf tuning & benchmarks > [!INFO]- Step-by-step Instructions -> - [ ] Capture baseline timings for cache rebuild/query across representative repos. +> - [ ] Capture baseline rebuild/query timings across representative repos. > - [ ] Profile shard fan-out hotspots and prototype optimizations. -> - [ ] Automate a lightweight benchmark harness (Docker-safe) to guard regressions. -> - [ ] Document results in `docs/architecture/bitmap-cache-design.md`. +> - [ ] Automate a Docker-safe benchmark harness for regressions. +> - [ ] Document findings in `docs/architecture/bitmap-cache-design.md`. > [!NOTE]- Dependencies -> - [GM.ALPHA.T001](#gmalpha001) +> - **Hard:** [GM.ALPHA.T001](#gmalphat001) - -- [ ] (GM.ALPHA.T003) Edge diff coverage; multi-branch stress harness. + +- [ ] (GM.ALPHA.T003) Edge diff coverage > [!INFO]- Step-by-step Instructions -> - [ ] Create fixture branches with divergent edge histories to prove diff stability. +> - [ ] Create fixture branches with divergent edge histories to stress diffs. > - [ ] Add integration tests comparing fan-in/out across merge commits. -> - [ ] Ensure cache/journal diff helpers handle branch fan-out. +> - [ ] Ensure cache/journal diff helpers handle branch fan-out scenarios. > - [ ] Document the harness in `docs/architecture/System_Architecture.md`. > [!NOTE]- Dependencies -> - [GM.ALPHA.T002](#gmalpha002) +> - **Hard:** [GM.ALPHA.T002](#gmalphat002) - -- [ ] (GM.ALPHA.T004) Implement sandbox txn start/apply/abort; hook integration. + +- [ ] (GM.ALPHA.T004) Sandbox transactions > [!INFO]- Step-by-step Instructions > - [ ] Implement `gm_txn_start/apply/abort` helpers manipulating pending refs. > - [ ] Build CLI plumbing (`git mind txn ...`) with dry-run/apply flows. > - [ ] Add local/server hook snippets to enforce provenance. > - [ ] Ship documentation updates (RFC, roadmap, tutorial snippet). > [!NOTE]- Dependencies -> - [GM.ALPHA.T003](#gmalpha003) -> - [GM.MVP.T002](#gmmvp002) +> - **Hard:** [GM.ALPHA.T003](#gmalphat003) +> - **Hard:** [GM.MVP.T002](#gmmvpt002) - -- [ ] (GM.ALPHA.T005) Post-commit AUGMENTS wiring. +#### CLI + + +- [ ] (GM.ALPHA.T005) Post-commit AUGMENTS wiring > [!INFO]- Step-by-step Instructions > - [ ] Finish journal read integration and handle path truncation errors. > - [ ] Add end-to-end test demonstrating AUGMENTS edges emitted via hooks. -> - [ ] Document error/fallback behavior in hooks guide. -> - [ ] Verify containerized tests cover new path. +> - [ ] Document error/fallback behavior in hook guides. +> - [ ] Verify containerized tests cover the new path. > [!NOTE]- Dependencies -> - [GM.ALPHA.T004](#gmalpha004) +> - **Hard:** [GM.ALPHA.T004](#gmalphat004) - -- [ ] (GM.ALPHA.T006) Gate GraphQL auto-resolve behind flag; document validation; GH App roadmap. + +- [ ] (GM.ALPHA.T006) GraphQL auto-resolve flag > [!INFO]- Step-by-step Instructions -> - [ ] Introduce feature flag controlling auto-resolve behavior. +> - [ ] Introduce a feature flag controlling auto-resolve behavior. > - [ ] Document validation workflow with screenshots in Review Seeding docs. > - [ ] Outline GH App roadmap clarifying future automation. -> - [ ] Add regression tests around new flag default. +> - [ ] Add regression tests around the new flag default. > [!NOTE]- Dependencies -> - [GM.MVP.T004](#gmmvp004) +> - **Hard:** [GM.MVP.T004](#gmmvpt004) -#### Observability & Analytics +#### Observability - -- [ ] (GM.ALPHA.T007) Structured logging; sampling options. + +- [ ] (GM.ALPHA.T007) Structured logging & sampling > [!INFO]- Step-by-step Instructions > - [ ] Design logging schema for CBOR debug tracing. -> - [ ] Implement sampling controls (env/config toggles). -> - [ ] Update ops docs with usage examples. +> - [ ] Implement sampling controls (environment/config toggles). +> - [ ] Update operations docs with usage examples. > - [ ] Add tests ensuring logs redact sensitive content. > [!NOTE]- Dependencies -> - [GM.ALPHA.T004](#gmalpha004) +> - **Hard:** [GM.ALPHA.T004](#gmalphat004) ### Beta -#### Core & Platform +#### Core - -- [ ] (GM.BETA.T001) Extend multi-author rollups; surface in CLI output. + +- [ ] (GM.BETA.T001) Multi-author attribution rollups > [!INFO]- Step-by-step Instructions -> - [ ] Extend attribution data structure to track multiple authors/time windows. -> - [ ] Update cache/journal serialization to carry additional metadata. +> - [ ] Extend attribution data structure to track multiple authors and time windows. +> - [ ] Update cache/journal serialization to carry new metadata. > - [ ] Add CLI flags to display attribution columns. -> - [ ] Document workflow and examples in attribution architecture doc. +> - [ ] Document workflow and examples in attribution docs. > [!NOTE]- Dependencies -> - [GM.ALPHA.T004](#gmalpha004) -> - [GM.MVP.T002](#gmmvp002) +> - **Hard:** [GM.ALPHA.T004](#gmalphat004) +> - **Soft:** [GM.MVP.T002](#gmmvpt002) ### v1.0.0 -#### Core & Platform +#### Core -- [ ] (GM.V1.T001) Finalize strict equality enforcement across core. +- [ ] (GM.V1.T001) Strict equality enforcement > [!INFO]- Step-by-step Instructions -> - [ ] Harmonize equality helpers in cache/journal/util modules. -> - [ ] Add regression tests covering mixed OID/string paths. -> - [ ] Update `docs/TECHNICAL.md` and ADRs with strict behavior guarantees. -> - [ ] Sweep references to legacy SHA fallbacks in docs/examples. +> - [ ] Harmonize equality helpers across cache/journal/util modules. +> - [ ] Add regression tests covering strict equality edges-to-cache interactions. +> - [ ] Document long-term guarantees in architecture docs. +> - [ ] Ensure release notes highlight the enforcement. > [!NOTE]- Dependencies -> - [GM.ALPHA.T001](#gmalpha001) -> - [GM.MVP.T001](#gmmvp001) +> - **Hard:** [GM.ALPHA.T001](#gmalphat001) +> - **Hard:** [GM.MVP.T001](#gmmvpt001) -- [ ] (GM.V1.T002) Sweep remaining safe-string/memory stragglers and docs. +- [ ] (GM.V1.T002) Safe-string sweep > [!INFO]- Step-by-step Instructions > - [ ] Grep for raw `strcpy`/`sprintf` usage outside approved wrappers. > - [ ] Replace with `gm_snprintf`/`gm_strcpy_safe` equivalents. > - [ ] Update safety documentation and examples. > - [ ] Add unit coverage where new wrappers are introduced. > [!NOTE]- Dependencies -> - [GM.MVP.T001](#gmmvp001) +> - **Hard:** [GM.MVP.T001](#gmmvpt001) + +#### CLI -- [ ] (GM.V1.T003) Optional heuristics for worksheet gates. +- [ ] (GM.V1.T003) Worksheet heuristics > [!INFO]- Step-by-step Instructions > - [ ] Define heuristic rules (placeholder detection, decision coverage). -> - [ ] Implement optional flag to enable heuristics in gate tooling. +> - [ ] Implement optional flag enabling heuristics in gate tooling. > - [ ] Document opt-in usage and backward compatibility. > - [ ] Add tests covering heuristic outcomes. > [!NOTE]- Dependencies -> - [GM.MVP.T005](#gmmvp005) -> - [GM.MVP.T006](#gmmvp006) +> - **Hard:** [GM.MVP.T005](#gmmvpt005) +> - **Soft:** [GM.MVP.T006](#gmmvpt006) -#### Observability & Analytics +#### Observability -- [ ] (GM.V1.T004) Collect tidy counts and failures; render trends. +- [ ] (GM.V1.T004) CI trend baselines > [!INFO]- Step-by-step Instructions > - [ ] Instrument CI to capture tidy counts and unit failures. > - [ ] Store trend data (JSON/CSV) for dashboards. > - [ ] Render trend visualization in docs/dashboard. > - [ ] Document maintenance workflow for trend data. > [!NOTE]- Dependencies -> - [GM.ALPHA.T007](#gmalpha007) -> - [GM.MVP.T007](#gmmvp007) +> - **Hard:** [GM.ALPHA.T007](#gmalphat007) +> - **Soft:** [GM.MVP.T007](#gmmvpt007) ## Completeness | Task | Started? | Finished? | Tested? | Shipped? | |------|----------|-----------|---------|----------| -| [GM.MVP.T001](#gmmvp001) | 🚫 | 🚫 | 🚫 | 🚫 | -| [GM.MVP.T002](#gmmvp002) | 🚫 | 🚫 | 🚫 | 🚫 | -| [GM.MVP.T003](#gmmvp003) | 🚫 | 🚫 | 🚫 | 🚫 | -| [GM.MVP.T004](#gmmvp004) | 🚫 | 🚫 | 🚫 | 🚫 | -| [GM.MVP.T005](#gmmvp005) | 🚫 | 🚫 | 🚫 | 🚫 | -| [GM.MVP.T006](#gmmvp006) | 🚫 | 🚫 | 🚫 | 🚫 | -| [GM.MVP.T007](#gmmvp007) | 🚫 | 🚫 | 🚫 | 🚫 | -| [GM.ALPHA.T001](#gmalpha001) | 🚫 | 🚫 | 🚫 | 🚫 | -| [GM.ALPHA.T002](#gmalpha002) | 🚫 | 🚫 | 🚫 | 🚫 | -| [GM.ALPHA.T003](#gmalpha003) | 🚫 | 🚫 | 🚫 | 🚫 | -| [GM.ALPHA.T004](#gmalpha004) | 🚫 | 🚫 | 🚫 | 🚫 | -| [GM.ALPHA.T005](#gmalpha005) | 🚫 | 🚫 | 🚫 | 🚫 | -| [GM.ALPHA.T006](#gmalpha006) | 🚫 | 🚫 | 🚫 | 🚫 | -| [GM.ALPHA.T007](#gmalpha007) | 🚫 | 🚫 | 🚫 | 🚫 | -| [GM.BETA.T001](#gmbeta001) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.MVP.T001](#gmmvpt001) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.MVP.T002](#gmmvpt002) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.MVP.T003](#gmmvpt003) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.MVP.T004](#gmmvpt004) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.MVP.T005](#gmmvpt005) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.MVP.T006](#gmmvpt006) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.MVP.T007](#gmmvpt007) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.ALPHA.T001](#gmalphat001) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.ALPHA.T002](#gmalphat002) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.ALPHA.T003](#gmalphat003) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.ALPHA.T004](#gmalphat004) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.ALPHA.T005](#gmalphat005) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.ALPHA.T006](#gmalphat006) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.ALPHA.T007](#gmalphat007) | 🚫 | 🚫 | 🚫 | 🚫 | +| [GM.BETA.T001](#gmbetat001) | 🚫 | 🚫 | 🚫 | 🚫 | | [GM.V1.T001](#gmv1t001) | 🚫 | 🚫 | 🚫 | 🚫 | | [GM.V1.T002](#gmv1t002) | 🚫 | 🚫 | 🚫 | 🚫 | | [GM.V1.T003](#gmv1t003) | 🚫 | 🚫 | 🚫 | 🚫 | diff --git a/docs/features/images/task_dag.svg b/docs/features/images/task_dag.svg index 5ce6b7d8..9ee10707 100644 --- a/docs/features/images/task_dag.svg +++ b/docs/features/images/task_dag.svg @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:fb1670e921d978622de76135fd03752326b92c6142703f1fa17b886332777608 -size 7743 +oid sha256:c0fdf4f5251c242b9f91aad3c0f4a857ec4dec8eeed5a1654f43aacb57d3e47f +size 7678 From 21d29c357bee5e1ec71c03c90dec961850fe7518 Mon Sep 17 00:00:00 2001 From: "J. Kirby Ross" Date: Thu, 18 Sep 2025 04:59:31 -0700 Subject: [PATCH 42/42] docs: tweak dependency dag layout --- docs/features/images/task_dag.svg | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/features/images/task_dag.svg b/docs/features/images/task_dag.svg index 9ee10707..c0985e52 100644 --- a/docs/features/images/task_dag.svg +++ b/docs/features/images/task_dag.svg @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:c0fdf4f5251c242b9f91aad3c0f4a857ec4dec8eeed5a1654f43aacb57d3e47f -size 7678 +oid sha256:976b572cc44264c386c3c0b9b809787b611853908f57b42e6b3931fbf4fb80f3 +size 7963