plan(issue-286): merge plan/issue-286 into main

.agents/skills/nils-cli-verify-required-checks/scripts/nils-cli-verify-required-checks.sh

@@ -14,10 +14,10 @@ Runs the required pre-delivery checks from DEVELOPMENT.md:
   - bash scripts/ci/third-party-artifacts-audit.sh --strict
   - bash scripts/ci/completion-asset-audit.sh --strict
   - bash scripts/ci/completion-flag-parity-audit.sh --strict
+  - zsh -f tests/zsh/completion.test.zsh
   - cargo fmt --all -- --check
   - cargo clippy --all-targets --all-features -- -D warnings
   - cargo test --workspace
-  - zsh -f tests/zsh/completion.test.zsh
 
 Modes:
   (default)
@@ -33,8 +33,6 @@ Environment:
   NILS_CLI_TEST_RUNNER=nextest
     Run `cargo nextest run --profile ci --workspace` and `cargo test --workspace --doc`
     instead of `cargo test --workspace`.
-  NILS_CLI_COVERAGE_DIR=target/coverage
-    Coverage output directory to create before checks.
 
 Exit codes:
   0  all checks passed
@@ -122,9 +120,9 @@ fi
 
 run bash scripts/ci/test-stale-audit.sh --strict
 run bash scripts/ci/third-party-artifacts-audit.sh --strict
-coverage_dir="${NILS_CLI_COVERAGE_DIR:-target/coverage}"
-run mkdir -p "$coverage_dir"
 run bash scripts/ci/completion-asset-audit.sh --strict
+run bash scripts/ci/completion-flag-parity-audit.sh --strict
+run zsh -f tests/zsh/completion.test.zsh
 run cargo fmt --all -- --check
 run cargo clippy --all-targets --all-features -- -D warnings
 if [[ "$test_runner" == "nextest" ]]; then
@@ -133,7 +131,5 @@ if [[ "$test_runner" == "nextest" ]]; then
 else
   run cargo test --workspace
 fi
-run bash scripts/ci/completion-flag-parity-audit.sh --strict
-run zsh -f tests/zsh/completion.test.zsh
 
 echo "ok: all nils-cli checks passed"

.github/workflows/ci.yml

@@ -39,16 +39,10 @@ jobs:
         with:
           tool: cargo-nextest
 
-      - name: Third-party artifact audit
-        run: bash scripts/ci/third-party-artifacts-audit.sh --strict
-
-      - name: Completion asset audit
-        run: bash scripts/ci/completion-asset-audit.sh --strict
-
-      - name: Nils CLI checks (includes docs-placement-audit)
+      - name: Nils CLI checks (includes third-party-artifacts-audit, Completion asset audit, docs-hygiene-audit, test-stale-audit)
         env:
           NILS_CLI_TEST_RUNNER: nextest
-        run: xvfb-run -a ./.agents/skills/nils-cli-verify-required-checks/scripts/nils-cli-verify-required-checks.sh
+        run: bash scripts/ci/nils-cli-checks-entrypoint.sh --xvfb
 
       - name: Publish JUnit report
         if: always() && hashFiles('target/nextest/ci/junit.xml') != ''
@@ -104,16 +98,10 @@ jobs:
         with:
           tool: cargo-nextest
 
-      - name: Third-party artifact audit
-        run: /opt/homebrew/bin/bash scripts/ci/third-party-artifacts-audit.sh --strict
-
-      - name: Completion asset audit
-        run: /opt/homebrew/bin/bash scripts/ci/completion-asset-audit.sh --strict
-
-      - name: Nils CLI checks (includes docs-placement-audit)
+      - name: Nils CLI checks (includes third-party-artifacts-audit, Completion asset audit, docs-hygiene-audit, test-stale-audit)
         env:
           NILS_CLI_TEST_RUNNER: nextest
-        run: /opt/homebrew/bin/bash ./.agents/skills/nils-cli-verify-required-checks/scripts/nils-cli-verify-required-checks.sh
+        run: /opt/homebrew/bin/bash scripts/ci/nils-cli-checks-entrypoint.sh
 
       - name: Publish JUnit report
         if: always() && hashFiles('target/nextest/ci/junit.xml') != ''

BINARY_DEPENDENCIES.md

@@ -76,6 +76,8 @@ These are repository scripts (not third-party packages):
 - Supporting utilities:
   - `scripts/generate-third-party-artifacts.sh`
   - `scripts/workspace-bins.sh`
+  - `scripts/ci/docs-placement-audit.sh`
+  - `scripts/ci/docs-hygiene-audit.sh`
   - `scripts/ci/coverage-summary.sh`
   - `scripts/ci/coverage-badge.sh`
 

DEVELOPMENT.md

@@ -44,6 +44,8 @@
 ## Documentation placement
 
 - Canonical policy: `docs/specs/crate-docs-placement-policy.md`.
+- Workspace retention inventory: `docs/specs/workspace-doc-retention-matrix-v1.md`.
+- Completion obligations: `docs/specs/completion-coverage-matrix-v1.md`.
 - Stale-test lifecycle and reviewer checklist: `docs/runbooks/test-cleanup-governance.md`.
 - When Markdown files change, run: `bash scripts/ci/docs-placement-audit.sh --strict`.
 - Run generic Markdown lint checks: `bash scripts/ci/markdownlint-audit.sh --strict`.
@@ -75,7 +77,7 @@
 - Or run the single entrypoint for required checks:
   `./.agents/skills/nils-cli-verify-required-checks/scripts/nils-cli-verify-required-checks.sh`
   (includes docs/completion/stale-test/third-party-artifact audits
-  plus fmt/clippy/tests; it pre-creates `target/coverage`, but still run coverage commands above)
+  plus fmt/clippy/tests; coverage commands above are still required explicitly)
 - Docs-only fast path: if every changed file is documentation-only (`*.md`, `docs/**`, `crates/*/docs/**`, plus root docs like `README.md`,
   `DEVELOPMENT.md`), run:
   - `./.agents/skills/nils-cli-verify-required-checks/scripts/nils-cli-verify-required-checks.sh --docs-only`

README.md

@@ -52,7 +52,7 @@ Each crate is either a standalone CLI binary or a shared library used across the
 
 - [crates/agent-docs](crates/agent-docs): Deterministic policy-document resolver for Codex/agent workflows (`resolve`, `contexts`, `add`,
   `baseline`).
-- [crates/codex-cli](crates/codex-cli): Provider-specific CLI for OpenAI/Codex workflows (auth, diagnostics, execution wrappers, Starship),
+- [crates/codex-cli](crates/codex-cli): Provider-specific CLI for OpenAI/Codex workflows (auth, diagnostics, execution flows, Starship),
   with adapters over `nils-common::provider_runtime`.
 - [crates/gemini-cli](crates/gemini-cli): Provider-specific CLI lane for Gemini workflows, with adapters over
   `nils-common::provider_runtime`.
@@ -75,12 +75,21 @@ Contributors should treat `nils-common` as the shared helper boundary for cross-
 Detailed scope, API examples, migration conventions, and non-goals are documented in
 [crates/nils-common/README.md](crates/nils-common/README.md).
 
+Sprint-2 boundary freeze and extraction lane ownership are tracked in
+[docs/specs/workspace-shared-crate-boundary-v1.md](docs/specs/workspace-shared-crate-boundary-v1.md).
+
+Workspace doc retention scope and delete/keep decisions are tracked in
+[docs/specs/workspace-doc-retention-matrix-v1.md](docs/specs/workspace-doc-retention-matrix-v1.md).
+
 ## Shell wrappers and completions
 
 Canonical completion architecture and contributor validation live in
 [docs/runbooks/cli-completion-development-standard.md](docs/runbooks/cli-completion-development-standard.md). Use
 [DEVELOPMENT.md](DEVELOPMENT.md) for required delivery checks.
 
+Completion obligation coverage is tracked in
+[docs/specs/completion-coverage-matrix-v1.md](docs/specs/completion-coverage-matrix-v1.md).
+
 Assets:
 
 - [completions/zsh/](completions/zsh/): zsh completions (plus `aliases.zsh`)

crates/api-gql/tests/history.rs

@@ -17,8 +17,7 @@ fn run_api_gql(cwd: &Path, args: &[&str]) -> CmdOutput {
 }
 
 fn run_api_gql_with(cwd: &Path, args: &[&str], envs: &[(&str, &str)]) -> CmdOutput {
-    let mut options = CmdOptions::default().with_cwd(cwd);
-    for key in [
+    let mut options = CmdOptions::default().with_cwd(cwd).with_env_remove_many(&[
         "GQL_HISTORY_ENABLED",
         "GQL_HISTORY_FILE",
         "GQL_HISTORY_LOG_URL_ENABLED",
@@ -29,9 +28,7 @@ fn run_api_gql_with(cwd: &Path, args: &[&str], envs: &[(&str, &str)]) -> CmdOutp
         "ACCESS_TOKEN",
         "SERVICE_TOKEN",
         "GQL_SCHEMA_FILE",
-    ] {
-        options = options.with_env_remove(key);
-    }
+    ]);
     for (k, v) in envs {
         options = options.with_env(k, v);
     }

crates/api-grpc/tests/integration.rs

@@ -11,29 +11,28 @@ fn api_grpc_bin() -> PathBuf {
 }
 
 fn run_api_grpc(cwd: &Path, args: &[&str], envs: &[(&str, &str)]) -> CmdOutput {
-    let mut options = CmdOptions::default().with_cwd(cwd);
-    for key in [
-        "GRPCURL_BIN",
-        "GRPC_URL",
-        "GRPC_ENV_DEFAULT",
-        "GRPC_TOKEN_NAME",
-        "GRPC_HISTORY_ENABLED",
-        "GRPC_HISTORY_FILE",
-        "GRPC_HISTORY_LOG_URL_ENABLED",
-        "GRPC_JWT_VALIDATE_ENABLED",
-        "ACCESS_TOKEN",
-        "SERVICE_TOKEN",
-        "HTTP_PROXY",
-        "http_proxy",
-        "HTTPS_PROXY",
-        "https_proxy",
-        "ALL_PROXY",
-        "all_proxy",
-    ] {
-        options = options.with_env_remove(key);
-    }
-    options = options.with_env("NO_PROXY", "127.0.0.1,localhost");
-    options = options.with_env("no_proxy", "127.0.0.1,localhost");
+    let mut options = CmdOptions::default()
+        .with_cwd(cwd)
+        .with_env_remove_many(&[
+            "GRPCURL_BIN",
+            "GRPC_URL",
+            "GRPC_ENV_DEFAULT",
+            "GRPC_TOKEN_NAME",
+            "GRPC_HISTORY_ENABLED",
+            "GRPC_HISTORY_FILE",
+            "GRPC_HISTORY_LOG_URL_ENABLED",
+            "GRPC_JWT_VALIDATE_ENABLED",
+            "ACCESS_TOKEN",
+            "SERVICE_TOKEN",
+            "HTTP_PROXY",
+            "http_proxy",
+            "HTTPS_PROXY",
+            "https_proxy",
+            "ALL_PROXY",
+            "all_proxy",
+        ])
+        .with_env("NO_PROXY", "127.0.0.1,localhost")
+        .with_env("no_proxy", "127.0.0.1,localhost");
 
     for (k, v) in envs {
         options = options.with_env(k, v);

crates/api-rest/tests/history.rs

@@ -13,28 +13,27 @@ fn api_rest_bin() -> std::path::PathBuf {
 }
 
 fn run_api_rest(cwd: &Path, args: &[&str], envs: &[(&str, &str)]) -> CmdOutput {
-    let mut options = CmdOptions::default().with_cwd(cwd);
-    for key in [
-        "REST_URL",
-        "REST_TOKEN_NAME",
-        "REST_HISTORY_ENABLED",
-        "REST_HISTORY_FILE",
-        "REST_HISTORY_LOG_URL_ENABLED",
-        "REST_ENV_DEFAULT",
-        "REST_JWT_VALIDATE_ENABLED",
-        "ACCESS_TOKEN",
-        "SERVICE_TOKEN",
-        "HTTP_PROXY",
-        "http_proxy",
-        "HTTPS_PROXY",
-        "https_proxy",
-        "ALL_PROXY",
-        "all_proxy",
-    ] {
-        options = options.with_env_remove(key);
-    }
-    options = options.with_env("NO_PROXY", "127.0.0.1,localhost");
-    options = options.with_env("no_proxy", "127.0.0.1,localhost");
+    let mut options = CmdOptions::default()
+        .with_cwd(cwd)
+        .with_env_remove_many(&[
+            "REST_URL",
+            "REST_TOKEN_NAME",
+            "REST_HISTORY_ENABLED",
+            "REST_HISTORY_FILE",
+            "REST_HISTORY_LOG_URL_ENABLED",
+            "REST_ENV_DEFAULT",
+            "REST_JWT_VALIDATE_ENABLED",
+            "ACCESS_TOKEN",
+            "SERVICE_TOKEN",
+            "HTTP_PROXY",
+            "http_proxy",
+            "HTTPS_PROXY",
+            "https_proxy",
+            "ALL_PROXY",
+            "all_proxy",
+        ])
+        .with_env("NO_PROXY", "127.0.0.1,localhost")
+        .with_env("no_proxy", "127.0.0.1,localhost");
 
     for (k, v) in envs {
         options = options.with_env(k, v);

crates/api-test/tests/e2e.rs

@@ -19,15 +19,12 @@ fn run_api_test(cwd: &Path, args: &[&str]) -> CmdOutput {
 }
 
 fn run_api_test_with_env(cwd: &Path, args: &[&str], env: &[(&str, &str)]) -> CmdOutput {
-    let mut options = CmdOptions::default().with_cwd(cwd);
-    for key in [
+    let mut options = CmdOptions::default().with_cwd(cwd).with_env_remove_many(&[
         "ACCESS_TOKEN",
         "SERVICE_TOKEN",
         "REST_TOKEN_NAME",
         "GQL_JWT_NAME",
-    ] {
-        options = options.with_env_remove(key);
-    }
+    ]);
     for (k, v) in env {
         options = options.with_env(k, v);
     }