Contributing¶
Git and GitHub are the system of record. Read repository AGENTS.md, use or
create the applicable Issue, and make tracked changes only in its registered
Issue-linked worktree. Ordinary work reaches main through a pull request.
Verification¶
Quality CLI process lifetime¶
The direct quality CLI owns each check until its workload has stopped. On Linux it connects retained log output to the existing finite Quality descendant owner. This covers nested sessions without introducing a second descendant inventory or a persistent supervisor. Ctrl-C requests cleanup and propagates the original interruption only after the owner has reaped its children; it never reports a passing check. Normal command exit codes, log retention and timeout results remain unchanged. After normal root exit, the shared owner allows at most one second for owned descendants to finish naturally (for example, Python forkserver helpers responding to pipe EOF). Cancellation bypasses this wait. Exited children are reaped; descendants still running after that interval are forcibly cleaned up and make the command an error.
Only the invocation's exact children may be signalled. The Linux owner has five seconds for cleanup; the CLI waits at most seven seconds, then at most two seconds to reap a forcibly stopped owner. Missing support, an unreadable ownership inventory or absent clean acknowledgement is a containment error, with no success or complete-cleanup claim. Killing the owner itself or kernel failure remains outside the guarantee. No process-name sweep, retry, service, credential or repository-cleanup authority is granted. Non-Linux platforms retain their process-group/tree scope, now also on interruption, with five seconds per termination command or reap; Linux nested-session guarantees do not apply to them.
After an incomplete cleanup, preserve the error and reconcile exact owned processes before rerunning verification. Never broaden cleanup to unrelated processes. The change needs no persisted-state migration; rollback restores the prior CLI execution path and shared-owner completion behavior. Regression evidence uses a real CLI entry and SIGINT, independently checks nested PID absence and unrelated sentinel survival, and covers normal success, timeout and unavailable ownership. Retained logs remain operator-owned.
Classify the produced artifact with python3 scripts/verification_policy.py.
Run focused checks while iterating. Code, configuration, packaging,
installation-contract, security, CI, and test candidates run:
To run one named test module, use the focused profile with its repository-relative test path. For example:
python3 scripts/quality_gate.py run --profile focused --test tests/test_docs.py
The test directory is not an import package, so do not invoke a focused module
as python3 -m unittest tests.test_docs. The focused profile preserves the
canonical discovery-based test invocation.
Review-stable code, configuration, packaging, installation-contract, security, CI, and test candidates run:
python3 scripts/quality_gate.py run --profile required
Before pushing a Python code or test candidate, classify it with
--candidate-stage pre_push. This selects one local CI-equivalent preflight,
including the coverage report, when the coverage-owner runtime and pinned quick
validator are available:
python3 scripts/verification_policy.py \
--task-effect repository_change --artifact-class code --candidate-stage pre_push
python3 scripts/quality_gate.py run --profile ci --python python3.11
If the preflight cannot run or fails, do not push; resolve the bounded local handoff first. A passing local preflight is not hosted acceptance.
On ci-capacity-insufficient, retain the failing job's numeric capacity record.
Its optional cgroup_stat_bytes separates anonymous memory, filesystem cache
and tmpfs; shmem is already included in file. Missing detail is reported as
unavailable. Do not subtract cache from the 6 GiB admission requirement or use
a later idle sample as the failed job's memory composition.
The repository runner now budgets 9 GiB and requires that amount free before
registration, covering the observed cold-cache footprint while keeping the
6 GiB in-job gate. Existing services adopt it only through an authorized idle
rollout followed by fresh hosted validation.
Merge requires the exact-head hosted validate check. A failed, skipped,
stale, or unavailable result blocks acceptance until a new exact-head hosted
run succeeds; a local result never substitutes for that gate.
On Linux, Quality MCP also terminates and reaps children that start separate sessions. A timeout, cancellation, output overflow, or command that exits with live descendants remains an error. Temporary artifacts under its private root are removed; repository files are not swept. If containment is unavailable or incomplete, retain the error and reconcile the owned processes before rerunning. Other platforms retain their existing process-tree/group behavior. This is process lifecycle handling, not a security sandbox.
Unattended RC admission¶
Issue #988 introduces a repository-owned, read-only daily admission evaluator:
python3 scripts/rc_window.py --input observation.json. Its closed observation
contains the current activation and independent setting, dedicated runner
evidence, exact candidate/check identities and a complete bounded window-claim
inventory. It rejects stale observations, holds, used or uncertain publication
identities and a second candidate in the same Asia/Tokyo date. Inputs are
limited to 64 KiB; output never grants publication authority.
The source also provides a disposable KVM guest builder and one-job launcher. See the release runner procedure for image verification, credential-free smoke, pre-job admission and separately authorized registration. It does not install or enable a scheduled publisher. Provider-backed observation, atomic workflow coordination, the publication adapter and the ten-window credential-separated pilot remain #988 acceptance work. Use the existing manual release path until those gates and explicit activation pass. The canonical publication contract owns the authority, recovery and failure rules.
Evaluation artifacts¶
Before adding an evaluation file, follow evaluation artifact governance.
Extend the existing evaluation family, declare its lifecycle and actual consumer
in evaluations/lifecycle.json, and preserve unique historical evidence. Run
python3 scripts/evaluation_lifecycle.py; normal test discovery also enforces
the catalog without running a model or external API.
Documentation changes¶
Follow documentation governance. Update English canonical content and the official Japanese translation together, regenerate machine-derived pages, and run:
python3 scripts/docs.py generate
python3 scripts/docs.py check
The check includes a strict MkDocs build. Generated HTML under site/ is
disposable and ignored.