@nidvue/teamwork 0.0.0-stage → 1.1.1

package/skills/teamwork/references/Remotes.md

@@ -0,0 +1,144 @@
+# Remotes - repository and CI integrity on any git host
+
+Owner: Release Engineer. The skill is remote-agnostic: the *policy* below is the
+contract, and the host table says how to configure it on GitHub, GitLab,
+Bitbucket, Gitea/Forgejo, Azure DevOps or a bare server. Configuration is not
+optional decoration - unprotected integrity is the failure this file exists to
+prevent.
+
+## The integrity policy (host-neutral)
+
+1. **The default branch is protected.**
+   - no direct commits: every change arrives through a reviewable request;
+   - no force-push and no history rewrite: an already-published commit is
+     immutable (the single exception is a privacy purge, which is a CEO red line
+     and is recorded);
+   - no deletion of the branch or of a tag;
+   - linear history: no merge commits on the default branch.
+2. **Required status checks.** A merge is impossible while any required check is
+   red, on the exact merged revision:
+   - the test matrix (every supported OS x Python), lint, build + release
+     verification, the privacy scan, and the strict docs build;
+   - the checks are *required*, not advisory: "the release engineer saw it pass
+     locally" is not a check;
+   - require the branch to be up to date with the default branch before merge
+     (strict mode), so a green run cannot be stale;
+   - **a required check must always be reported.** A workflow skipped by a path
+     filter produces no check run at all, so a documentation-only pull request
+     would wait forever for a check that can never appear. Path filters belong on
+     `push` (a cost optimisation); on `pull_request` the required workflows run
+     unconditionally. This is the most common way branch protection deadlocks a
+     repository.
+3. **Required review.** At least one approval from a role that is not the author
+   - in this team, the **Reviewer**. Self-approval is impossible; a new commit on
+   the request dismisses the stale approval; the Reviewer - never the author -
+   performs the merge.
+4. **Merge strategy - one canonical shape.**
+   - feature work: **squash** into one commit on the default branch, so history
+     reads as one coherent change-set per task;
+   - delete the source branch on merge;
+   - releases: a tag on a commit that is already green on the default branch; never
+     tag an unmerged branch, never move a published tag;
+   - no `merge commit` and no `rebase merge` as a default, because they hide the
+     squash boundary.
+5. **Ref and secret hygiene.**
+   - protected tag pattern `v*`, created only by the CEO;
+   - CI least privilege: workflow default `contents: read`, each job widening only
+     what it needs; attestation/OIDC only where used;
+   - no secret in the tree, in a workflow log or in a prompt - the privacy scan is
+     the gate, and the host secret store is the only place a value lives;
+   - third-party actions/images pinned to a version (SHA pinning is the follow-up
+     for anything with write permission).
+6. **Verification is evidence, not assumption.** The Release Engineer records the
+   protection rules, the required checks and the merge settings, and periodically
+   re-reads them from the host API to detect drift. A protection change is a
+   governance event: recorded in `Decisions.md` with who changed it and why.
+
+## Single-owner repositories (the honest caveat)
+
+`required_approving_review_count = 1` cannot be satisfied by the author, and a host
+will not let you approve your own request. On a repository with one account that
+means either:
+
+- add a second collaborator (or a second account/bot with review rights) so a real
+  approval can happen - the preferred answer; or
+- keep `enforce_admins = false` so the owner can bypass the approval for their own
+  authorized work - and then **every bypass is a recorded governance event**: who,
+  when, which revision, and why the internal Reviewer verdict stands in for the
+  host approval.
+
+Do not set the approval count to zero to make life easier: that silently deletes
+the review gate for everyone else too. State which of the two applies in
+`Release.md`, and re-read it during the drift check.
+
+## Host mapping
+
+| Policy | GitHub | GitLab | Bitbucket Cloud | Gitea / Forgejo | Azure DevOps |
+|---|---|---|---|---|---|
+| protect default branch | branch protection / Rulesets (`PATCH .../branches/main/protection`) | protected branches | branch restrictions | branch protection | branch policies |
+| no force-push / delete | `allow_force_pushes=false`, `allow_deletions=false` | "Allowed to force push" off | "Prevent rewriting history" | "Enable force push" off | "Require a merge strategy" + locks |
+| required checks | `required_status_checks` (strict) | "Pipelines must succeed" | merge checks | "Require status checks" | build validation policy |
+| required review | `required_pull_request_reviews` | merge request approvals | default reviewers | "Require approvals" | "Require a minimum number of reviewers" |
+| dismiss stale approval | `dismiss_stale_reviews=true` | "Reset approvals on push" | merge check | "Dismiss stale approvals" | "Reset votes on new pushes" |
+| squash-only, delete branch | repo `allow_squash_merge=true`, `allow_merge_commit=false`, `allow_rebase_merge=false`, `delete_branch_on_merge=true` | project merge method `ff`/squash + "Delete source branch" | merge strategy setting | "Squash merge only" | "Squash merge" + delete source branch |
+| protected tags | tag protection rules / Rulesets | protected tags | (use branch restrictions on the release branch) | protected tags | tag policies via a pipeline gate |
+| least-privilege CI | workflow `permissions:` | job `rules` + protected variables | pipelines `deployment` permissions | Actions permissions | pipeline permissions + variable groups |
+| code scanning as a gate | `code-scanning/alerts?state=open` (`--commit` routes the fixes) | SAST report in the MR / `vulnerabilities` API | Pipeline security report | integrated scanners (`gosec` via Actions) | Advanced Security alerts |
+| bare git server | `update` hook / `pre-receive` + `receive.denyNonFastForwards` | - | - | - | - |
+
+## Minimum viable protection (what must be on)
+
+| Setting | Value | Why |
+|---|---|---|
+| direct push to default branch | denied (admin bypass allowed only for an authorized purge) | review cannot be skipped |
+| force-push | denied | published history is immutable |
+| branch deletion | denied | the default branch cannot disappear |
+| required checks | the CI matrix + privacy + docs, strict | nothing red merges |
+| required approvals | >= 1, non-author, stale-dismissing | the two-stage gate is real |
+| merge method | squash only | one change-set per task |
+| delete branch on merge | on | no branch debt |
+| tag protection | `v*`, CEO only | a release is deliberate |
+
+## Evidence shape
+
+```
+gh api repos/<owner>/<repo>/branches/main/protection @<rev> -> required_checks=[CI, privacy, docs],
+  enforce_admins=false, allow_force_pushes=false, allow_deletions=false, required_approvals=1,
+  dismiss_stale_reviews=true
+gh api repos/<owner>/<repo> --jq '.allow_squash_merge,.allow_merge_commit,.allow_rebase_merge,.delete_branch_on_merge'
+  @<rev> -> true false false true
+gh run list --workflow CI --commit <sha> @<rev> -> success (all matrix jobs)
+teamwork.py code-scanning @<rev> -> 0 open alerts (or: N blocking -> P0 tasks filed to the file owners)
+```
+
+## Code scanning is part of the release signal
+
+On a forge that scans code (GitHub code scanning, GitLab SAST, Azure Advanced
+Security), an open `error`/`critical`/`high` alert on the default branch is a
+known defect **in the shipped revision**: the code is already public, so the
+alert is a release blocker, not a backlog item. Two measured examples on this
+repository's own remote, both `py/clear-text-logging-sensitive-data` on
+`scripts/privacy_scan.py`, both `error`, both on `main` with no task and no owner.
+
+The Release Engineer owns the gate:
+
+```sh
+teamwork.py code-scanning            # plan: alert -> owning role, exit 1 while blocking
+teamwork.py code-scanning --commit    # file one P0 task per (owner, rule, file)
+```
+
+Routing follows file ownership (`SCAN_ROUTE` in `src/teamwork/config.py`); the
+Security Auditor owns `scripts/privacy_scan.py` and the triage of a genuine
+false positive, the Developer owns `src/**` and `tests/**`, the Release Engineer
+owns `.github/**` and unfiled alerts. Dismissing an alert is a recorded
+triage, never a way to quiet the gate. Re-read after the fix lands and record
+the alert numbers and the `gh api` command as evidence, exactly like a CI run id.
+
+## Drift check
+
+Re-read the settings and compare with the table above; a missing or weakened
+setting is a defect of the same severity as a red build, routed to the Release
+Engineer and closed only with the API output as evidence. If the host cannot
+express a rule, say so and record the compensating control (for example: a bare
+server with a `pre-receive` hook, or a release checklist item that a human
+verifies) - never leave it silently unprotected.

package/skills/teamwork/references/Roles.md

@@ -0,0 +1,201 @@
+# Roles, handoffs and decision rights
+
+Reference for the /teamwork skill. Loaded on demand.
+
+Related: [Engineering](Engineering.md) | [Evidence](Evidence.md) | [Docs](Docs.md) | [State](State.md) | [Concurrency](Concurrency.md) | [Testing](Testing.md) | [Audit](Audit.md)
+
+## Roster
+
+| Role | Instances | Owns | Reports to |
+|---|---|---|---|
+| CEO | leader session, never spawned | user interface, decomposition, assignment, arbitration, global memory, final report | user |
+| CTO | `cto` | technology strategy, feasibility, stack, engineering standards, the build/release *policy*, and the engineering lanes | CEO |
+| COO | `coo` | process, tooling, dependencies, risk register, planning and throughput | CEO |
+| CFO | `cfo` | cost model, budget, unit economics, build-vs-buy, ROI | CEO |
+| Product Manager | `product-manager` | competitor/state-of-the-art research, stories, requirements, acceptance criteria, traceability, and the product/documentation lanes | CEO |
+| Reviewer | `reviewer` or `reviewer-1..N` | independent second review of **every** deliverable; **the only role that passes review and merges into `main`** | CEO |
+| Security Auditor | `security-auditor` | security assessment, red lines, remediation verification; audits the whole team, CTO included | CEO |
+| Architect | `architect` | system/module/API/data/deployment architecture, **frozen interfaces**, ADRs | CTO |
+| Developer | `developer-1..N` | production code, **its own unit tests**, inline docs, commits on its branch | CTO |
+| Tester | `tester-1..N` | integration/system/E2E tests, running and monitoring them, defect routing, regression | CTO |
+| Release Engineer | `release-engineer` | build/release pipeline, CI gates, packaging, rollback, observability, runbooks | CTO |
+| Data Engineer *(conditional)* | `data-engineer` | schema, migrations, integrity, backup/restore drills, query health | CTO |
+| Project Manager | `project-manager` | `Plan.md`, `Board.md`, task decomposition, dependency graph, duplicate detection, progress chasing | COO |
+| Designer | `designer-1..N` | UX flows, accessibility, visual consistency, `Design.md` | Product Manager |
+| Technical Writer | `technical-writer` | the committed documentation set, executed as written; release notes | Product Manager |
+
+```text
+CEO - user interface, arbitration, final acceptance
+├── CTO - technology strategy, engineering standards
+│   ├── Architect - frozen interfaces, ADRs
+│   ├── Developer-1..N - code + its own unit tests
+│   ├── Tester-1..N - integration/E2E, local + CI
+│   ├── Release Engineer - pipeline, packaging, repo/CI integrity
+│   └── Data Engineer - schema, integrity, restore drills
+├── COO - process, risk, throughput
+│   └── Project Manager - plan, board, dependencies, chasing
+├── Product Manager - research, requirements, acceptance criteria
+│   ├── Designer - UX, accessibility, every visual asset
+│   └── Technical Writer - documentation, release notes
+├── CFO - cost, budget, unit economics
+├── Reviewer-1..N - independent review, the only pass/merge right
+└── Security Auditor - audits everyone, CTO included
+```
+
+**Why these three stay with the CEO.** The Reviewer passes and merges every
+deliverable, so it cannot be managed by a lane whose work it reviews - that would
+be review under a manager, not independent review. The Security Auditor audits the
+CTO's own decisions. The CFO holds the cap that binds every other role. Everything
+else hangs off the role that owns the standard it is judged by. `ROLE_PARENT` in
+`src/teamwork/config.py` is the single source of truth: `teamwork.py map` renders
+this tree and `tests/unit/test_reporting_hierarchy.py` fails if a doc drifts from it.
+
+**Escalation walks the tree.** A blocked Developer tells the Architect, then the
+CTO; a blocked Tester tells the CTO; a blocked Designer tells the Product Manager.
+The CEO hears it only when the line cannot resolve it - or when it is a red line,
+a goal change, or a decision that binds the whole team. This keeps the CEO out of
+day-to-day arbitration without weakening a single gate: the two-stage review, the
+ledger and the test matrix apply to every role wherever it sits.
+
+### Roster tiers
+
+`init --roster <tier>` expands a tier into instances; `--agents` overrides it.
+
+| Tier | Instances | Startup read |
+|---|---|---|
+| `slim` (default) | 6 | 226 kB |
+| `standard` | 9 | 336 kB |
+| `full` | 16 | 586 kB |
+
+Startup read = every instance's `AGENTS.md` plus its own role charter, summed
+(`engine.expand_roster(tier)` over `roles/*.md` and `templates/AGENTS.md`). A tier is a recipe, not a rule: add any role the brief
+justifies, and prefer an extra `developer-N`/`tester-N` over a coordination role.
+
+A tier drops **lanes**, not gates:
+
+| Dropped from `slim` | Where the work goes |
+|---|---|
+| product-manager | requirements, acceptance criteria and `Research.md` ride with the CEO |
+| project-manager | `Plan.md`/`Board.md` ride with the CEO; `pulse` does the chasing |
+| cto / coo | stack and process facts go in `Decisions.md`/`Risks.md` |
+| cfo | `Costs.md` only when the work has a real cost dimension |
+| designer | `ui` layer unstaffed |
+| technical-writer | `docs` layer unstaffed; authors write their own docs |
+| data-engineer | `data` layer unstaffed |
+| release-engineer | the CEO pushes after review |
+| security-auditor | `security` layer unstaffed |
+
+Two invariants hold at every tier, and both are tested:
+
+- `staffed_layers` only requires a layer whose owning role has an instance, so
+  `tests plan` never reports a gap for work nobody owns.
+- `required_tribunal` never drops below `TRIBUNAL_MIN_SIGNERS`: with no CTO/CFO,
+  the Reviewer is the neutral seat, and a party to a dispute can never rule it.
+
+`init` prints the folded lanes and warns when `ceo`, `developer`, `tester` or
+`reviewer` is missing (`ROSTER_REQUIRED`).
+
+### Roles we deliberately do not add
+
+A role earns a place only if it owns a distinct deliverable, a distinct test layer
+and a distinct decision right. On that bar these stay out, and their work is folded
+in as a lane rather than a role: marketing/sales (out of scope for an engineering
+team; the CEO can staff them if a project ships commercially), a separate QA lead
+(test strategy is the Tester's, test seams the Architect's), an accessibility
+specialist (Designer owns `ui`, Reviewer verifies), and a dedicated performance
+engineer (perf and load live in the Release Engineer's `release` layer and the
+Tester's `integration` layer). Adding these would add ceremony without adding a
+gate. **Staff two Reviewers** (`reviewer-1`,
+`reviewer-2`): a passing review merges its own PR, so the second lane exists to
+fan the *review* queue out, not to land what the first lane passed. Without a `reviewer` the team cannot pass review
+or merge; without an `architect` nothing freezes interfaces. `init` warns when
+either is missing.
+
+## Handoff chain
+
+```text
+user -> CEO -> Architect (freeze interfaces) -> Project Manager (task graph)
+                        |                              |
+                        v                              v
+        Developer / Tester / Designer lanes  <--  dispatch (pulse)
+                        |                              |
+                        v                              v
+                  SelfCheck (owner)  ->  PR  ->  Review (Reviewer)  ->  merge into main
+                        |                              |
+                        v                              v
+                  Product Manager (traceability)   Archive.md (evidence ledger)
+```
+
+Every handoff is a record, not a conversation: task state, PR record, review
+verdict, archive entry. A peer message is only a pointer to the record.
+
+## Decision rights
+
+| Decision | Who decides | Where it is recorded |
+|---|---|---|
+| What to build, priority, scope | CEO (Product Manager proposes) | `docs/Team/Project.md`, `Plan.md` |
+| Interfaces, architecture, ADRs | Architect (CTO consults) | `Architecture.md`, `Decisions.md` |
+| Stack, feasibility, build/release policy | CTO | `Decisions.md` |
+| Pipeline, packaging, rollback, observability | Release Engineer | `Release.md`, runbooks |
+| Documentation set and release notes | Technical Writer | the committed docs |
+| Schema, migrations, backup/restore | Data Engineer | migrations, data dictionary |
+| Cost, budget, build-vs-buy | CFO | `Costs.md` |
+| Process, risk register | COO | `Risks.md` |
+| Acceptance criteria and their verification | CEO writes; an independent role verifies | `Criteria.md` |
+| Review verdict | the Reviewer that verified it | task `review_status`, `Reviews.md` |
+| Merge into `main` | the pass itself, recorded by the Reviewer who verified it; the author is refused | merge commit, `Archive.md` |
+| Test layer ownership and required coverage | each layer's own role; the Architect declares the required layers | `Tests.md`, `TestPlan.md` |
+| Contested design/decision | tribunal: CEO + CTO + CFO, after 3 rounds | `Disputes.md` + `Decisions.md` |
+| Red-line refusal | blocked until the CEO relays explicit user authorization | `Global/GlobalMemory.md`, `Decisions.md` |
+| Final completion report | CEO to the user | user message + `Archive.md` |
+
+## Test layers (independent, parallel)
+
+Every role owns exactly one layer (see `Testing.md` for what each must verify):
+`goal` CEO · `requirements` Product Manager · `plan` Project Manager · `tech` CTO ·
+`release` Release Engineer · `data` Data Engineer · `process` COO · `cost` CFO ·
+`system` Architect · `ui` Designer · `docs` Technical Writer · `unit` Developer ·
+`integration` Tester · `acceptance` Reviewer · `security` Security Auditor.
+
+Default required coverage per area is the proportionate core set
+(`unit`, `integration`, `acceptance`); `tests require --area <a> --layers ... --by
+<instance> --reason <why>` widens or narrows it on the record. Every staffed role
+must design and run at least one test of its own layer.
+
+Each layer is designed, implemented and run by its owner; one record per
+(layer, area) prevents duplicate testing. Details: `{references}/Testing.md`.
+
+## Submission (the single canonical path)
+
+Every role that produces work uses this path; nothing else closes a task.
+
+```sh
+teamwork.py branch start --agent <you> --task <T-id> [--worktree]
+teamwork.py commit --role <role> --type <feat|fix|test|docs|design|research|refactor|chore> \
+    --task <T-id> --area <area> \
+    --goal "<what was asked>" --deliverable "<what you produced>" \
+    --why "<why this change>" --status "<actual state, truthfully>" \
+    --result "<command @rev -> observed result>" --all
+teamwork.py task set <role> <T-id> --status selfcheck
+teamwork.py selfcheck <role> <T-id> --by <Instance> --note "<what you re-read>" \
+    --test "<self-test command @rev -> observed result>"
+teamwork.py pr open --agent <Instance> --task <T-id>
+# Reviewer:
+teamwork.py review <role> <T-id> --by <Reviewer> --result pass --evidence "<verify cmd @rev -> result>"
+teamwork.py pr merge --pr <P-id> --by <reviewer>  # a pass already merged it;
+#                            use this only to land a --no-merge pass
+```
+
+A pass merges the deliverable at once and deletes its branch, so there is no
+second Reviewer step: the engine refuses an author merging their own work and
+records the pass-without-merge only when `--no-merge` is given.
+
+Charters do not restate this; they state what the role produces and decides.
+
+## Boundaries that apply to every role
+
+- Never contact the user; escalate to the CEO and keep working.
+- Never approve or merge your own work; only the Reviewer merges.
+- Never commit on `main`; work on your own branch.
+- Never fake evidence, weaken tests, or claim an unexecuted result.
+- Stop at a red line: record it, escalate, do other work meanwhile.

package/skills/teamwork/references/State.md

@@ -0,0 +1,64 @@
+# Memory and task state
+
+Reference for the /teamwork skill. Loaded on demand; `SKILL.md` keeps the
+operating procedure.
+
+Related: [Engineering](Engineering.md) | [Evidence](Evidence.md) | [Docs](Docs.md) | [State](State.md) | [Concurrency](Concurrency.md) | [Roles](Roles.md) | [Testing](Testing.md) | [Audit](Audit.md)
+
+## Memory model
+
+Each agent owns three markdown files in its directory; the CEO additionally owns
+the shared one. Management is via the script so caps and promotion are
+deterministic, not vibes.
+
+| Layer | File | Loaded | Purpose |
+|---|---|---|---|
+| Short-term | `ShortTermMemory.md` | at startup (`load`) | working memory for the current tasks |
+| Long-term | `LongTermMemory.md` | never; queried (`recall`) | durable facts, interfaces, gotchas |
+| Archive | `ArchivedMemory.md` | never; searchable | evicted long-term entries |
+| Shared | `Global/GlobalMemory.md` | read on demand | facts no agent should re-ask |
+
+```sh
+teamwork.py load <agent>                                  # startup context
+teamwork.py remember <agent> "<fact>" --key k --importance 0-5 [--pin]
+teamwork.py recall "<query>" --agent <agent> | --global | --all
+teamwork.py touch <agent> <key>                            # mark as used
+teamwork.py consolidate --all                              # auto maintenance
+teamwork.py global "<fact>" --key k --importance 4         # CEO only
+```
+
+Consolidation rules (automatic on `remember`/`load`, run manually by the CEO):
+
+- A short-term entry unused for `STALE_DAYS` (3) with fewer than `MIN_USES` (2)
+  uses is **promoted** to long-term when its importance >= 2, otherwise dropped.
+- Overflow beyond `SHORT_CAP` (24) is promoted or dropped by score.
+- Long-term is capped at `LONG_CAP` (64); the lowest-scoring entries (importance,
+  use count, recency) are moved to the archive, pinned entries are never evicted.
+- Duplicate keys merge: highest importance, summed uses, newest body.
+- Caps are configurable with `TEAMWORK_SHORT_CAP`, `TEAMWORK_LONG_CAP`,
+  `TEAMWORK_ARCHIVE_CAP`, `TEAMWORK_STALE_DAYS`, `TEAMWORK_MIN_USES`.
+
+What belongs where: task-local working notes and in-flight decisions in
+short-term; verified interfaces, commands, revisions, gotchas and rejected
+approaches in long-term; team-wide facts in global memory (CEO), proposed by the
+owner who discovered them.
+
+## Task lists and priority
+
+Every agent keeps a private `TaskQueue.md`, priority ordered. `P0` = critical path
+code, `P1` = tests/verification, `P2` = docs/polish, `P3` = nice-to-have.
+
+```sh
+teamwork.py task add <agent> "<title>" --priority P1 --deps architect:T-0003 \
+    --shared <issue/PR> --body "acceptance criteria"
+teamwork.py task next <agent>            # highest-priority task with deps done
+teamwork.py task list <agent>            # ready/blocked per task
+teamwork.py task set <agent> T-0002 --status doing
+teamwork.py task set <role> T-0002 --status selfcheck   # then selfcheck, pr open, review, pr merge
+teamwork.py board                        # all queues: counts, next task, blockers
+```
+
+Rules: dependencies are explicit (`agent:T-0001` for cross-agent), a task with
+unmet dependencies is never started, a finished task is marked `done` with
+evidence before the agent looks for the next one, and an agent with executable
+work never idles.

package/skills/teamwork/references/Testing.md

@@ -0,0 +1,144 @@
+# Layered testing - every agent tests its own work
+
+Reference for the /teamwork skill. Loaded on demand.
+
+Related: [Roles](Roles.md) | [Engineering](Engineering.md) | [Evidence](Evidence.md) | [State](State.md) | [Docs](Docs.md) | [Concurrency](Concurrency.md) | [Audit](Audit.md)
+
+## One layer per role
+
+Every agent designs, develops **and executes** its own independent tests, and
+evidences the run. No layer is delegated, and nobody substitutes for another
+role's layer.
+
+| Layer | Owner | What it must verify |
+|---|---|---|
+| `goal` | CEO | black-box: the delivered result actually meets the user's objective |
+| `requirements` | Product Manager | every requirement maps to a passing check; traceability is complete |
+| `plan` | Project Manager | plan integrity: dependency graph, duplicate work, milestone exit criteria |
+| `tech` | CTO | toolchain and dependency upgrades, feasibility spikes, version drills |
+| `release` | Release Engineer | reproducible build, CI gates, packaging, upgrade and rollback |
+| `data` | Data Engineer | schema and migrations, backfill, backup and restore drills |
+| `process` | COO | the documented workflow and tooling actually run end to end |
+| `cost` | CFO | metering, cap enforcement, unit-economics assertions |
+| `system` | Architect | architecture conformance: boundaries, dependency direction, contracts, ADRs |
+| `ui` | Designer | UI use cases: flows, component states, accessibility |
+| `docs` | Technical Writer | every documented command and claim executed as written |
+| `unit` | Developer | unit tests for the code the Developer wrote |
+| `integration` | Tester | integration / system / end-to-end behaviour |
+| `acceptance` | Reviewer | acceptance tests over **every** role's output |
+| `security` | Security Auditor | auth, input handling, secrets, red-line behaviour |
+
+Ownership is enforced: `tests add --layer integration --owner developer-1` is
+refused, and `tests run` only accepts instances of the owning role.
+
+Several **Reviewers** may run at once (`reviewer-1`, `reviewer-2`, ...). One may
+pass the verdict and that same lane merges it - an author never reviews or merges
+its own work, which is where independence lives.
+
+## Comprehensive and systematic
+
+Each layer is designed the same way, so coverage is comparable across roles:
+
+1. **Enumerate** the claims the role is accountable for (its own deliverables and
+   decisions) and the ways they can fail: normal path, boundaries, error paths,
+   concurrency, degraded inputs, and the regression case for each fixed defect.
+2. **Design before implementing**: write down the cases and the expected result,
+   then implement them. Tests are written from the frozen interface
+   (`Architecture.md`) and the role's own specification - not from the finished
+   code, so lanes stay independent.
+3. **Execute and evidence**: actually run them and record command + revision +
+   observed result. Reading a diff is not a test.
+4. **Keep them deterministic**: no network, no sleeps, no ordering assumptions;
+   quarantine flaky tests explicitly with an owner instead of ignoring them.
+5. **Keep them alive**: re-run after every change that touches the layer's subject;
+   a stale pass is not a pass.
+
+Coverage is measured against the role's own claims, not line coverage. A layer
+that cannot fail does not count as a test.
+
+## Records
+
+One record per **(layer, area)** pair - that is the anti-duplication rule: the
+same thing is not tested twice by accident.
+
+```sh
+# each role declares its own layer for an area it is accountable for
+teamwork.py tests add --layer unit --area auth --command "go test ./internal/auth"
+teamwork.py tests add --layer system --area auth --command "check-boundaries ./..."
+# the owning role runs it and records evidence
+teamwork.py tests run TS-0002 --by tester-1 --result pass \
+    --evidence "go test ./test/integration -run Auth @a1b2c3d -> ok 4 tests" \
+    --baseline "empty auth table" --artifact Reports/auth-run.log --replay "go test ./test/integration -run Auth"
+
+# a defect fix proves the failure first; the proof is stored on the defect task
+# (task added with --bug), not on a layer record
+teamwork.py tests repro T-0007 --by tester-1 \
+    --pre-rev a1b2c3d --pre-evidence "go test ./test/integration -run Auth @a1b2c3d -> FAIL, 2 tests" \
+    --post-rev d4e5f6a --post-evidence "go test ./test/integration -run Auth @d4e5f6a -> ok 4 tests"
+
+teamwork.py tests list [--layer unit]
+teamwork.py tests plan        # matrix, role coverage, gaps
+
+Exit codes: `0` every required layer passes, `1` gaps remain, `3` no area is
+declared yet (nothing to check).
+```
+
+`tests add` refuses a duplicate `(layer, area)` and warns when the same command
+would run in two layers.
+
+## Required coverage
+
+Default: **every staffed role's layer** must cover every area in use. Narrow it
+deliberately, per area, and record why:
+
+```sh
+teamwork.py tests require --area auth --layers unit,integration,system,ui,acceptance,security
+```
+
+Default required coverage per area is the proportionate core set (`unit`,
+`integration`, `acceptance`) restricted to staffed roles; widen or narrow it per
+area with `tests require --area <a> --layers ... --by <architect|ceo> --reason <why>`,
+which is recorded and audited. Every staffed role must still design and run at
+least one test of its own layer.
+
+`loop` will not report STOP while a required layer is missing, pending or failing,
+nor (with four or more staffed layers) while a staffed role has designed no tests
+at all. `audit` lists the same gaps, failing layers, duplicate commands and roles
+with no tests.
+
+## Local and CI are one certification
+
+The Tester owns both signals and must show they agree:
+
+1. **Local** - run the layers on the working revision; this is the fast signal.
+2. **CI** - confirm the Release Engineer's pushed SHA produced the same result,
+   job by job across the OS/Python matrix; this is the authoritative signal.
+   A green local run with a red CI run is a failure, and so is the reverse.
+3. **Divergence is a defect.** Route it to the owner and re-verify after the fix:
+   code -> Developer; test -> Tester; contract/interface -> Architect; workflow,
+   packaging, runner or flake -> Release Engineer; scope -> CEO. File the exact
+   command, expected vs actual, log excerpt, SHA, run id and a one-line repro.
+4. **Never report a suite as passing while the matching CI run is red** (or the
+   reverse), and never let a red run go unowned.
+
+A `tests run` evidence string therefore names both:
+
+```
+<local command> @<rev> -> <result>; CI <run-id> @<rev> -> <conclusion>
+```
+
+## How it fits the flow
+
+```text
+interfaces frozen
+      |
+      +-- every role designs and runs its own layer, in parallel:
+          goal · requirements · plan · tech · release · data · process · cost
+          system · ui · docs · unit · integration · acceptance · security
+      |
+      v
+  PR -> Reviewer acceptance tests + independent review -> merge (same lane)
+```
+
+Test layers are lanes like any other: they claim provider slots, run in parallel
+with implementation, and are never deferred to the end of a milestone.