fix(sec-core): skip read-only raw user skills

[1570005763]

Why

#3146 added raw user skills to default discovery. Images with read-only raw skills then fail during init or scan --all when Ledger tries to create .skill-meta. Auto-remembering a writable sibling as parent/* can also make the read-only skill appear managed and disable the batch skip on the same or next run.

What changed

Extend the existing batch guard to host-backed, unmanaged, read-only skills directly under the raw user default root, resolved through the existing XDG helper. Return status=skipped, reasonCode=readonly_default_skill, and persisted=false before scanning or writing skill metadata. Auto-remember raw user skills by individual path so successful writable siblings do not expand managed coverage; other roots keep their existing registration rules.

Related issue

no-issue: focused follow-up regression fix for the raw user discovery added by #3146.

User / Agent impact

Read-only raw defaults no longer fail an otherwise successful batch, including mixed writable/read-only siblings and repeated runs in either discovery order. Writable skills scan normally; explicit scans and managed user skills retain write errors. Skips do not produce an attestation or activation state.

Risk and compatibility

• Public CLI, API, configuration, or documented behavior changed
• Privileged or security-sensitive behavior changed
• Cross-component contract changed
• Migration or rollback guidance is needed

The skip is limited to exact default-root children with non-writable Ledger state. Existing readonly_system_skill results, SkillFS/resolver errors, and real scan/write errors retain their behavior. No new CLI option, configuration field, dependency, manifest format, or activation/SkillFS behavior is introduced.

Existing managedSkillDirs patterns are preserved because configuration does not record whether a pattern was user-configured or auto-generated. A pre-existing raw-root glob therefore remains managed and strict. After confirming unintended coverage, users can replace that glob with individual paths they intend to manage; there is no automatic configuration migration.

Validation

Python 3.11.6 on macOS: 263 passed, 3 subtests passed. The nine new regression cases were first run against the previous implementation and failed as expected.

cd src/agent-sec-core
PYTHONPATH=agent-sec-cli/src:tests/unit-test python -m pytest -q \
  tests/unit-test/skill_ledger/{test_config,test_canonical_workflows,test_live_root}.py \
  tests/unit-test/security_middleware/backends/test_skill_ledger_backend.py \
  tests/integration-test/skill-ledger/test_skill_ledger_integration.py

• make python-code-pretty, git diff --check, and bash scripts/docs-lint.sh passed. Incremental Ruff found no new findings; two pre-existing test import-order findings remain unchanged.
• CLI regression tests cover init and scan --all, both sibling orders, read-only skill roots and existing metadata directories, two consecutive runs, exact-path registration, untouched skipped content, and strict explicit/exact-managed/glob-managed failures. Configuration tests also cover HOME fallback, custom XDG roots, later sibling additions, repeated registration, and preservation of existing patterns.
• Native Alibaba Cloud Linux 4.0.4, kernel 6.6.102, Python 3.11.6, UID/GID 65534: 27 CLI expectations passed. This includes 19 checks of the c8a2339ca023ba9e5280e263169d6a56fc3201d4 commit and 8 counterfactual checks reproducing the review issue on f2a994fd5.
• Real bind/remount read-only fixtures cover the HOME default skill subtree and a custom-XDG existing .skill-meta. Root and non-root write probes return EROFS. All 16 repeated mixed-directory runs on the fix exit 0 with stable skips; three strict scans retain EROFS failures.
• All 14 temporary mounts and the remote run directory were removed. Checked installation/configuration and host mount baselines remained unchanged. This validates source CLI behavior, not RPM delivery, SkillFS/FUSE, or Agent integration.

The subsequent ee494fe65 update only trims README detail. Production code and tests are identical to the Linux-tested revision; documentation lint and diff checks passed.

Documentation and rollback

README summaries cover the batch skip behavior. Individual-path auto-registration and existing-pattern details are documented in both user-guide languages and the existing Ledger design contract. Revert this commit to restore previous behavior. The change adds no stored-state format migration; rollback preserves already-recorded individual paths.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-09T03:10:41.028305Z	f2a994f	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[edonyzpc]

LGTM