[codeforester]

Summary

• distinguish required workspace-update preflight blocks from actual git pull failures in text, JSON, exit status, and aggregate counts;
• exclude Git-registered linked worktrees nested beneath a manifest primary checkout from that checkout's untracked-file preflight, while preserving blocks for arbitrary untracked files and real primary-root edits;
• add regression coverage and update the command, workspace-manifest, schema, and AI command-context documentation.

Required preflight refusals now render as BLOCKED and count under blocked; optional refusals remain SKIP, and pull errors count under failed. The command remains nonzero when either blocked or failed is nonzero. JSON schema version 1 remains backward-compatible because blocked is additive.

Validation

• 31 passed, 10 subtests passed for cli/python/base_projects/tests/test_workspace_update.py
• pylint cli/python/base_projects/workspace_update.py cli/python/base_projects/tests/test_workspace_update.py
• 1835 passed Python tests via ./bin/base-test
• 1068 BATS tests passed via ./bin/base-test
• git diff --check

Documentation impact

Updated .ai-context/COMMANDS.md, docs/command-reference.md, docs/workspace-manifest.md, and docs/schemas/workspace-update.json to document the blocked/failed distinction and nested-worktree behavior.

Fixes #2633

[codeforester]

Hosted validation is complete. All functional/platform lanes passed: Python 3.10–3.13, BATS, macOS smoke, Ubuntu source-checkout, moving-provider source-checkout, integration, stable compatibility, all Pylint matrices, issue-branch policy, and release-train preflight. The only failure is the unrelated Security scanners lane: pip-audit reports the existing requirements-dev.txt pin pylint==3.3.9 as CVE-2026-114608, fixed in pylint 4.0.9. I have kept that dependency-security remediation out of this workspace-scoped PR; #2634 is not merge-ready until that baseline security finding is separately upgraded or explicitly waived.

[codeforester]

[docs drift, not inline-anchorable since the file isn't touched by this diff] cli/bash/commands/basectl/subcommands/workspace.sh's base_workspace_update_usage still says preflight failures are "skipped".

This PR updates .ai-context/COMMANDS.md, docs/command-reference.md, and docs/workspace-manifest.md to describe the new blocked/skipped split, but basectl workspace update --help (generated from base_workspace_update_usage in cli/bash/commands/basectl/subcommands/workspace.sh) still reads:

Dirty, non-default, non-tracking, and linked worktree roots are skipped with recovery guidance; no checkout is modified implicitly.

That's now inconsistent with the rest of the documentation set this PR updates — required-root preflight refusals are rendered as BLOCKED and counted under blocked, not skipped. Worth updating this help text in the same PR so --help doesn't contradict the docs.

[codeforester]

Addressed the review findings in commit 73a8c5ca:

• Parse complete git worktree list --porcelain blocks and ignore prunable or non-directory registrations, so stale linked-worktree paths cannot hide later dirty content.
• Use :(exclude,literal) pathspecs so * and ? in worktree directory names cannot broaden exclusions.
• Mark counts.blocked required in docs/schemas/workspace-update.json.
• Update workspace update --help and the Bash command README to distinguish required-root blocking from optional-root skipping; added help-surface assertions.

Regression coverage now includes a wildcard-named linked worktree, an unrelated matching sibling, and a recreated stale registration. Local validation: 31 workspace-update tests, schema contract test, Pylint on changed Python files, JSON syntax, and all 25 help BATS tests pass. Hosted checks have restarted for the new head.

[codeforester]

The remaining red gate was the security scanner, not a test regression. It reported pylint==3.3.9 / CVE-2026-114608 (fixed in 4.0.9).\n\nPushed c9f9d31f upgrading requirements-dev.txt to pylint==4.0.9. Local verification: full-repository Pylint passes, pip-audit reports no known vulnerabilities, workspace/schema tests pass (32 tests plus 10 subtests), and dependency/workflow contract tests pass (40 tests).