v1simple-internal

Public engineering-context companion to v1simple/v1simple.

The repository name describes its role inside the project: it contains architecture context, sanitized plans and reviews, structured work tracking, hardware-validation schemas, and the tooling that checks those records. It is not a private-data store.

The firmware repository remains standalone. Its build, tests, and releases do not depend on this companion.

Safety model

Everything committed here is public.

• Commit and tag metadata must use a GitHub noreply address or noreply@example.invalid.
• Tracked snapshots are scanned for personal email addresses, local home directories, common secret formats, and embedded author metadata.
• Pre-commit and pre-push hooks block unsafe identities, unsafe snapshots, force pushes, deletions, and publication outside the public ref allowlist.
• Public CI reruns the privacy scanners and their regression suites.
• Raw device artifacts, local overlays, caches, claims, and generated reports remain ignored.
• This repository never stores private backup branches or mirrors.

These checks reduce accidental disclosure risk; they do not replace review. Before publication, inspect the complete staged snapshot and outgoing history.

Layout

AGENTS.md    contributor and automation contract
agent/       architecture, invariants, and test guidance
config/      versioned schemas and sanitized project records
scripts/     diagnostics and guarded workflow commands
tests/       regression tests for companion tooling
docs/        public plans, reviews, references, and hardware guidance
reviews/     dated audits of repository work
var/         disposable local caches and raw outputs (ignored)

Start every session with the doctor

The doctor is read-only. It verifies repository identities, required paths, worktree state, branch publication policy, audit freshness, and local release evidence:

python3 scripts/v1i.py doctor

The firmware repository defaults to the sibling path ../v1simple. Override it when needed:

V1SIMPLE_PUBLIC_REPO=/path/to/v1simple python3 scripts/v1i.py doctor
python3 scripts/v1i.py doctor --public-repo /path/to/v1simple

Use --strict before finishing and --release for release preparation.

Install local guards

git config core.hooksPath .githooks
python3 .githooks/commit-msg --selftest

Use a privacy-safe repository identity:

git config user.name v1simple
git config user.email noreply@example.invalid

Verification

python3 -m unittest discover -s tests -p 'test_*.py'
python3 scripts/test_check_public_commit_metadata.py
python3 scripts/test_check_public_snapshot_privacy.py
python3 scripts/test_public_privacy_hooks.py
python3 scripts/check_public_commit_metadata.py
python3 scripts/check_public_snapshot_privacy.py
python3 scripts/v1i.py self-check

Publication

Only main, release tags, and transient GitHub-managed Dependabot branches under dependabot/github_actions/ may exist on the public remote. Development branches remain local. Published refs are append-only.

The first public release of this repository starts from one audited root commit. Its former private history and backup refs remain isolated in a separate private archive and are not ancestors of public main.