Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 14 additions & 14 deletions .aipass/tier1_navmap.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,15 @@

AIPass: autonomous agents (citizens) with identity, memory, and a mailbox, serving each other and external projects. Each lives in a branch, its home and address. Everything routes through `drone`. Open source, public repo: strangers read this code; treat their findings as contributions.

# Platform — Linux only

AIPass runs on Linux: native, WSL2, or the Docker image. Windows and macOS are not maintained; a port is the community's. Not abandonment: the owner's lifetime project and daily driver, open source forever. A user this affects: open a GitHub discussion or issue tagged `transition` with their setup; we help them find their path (Docker, WSL2, a fork).

# Terminology

- Branch — directory `src/aipass/<name>/`, your home and address.
- Agent (citizen) — persistent identity in a branch: passport (`.trinity/`), memories, mailbox. Addressable as `@name`.
- Sub-agent — disposable worker for one task. No passport, no memory, not a citizen.
- Sub-agent — disposable worker for one task. No passport, no memory.
- Registry — machine-managed catalogs (`registry.json`, flow, spawn); never hand-edit.
- Settings — provider files under `~/.claude` and `~/.codex` are the user's, a gate refuses AI edits · project `.claude/settings.json` ships with the clone, `settings.local.json` overrides it.
- Your four directories — `docs/` tracked reference · `docs.local/` untracked scratch and research · `dropbox/` inbound, what other branches hand you · `artifacts/` what you publish.
Expand Down Expand Up @@ -54,8 +58,8 @@ Citizens dispatch each other directly. One question: does the recipient need to

- Need an answer or work: `dispatch` (send + wake); a sleeping agent never reads plain email.
- FYI only (status, steering an agent already awake): `email`.
- Replies never wake; wake-back does: when an agent you dispatched completes, you are woken to verify and hand off.
- Managers (`citizen_class: manager`, e.g. @devpulse) are never dispatched; `email` them, they see it live.
- Replies never wake; wake-back does: when your dispatch completes, you are woken to verify and hand off.
- Managers (`citizen_class: manager`, e.g. @devpulse) are never dispatched; `email` them.

Always reply to dispatches — reply auto-closes. No silent completions.

Expand All @@ -66,25 +70,21 @@ Create only via `drone @flow create <path> "Subject" [type]`, never by hand: man
- DPLAN — dev plan: thinking, architecture, before building.
- FPLAN — flow plan, the default: building. `master` = multi-phase, spawns sub-FPLANs.
- PPLAN — playbook: a throwaway run of a reusable SOP. Operating the system, not changing it.
- RPLAN — research: a trace, a study of an external repo, a measurement. Brief, report path and verdict live in it.
- RPLAN — research: a trace, a study, a measurement. Brief, report path and verdict live in it.
- APLAN — autonomous work, an audit or a night shift. CPLAN capture, TDPLAN team dev. `drone @flow templates` lists all seven.

# Sub-agents

- Default to sub-agents for reading, searching, building, testing, research; yourself only for tiny edits, your own memories and plans.
- One clear task per agent, briefed with full context as a file: they know nothing of your conversation; a paraphrase loses the clause.
- No git, no memory, no dispatch: they build and report, you decide and act. Read every diff; a pass count stays green through a deleted docstring and an oracle that cannot fail.
- One clear task per agent, briefed with full context as a file: they know nothing of your conversation.
- No git, no memory, no dispatch: they build and report, you decide and act. Read every diff; a pass count stays green through a deleted docstring.
- HELD is an answer: a cure the brief did not name, or whose own mutant survives, stops there; say HELD and why.
- Branch-expert work → dispatch a citizen; else → a sub-agent.
- Models: opus to build and analyse, sonnet for routine investigation, haiku for trivial mechanics. Never fable.
- Branch-expert work → dispatch a citizen; else a sub-agent.
- Models: opus to build and analyse, sonnet to investigate, haiku for trivial mechanics. Never fable.

# Chrome — the claude-in-chrome MCP

Built into Claude Code; drives the desktop's default-profile Chrome with the owner's live sign-ins. Never `--user-data-dir`, never a hand-written DISPLAY.

- Chrome down: `python3 tools/open_chrome.py` in `Projects/Vera-Studio/src/vera_studio/vera`.
- Connect: `list_connected_browsers`, `select_browser <deviceId>`, `tabs_context_mcp {createIfEmpty:true}`.
- `[]` or "extension is not connected" with Chrome up: the extension is signed out or asleep; no shell step cures it, the owner clicks the Claude icon once. CAPTCHAs and credentials are the owner's.
Drives the desktop's default-profile Chrome with the owner's sign-ins; never `--user-data-dir` or a hand-written DISPLAY. Connect: `list_connected_browsers`, `select_browser`, `tabs_context_mcp`. `[]` with Chrome up: the extension is asleep, the owner clicks the Claude icon. CAPTCHAs and credentials are the owner's.

# Memory — .trinity/

Expand All @@ -99,7 +99,7 @@ Save proactively — after milestones, decisions, topic switches.

# House rules

- Public repo — write as if it ships, because it does. No secrets in the tree, no hardcoded paths (`pathlib`, never `/home/...`), cross-platform.
- Public repo — write as if it ships, because it does. No secrets in the tree, no hardcoded paths (`pathlib`, never `/home/...`), Linux only.
- No bare imports — always `from aipass.<agent>.apps...`.
- State lives in `.trinity/` and dashboards, never in prompts. Prompts are signposts; memories record; registries catalog.
- New test files need permission: a hook gate refuses them by policy (`.aipass/test_write_policy.json`); editing an existing test is fine. Need one? Mail @devpulse the defect it pins.
Expand Down
116 changes: 8 additions & 108 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -1,21 +1,17 @@
name: CI

# Transition lane (the owner, 2026-11-08): AIPass is Linux only and PRs must
# land in minutes. This file runs lint alone. The full lane (pytest matrix,
# sentry-audit, coverage) sits beside it as ci.yml(full_disabled), unread by
# Actions; tests still run locally and on the daemon's schedule. Restore it by
# renaming back once the Linux-only structure settles.

on:
# push fires on main only (post-merge validation). Dev work is always PR'd
# within minutes, so push+pull_request on dev double-ran every job — the PR
# event alone carries the required checks.
push:
branches: [main]
pull_request:
branches: [main, dev]

# One run per ref at a time, and a RUNNING run is never cancelled: a new push
# queues behind it (GitHub keeps at most one pending run per group). Until
# 2026-09-08 this was cancel-in-progress: true, and eight landings pushed
# within hours on 2026-09-07/08 erased every in-flight verdict; the first
# completed matrix showed 13 reds with no wave to attribute them to
# (RPLAN-0004 in sentry, finding 2.5). A verdict that finishes is worth the
# runner minutes it costs on a public repo.
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: false
Expand All @@ -29,109 +25,13 @@ env:
jobs:
lint:
runs-on: ubuntu-latest
timeout-minutes: 30
timeout-minutes: 10
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: "3.13"
# Hash-pinned tool install (Scorecard: Pinned-Dependencies). Pins ruff to
# the version this lint gate is known-green against; see .github/requirements/lint.in.
# Hash-pinned tool install (Scorecard: Pinned-Dependencies); see .github/requirements/lint.in.
- run: python -m pip install --require-hashes -r .github/requirements/lint.txt
- run: ruff check src/ tests/
- run: ruff format --check src/ tests/

test:
strategy:
fail-fast: false
matrix:
python-version: ["3.10", "3.11", "3.12", "3.13"]
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: ${{ matrix.python-version }}
- run: |
python -m pip install --require-hashes -r .github/requirements/pip.txt
pip install -e ".[dev,host]"
# tests/e2e build a wheel + clean venv per the dedicated e2e-wheel.yml
# workflow — they are not part of the fast unit lane.
# Plain pytest: this job's old `coverage run` wrapper produced data that
# was never reported anywhere (the coverage job collects its own) — it
# only slowed all four matrix legs.
# xdist (DPLAN-0277 phase 1b): loadscope keeps each test class on one
# worker. The suite's shared-state hygiene was fixed for this — see the
# repo-root conftest.py guard — and proven over repeated full runs.
# --timeout (pytest-timeout, a dev extra): one hung test used to take the
# whole job to its 30-minute cap with no traceback — PR #774 round three,
# run 38087470864, the 3.10 leg sat 26 min behind one api socket test and
# the summary never printed. A per-test ceiling fails that one test with
# the stack of where it sat; the slowest honest test here is under 2 min.
# --timeout-method thread: the default signal method cannot interrupt a
# wait inside C (a lock, a portal join), and round five's macOS leg hung
# past its 300 s ceiling that way (run 38100884450, memory's search test
# FAILED then its worker never reported again). The thread method dumps
# every thread's stack and exits the worker; xdist marks the test failed
# and carries on, so the job ends with evidence instead of a cancel.
# --max-worker-restart 0: a worker that dies outright ("node down: Not
# properly terminated") ends the session red with the in-flight test
# named. Round five's macOS leg (run 38100884450) let xdist replace the
# dead worker and the session never finished: 8 minutes of silence, then
# the job cap, no summary. A dead worker is a red; say so in one line.
- run: pytest -v --tb=short --rootdir=. --ignore=tests/e2e -n auto --dist loadscope --timeout 300 --timeout-method thread --max-worker-restart 0

standards:
name: sentry-audit
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
# Full history: stale_header_date (2026-09-25) reads `git log` for the
# last commit touching each test file. A shallow (depth-1) checkout
# makes every file look born at HEAD, so that checker DECLINES there
# rather than guess. Full history makes CI match a local audit exactly.
# (This once served a README-freshness check that no longer reads git.)
fetch-depth: 0
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: "3.13"
- run: |
python -m pip install --require-hashes -r .github/requirements/pip.txt
# Install the `memory` extra (numpy/chromadb/fastembed) alongside dev:
# the diagnostics standard runs pyright over every branch, and memory's
# handlers import chromadb/numpy. Without these deps installed, pyright
# reports them as unresolved imports (reportMissingImports=error) and
# memory scores <100 — a false failure from a missing CI dep, not a code
# defect. Installing the declared extra lets pyright resolve them so the
# audit measures real type-correctness (and matches a local audit).
pip install -e ".[dev,memory]"
# Public repo: no developer's home path in any tracked text file (the owner,
# 2026-10-04). Reads git ls-files; exit 1 on a hit, 2 when it could not measure.
- name: No developer home path in tracked files
run: python -m aipass.sentry.apps.sentry home-paths scan
- name: Run sentry standards audit
run: python .github/scripts/sentry_audit.py

coverage:
name: coverage
# No `needs: [test]` — it re-runs the suite itself, so chaining it after
# the matrix only serialized the two longest jobs (~13 min critical path).
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: "3.13"
- run: |
python -m pip install --require-hashes -r .github/requirements/pip.txt
pip install -e ".[dev,host]"
- run: coverage run -m pytest --rootdir=. --ignore=tests/e2e --timeout 300 --timeout-method thread
- run: coverage xml
- uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
with:
files: ./coverage.xml
fail_ci_if_error: false
137 changes: 137 additions & 0 deletions .github/workflows/ci.yml(full_disabled)
Original file line number Diff line number Diff line change
@@ -0,0 +1,137 @@
name: CI

on:
# push fires on main only (post-merge validation). Dev work is always PR'd
# within minutes, so push+pull_request on dev double-ran every job — the PR
# event alone carries the required checks.
push:
branches: [main]
pull_request:
branches: [main, dev]

# One run per ref at a time, and a RUNNING run is never cancelled: a new push
# queues behind it (GitHub keeps at most one pending run per group). Until
# 2026-09-08 this was cancel-in-progress: true, and eight landings pushed
# within hours on 2026-09-07/08 erased every in-flight verdict; the first
# completed matrix showed 13 reds with no wave to attribute them to
# (RPLAN-0004 in sentry, finding 2.5). A verdict that finishes is worth the
# runner minutes it costs on a public repo.
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: false

permissions:
contents: read

env:
FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"

jobs:
lint:
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: "3.13"
# Hash-pinned tool install (Scorecard: Pinned-Dependencies). Pins ruff to
# the version this lint gate is known-green against; see .github/requirements/lint.in.
- run: python -m pip install --require-hashes -r .github/requirements/lint.txt
- run: ruff check src/ tests/
- run: ruff format --check src/ tests/

test:
strategy:
fail-fast: false
matrix:
python-version: ["3.10", "3.11", "3.12", "3.13"]
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: ${{ matrix.python-version }}
- run: |
python -m pip install --require-hashes -r .github/requirements/pip.txt
pip install -e ".[dev,host]"
# tests/e2e build a wheel + clean venv per the dedicated e2e-wheel.yml
# workflow — they are not part of the fast unit lane.
# Plain pytest: this job's old `coverage run` wrapper produced data that
# was never reported anywhere (the coverage job collects its own) — it
# only slowed all four matrix legs.
# xdist (DPLAN-0277 phase 1b): loadscope keeps each test class on one
# worker. The suite's shared-state hygiene was fixed for this — see the
# repo-root conftest.py guard — and proven over repeated full runs.
# --timeout (pytest-timeout, a dev extra): one hung test used to take the
# whole job to its 30-minute cap with no traceback — PR #774 round three,
# run 38087470864, the 3.10 leg sat 26 min behind one api socket test and
# the summary never printed. A per-test ceiling fails that one test with
# the stack of where it sat; the slowest honest test here is under 2 min.
# --timeout-method thread: the default signal method cannot interrupt a
# wait inside C (a lock, a portal join), and round five's macOS leg hung
# past its 300 s ceiling that way (run 38100884450, memory's search test
# FAILED then its worker never reported again). The thread method dumps
# every thread's stack and exits the worker; xdist marks the test failed
# and carries on, so the job ends with evidence instead of a cancel.
# --max-worker-restart 0: a worker that dies outright ("node down: Not
# properly terminated") ends the session red with the in-flight test
# named. Round five's macOS leg (run 38100884450) let xdist replace the
# dead worker and the session never finished: 8 minutes of silence, then
# the job cap, no summary. A dead worker is a red; say so in one line.
- run: pytest -v --tb=short --rootdir=. --ignore=tests/e2e -n auto --dist loadscope --timeout 300 --timeout-method thread --max-worker-restart 0

standards:
name: sentry-audit
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
# Full history: stale_header_date (2026-09-25) reads `git log` for the
# last commit touching each test file. A shallow (depth-1) checkout
# makes every file look born at HEAD, so that checker DECLINES there
# rather than guess. Full history makes CI match a local audit exactly.
# (This once served a README-freshness check that no longer reads git.)
fetch-depth: 0
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: "3.13"
- run: |
python -m pip install --require-hashes -r .github/requirements/pip.txt
# Install the `memory` extra (numpy/chromadb/fastembed) alongside dev:
# the diagnostics standard runs pyright over every branch, and memory's
# handlers import chromadb/numpy. Without these deps installed, pyright
# reports them as unresolved imports (reportMissingImports=error) and
# memory scores <100 — a false failure from a missing CI dep, not a code
# defect. Installing the declared extra lets pyright resolve them so the
# audit measures real type-correctness (and matches a local audit).
pip install -e ".[dev,memory]"
# Public repo: no developer's home path in any tracked text file (the owner,
# 2026-10-04). Reads git ls-files; exit 1 on a hit, 2 when it could not measure.
- name: No developer home path in tracked files
run: python -m aipass.sentry.apps.sentry home-paths scan
- name: Run sentry standards audit
run: python .github/scripts/sentry_audit.py

coverage:
name: coverage
# No `needs: [test]` — it re-runs the suite itself, so chaining it after
# the matrix only serialized the two longest jobs (~13 min critical path).
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: "3.13"
- run: |
python -m pip install --require-hashes -r .github/requirements/pip.txt
pip install -e ".[dev,host]"
- run: coverage run -m pytest --rootdir=. --ignore=tests/e2e --timeout 300 --timeout-method thread
- run: coverage xml
- uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
with:
files: ./coverage.xml
fail_ci_if_error: false
Loading
Loading