cacrespo / cacrespo/handshake

ci(agent): documentation consistency & architectural drift verifier agent in CI

Open
#32 0 comments 0 reactions 0 assignees View on GitHub
documentation enhancement
Dominant language
Python
Stars
0
Forks
0
Avg merge
2m
Merged PRs (30d)
1

Description

## Overview
As the project evolves across multiple protocol implementations (Python core, Web TypeScript/React, DuckDB WASM), documentation and architectural principles risk drifting out of sync.
We want an automated CI agent / workflow that inspects documentation, specifications (`docs/protocol.md`, `README.md`, etc.), and code changes in PRs to alert whenever changes deviate from foundational architectural definitions.

## Key Components

### 1. Architectural Invariants Specification
- Formalize core project invariants in a single source of truth (e.g. `docs/architecture-invariants.md`):
- Deterministic Ed25519 cryptography, 32-byte seeds, signature verification rules.
- Storage engine agnosticism with DuckDB as reference implementation (matching schemas between Python and DuckDB-WASM).
- Decentralized privacy-first topology: zero tracker persistence, ephemeral local-first presence, strictly localized geohash precision.
- Offline-first gossip synchronization model (strata-sync over WebRTC and BLE).

### 2. CI Verification Agent (`.github/workflows/docs-consistency.yml`)
- Automated workflow triggered on Pull Requests modifying `docs/`, `src/`, or `web/`.
- Runs an LLM agent / linter script that compares the PR git diff against the architectural invariants and protocol specs.
- Automatically comments on PRs or flags warnings for:
- Discrepancies between protocol documentation and code implementation.
- Architectural violations (e.g. introducing centralized state, breaking schema symmetry, insecure crypto primitives).
- Outdated or broken cross-references in docs.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading docs/protocol.md and README.md, then review the Python, Web TypeScript/React, and DuckDB-WASM areas named in the issue. Define the proposed docs/architecture-invariants.md source of truth and examine the PR trigger scope for .github/workflows/docs-consistency.yml. Done means the workflow checks relevant diffs and reports documentation inconsistencies or architectural violations.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, python, react, typescript, wasm
Domain
ci-cd, devops, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.