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
7 changes: 7 additions & 0 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,13 @@ jobs:
python -m pip install -r dev-requirements.txt
python -m pip install -e . --no-deps

# Unit-test conventions of WORKFLOW-LOCAL.md: placement, docstrings,
# and legacy files that only shrink against the PR's exact base.
- name: Check test conventions
env:
DEVCAPSULE_DIFF_BASE: ${{ github.event.pull_request.base.sha || 'origin/main' }}
run: python scripts/validate_unittests_follow_conventions.py

- name: Run tests with coverage
run: >-
python -m pytest tests/
Expand Down
2 changes: 1 addition & 1 deletion CURRENT-STATUS.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ coordination branch. Detailed state belongs in each linked status file.
|---|---|---|---|---|---|
| `workflow-improvements` | 2026-08-09 | Improve the multiple-stream workflow from concrete dogfood findings during the recursive E2E cycle | active 2026-10-30; Pair Review Loop naming implemented and packaging verified for 0.3.0; mainline and release integration pending | `ws-workflow-improvements/v1` | [workstream status](engineering-docs/wip/2026-08-09-workflow-improvements/CURRENT-STATUS.md) |
| `project-management` | 2026-08-09 | Maintain project-wide priorities, sequencing, dependencies, and lifecycle coordination | paused 2026-10-11 at owner direction; consent and forced configuration before RC work; remaining diagnostics/image scope and release cut decisions retained | `ws-project-management/coordination` | [workstream status](engineering-docs/wip/2026-08-09-project-management/CURRENT-STATUS.md) |
| `maintenance` | 2026-09-18 | Own the defects no open workstream covers, on `main` and on maintained release lines, and drive maintenance releases | integrating final acceptance 2026-10-31; PR #332 awaits owner merge; RC9 accepted; final publication authorized after main integration | `ws-maintenance/0.3.0-acceptance` for final acceptance delivery; `release-0.3.0`, the workstream's selection from the cut to the final tag; `ws-maintenance/session-logs` and `ws-maintenance/log-rotation` are merged and closed; owner-directed slice `ws-maintenance/ci-gating-030` merged via #312 and closed; synchronization review `ws-maintenance/0.3.0-main-sync` merged via #318 and closed; owner-requested preparation `ws-maintenance/0.3.0-rc9-preparation` merged through #329 and #331 | [workstream status](engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md) |
| `maintenance` | 2026-09-18 | Own the defects no open workstream covers, on `main` and on maintained release lines, and drive maintenance releases | active 2026-11-03; unit-test conventions slice, PR #335, awaits the owner's merge; 0.3.1 queue preserved | `ws-maintenance/test-conventions`; `ws-maintenance/0.3.1-preparation` carried into it; `release-0.3.0` closed and retained | [workstream status](engineering-docs/wip/2026-09-18-maintenance/CURRENT-STATUS.md) |
| `component-upgrades` | 2026-09-21 | Deliver component distribution channels, developer-owned version sets and proven upgrade rollback; Codex first | paused 2026-10-02; consent design ruled (D-0011 to D-0013), 0.2.16 consent slice next; R-UPGRADE-002 follow-up retained | `ws-component-upgrades/v1` | [workstream status](engineering-docs/wip/2026-09-21-component-upgrades/CURRENT-STATUS.md) |
| `sample-projects` | 2026-08-14 | Provide realistic sample projects as submodules that demonstrate ordinary adopter development inside DevCapsule | integrating 2026-10-22; AI Learning published; PR #252 reviewed and ready for human merge | `ws-sample-projects/ai-learning` | [workstream status](engineering-docs/wip/2026-08-14-sample-projects/CURRENT-STATUS.md) |
| `contained-display` | 2026-08-19 | Own the capsule supervisor core (container entry process, supervised children, explicit session end, headless mode) and the capsule's own display environment, closing the host-session credential exposure — supervisor first, display as its first consumer | active; **the contained display shipped in v0.2.12 on 2026-09-14** (recipe-9 base, contained desktop by default, X11 passthrough behind `host-x11`); the X11 credential bug is resolved; remaining threads are records and follow-ups (reconnect, WSL2 opener, sample locks) | `ws-contained-display/display-transport` | [workstream status](engineering-docs/wip/2026-08-19-contained-display/CURRENT-STATUS.md) |
Expand Down
32 changes: 32 additions & 0 deletions WORKFLOW-LOCAL-humane.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,38 @@ remark exists because a capsule's `/tmp` is a 2 GB tmpfs that the gate's
scratch overflows, which cost a resumed session a failed gate before the cause
was found.

## Unit Tests

**Rule.** A unit test file is named after its module and mirrors the
package tree; a test is a precondition it establishes, one call to a public
operation, and a postcondition the unit promises; every test says in a
docstring what contract it tests; existing files are marked legacy and only
shrink, a touched test is fixed and moved; the gate checks what a machine
can check and the reviewer checks the rest.

**Intended effect.** A reader sees which unit a test tests from its path
and what it tests from its first line. A test fails only when the unit
breaks its contract, never because a release moved, a lock was regenerated,
or the capsule that runs it has already accepted a vendor's terms.

**Motivation.** On 2026-11-03 the gate failed eighteen tests in the owner's
own capsule. None was a bug. Thirteen read the owner's accepted trust
record through the launcher's mounted settings, because the isolation
fixture moved the home and the product's fallback did not know. Four
asserted the repository's own lock, byte for byte, down to the release
candidate that built the base. One scanned every file under `tests/` and
found a forbidden word inside a sample project's virtualenv. These tests
had been written by three different models under pair review, and the
reviewer had named one of them "the right test". A test that copies the
value it finds is a change detector, not a contract: both a bug and an
intentional change fail it, and the fix is always to update the string.
The triple forces the precondition into the open, which is exactly what
the thirteen had left to chance. The mirror makes the unit obvious before
the first line is read. The legacy marker turns 1525 existing tests into a
debt that is paid at the moment someone is already in the file, rather than
a rewrite nobody will order. The gate carries the mechanical part because a
rule an agent must read is a rule an agent can skim.

## Reasoning And Code Navigation

**Rule.** Start from the contract, state the uncertainty, navigate from the
Expand Down
39 changes: 39 additions & 0 deletions WORKFLOW-LOCAL.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,6 +155,43 @@ in [`INFORMATION-MODEL.md`](devcapsule-src/devcapsule/assets/project_workflow/de
end-to-end suites are not in it. The [developer brief](DEVELOPING.md) says
when they run.

## Unit Tests

Owner direction, 2026-11-03, after eighteen tests failed in the owner's
capsule for reasons that were not bugs.

1. A unit test file mirrors the module it tests:
`tests/unit/<path>/test_<name>.py` tests `<path>/<name>.py` or
`<path>/_<name>.py` under `devcapsule-src`. The unit under test is that
module. A test of a heavier suite lives outside the mirror and carries
that suite's marker at module level.
2. A test is a Hoare triple. It establishes its precondition in its own
fixtures or asserts it first; a precondition inherited from the
repository's checkout, the host or the capsule that runs the test is not
a precondition. It performs one action: a call to one public operation
of the unit, or the raise it expects. It verifies a postcondition the
unit promises, never a value copied from a run. Release identifiers,
version strings and digests are not assertions of the unit suite.
3. Every test function has a docstring stating, in plain English, the
contract or the part of it under test. One line is enough when the body
is already plain; the reviewer decides that, not the author.
4. A unit with no declared public surface is not testable under rule 2
until it declares one: `__all__`, or a module docstring that names the
public operations and leaves the rest private.
5. Existing test files carry `pytestmark = pytest.mark.legacy`. A legacy
file only loses test functions. A test function you change is brought
to rules 1 to 3 and moved to the mirror. A legacy test broken by a
legitimate change is fixed or replaced by a conforming one, never marked
expected to fail or deselected. No marker but `legacy` is added to a
legacy file.
6. The gate holds rules 1, 3 and 5: `scripts/validate_unittests_follow_conventions.py` runs in
the `tests` and `build` sessions and in `tests.yml`, comparing legacy
files with the pull request's base. Its summary line counts the legacy
files and tests; the count goes down and never up.
7. In a Pair Review Loop, the brief instructs the reviewer to verify rules
1 to 4 on every new or changed test, and to name for each what would
make it fail for a reason that is not a bug.

## Reasoning And Code Navigation

1. Start with the behavior's contract: ownership, inputs, preconditions,
Expand Down Expand Up @@ -376,6 +413,8 @@ of `WORKFLOW.md`, in this checkout.
the chat or the terminal of that session: at least when the partner
starts, at each commit or gate it makes, and when it ends. The
partner's own log is evidence, not a report.
9. Owner direction, 2026-11-03. The brief carries the reviewer's duty under
*Unit Tests*, rule 7, for every loop.

## Commit Authorship

Expand Down
8 changes: 8 additions & 0 deletions devcapsule-src/noxfile.py
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,11 @@ def run_tests(session: nox.Session) -> None:
session.run("python", "-m", "pytest", str(PROJECT_ROOT / "tests"))


def check_test_conventions(session: nox.Session) -> None:
"""Hold the suite to *Unit Tests* in WORKFLOW-LOCAL.md; legacy files are compared with the diff base."""
session.run("python", str(PROJECT_ROOT / "scripts" / "validate_unittests_follow_conventions.py"))


def run_packaging_tests(session: nox.Session) -> None:
session.run(
"python",
Expand Down Expand Up @@ -170,6 +175,7 @@ def run_typecheck(session: nox.Session) -> None:
str(PROJECT_ROOT / "noxfile.py"),
str(VERSION_SCRIPT),
str(PROJECT_ROOT / "scripts" / "release-manifest.py"),
str(PROJECT_ROOT / "scripts" / "validate_unittests_follow_conventions.py"),
str(PROJECT_ROOT / "scripts" / "release-protocol.py"),
str(PROJECT_ROOT / "scripts" / "prepare-promotion.py"),
)
Expand Down Expand Up @@ -357,6 +363,7 @@ def bump_version(session: nox.Session) -> None:
def tests(session: nox.Session) -> None:
install_locked(session)
check_python_syntax(session)
check_test_conventions(session)
run_tests(session)


Expand Down Expand Up @@ -534,6 +541,7 @@ def build(session: nox.Session) -> None:
check_python_syntax(session)
check_shell_syntax(session)
run_typecheck(session)
check_test_conventions(session)
run_tests(session)
run_smoke(session)
build_test_pex(session)
Expand Down
3 changes: 2 additions & 1 deletion devcapsule-src/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,7 @@ markers = [
"contributor_e2e: launches a clean contributor container from a host or recursive capsule",
"ide_smoke: launches a real IDE session per surface with the executable under test; opt-in through nox -s ide-smoke",
"flaky: executes for visibility but has a temporarily non-blocking result",
"legacy: predates the unit-test conventions of WORKFLOW-LOCAL.md; the file only loses tests, see scripts/validate_unittests_follow_conventions.py",
]

[tool.coverage.run]
Expand All @@ -106,7 +107,7 @@ skip_covered = true

[tool.mypy]
python_version = "3.12"
files = ["devcapsule", "tests", "noxfile.py", "scripts/bump-version.py", "scripts/release-manifest.py", "scripts/ci_gate.py", "scripts/diff_coverage_annotations.py"]
files = ["devcapsule", "tests", "noxfile.py", "scripts/bump-version.py", "scripts/release-manifest.py", "scripts/ci_gate.py", "scripts/diff_coverage_annotations.py", "scripts/validate_unittests_follow_conventions.py"]
# Sample projects are independent submodules with their own dependencies. They
# are checked by their own tooling, not by DevCapsule's gate.
exclude = "(^|/)tests/resources/sample_projects/"
Expand Down
Loading
Loading