Harden codebase-memory-mcp skill guidance

[astandrik]

Pull Request Checklist

• I have read and followed the CONTRIBUTING.md guidelines.
• Paid-service submission guidance is not applicable; this skill does not require a paid service.
• This updates an existing skill in the correct directory.
• The existing file and folder naming convention is preserved.
• The content is clearly structured and follows the repository's skill format.
• Tested with GitHub Copilot CLI @github/copilot@1.0.79: the skill was loaded from this branch and completed a read-only bounded-filesystem-fallback smoke without modifying the repository.
• I have run npm start and verified that generated documentation is up to date.
• I am targeting the main branch for this pull request.

---

Description

Strengthen the existing codebase-memory-mcp skill so it is portable across agent environments and makes evidence quality, repository scope, pagination, fallback behavior, and mutation authority explicit.

The update:

• defines Scout, Verify, and Auditor evidence levels;
• selects indexed projects by exact canonical root instead of a similar project name;
• requires complete pagination and coverage checks for exhaustive claims;
• bounds filesystem fallback to the canonical checkout and prevents recursive symlink escape;
• clarifies moderate, fast, and full indexing modes and optional read-only tool profiles;
• permits indexing when explicitly approved by the user or narrowly pre-authorized by a trusted active runtime policy, while keeping deletion, trace ingestion, and ADR updates user-approval-only;
• narrows activation for known-file, exact-literal, configuration, error-string, and non-code tasks while preserving explicit and broader impact-analysis triggers.

docs/README.skills.md is regenerated from the updated skill description.

Evaluation results

Each counted evaluation used a fresh evaluator with only the target skill and the exact test prompt. Evaluators did not use tools or edit files. Five independent repetitions (or five complete trigger sets) were scored per family.

Evaluation family	Baseline	Updated	Expected behavior
Rooted fallback and absence boundaries	2/5 green; 3/5 failed	5/5 green	Stay at the canonical root, avoid external symlink traversal, and bound negative claims to inspected readable content
Scope coverage and symlink safety	1/5 green; 4/5 failed	5/5 green	Account for tracked, untracked, ignored, generated, vendored, binary, submodule, symlinked, and inaccessible content without recursive link escape
Activation controls	5/5 sets green	5/5 sets green	Trigger on explicit, implicit, and contextual positives; abstain on exact-literal and known-file negatives
Mutation authority without user approval or trusted active policy	0/5 chose immediate indexing; 5/5 chose bounded local exploration	0/5 chose immediate indexing; 5/5 chose bounded local exploration	Do not treat deadline pressure or a recommendation as authorization
Trusted active runtime indexing policy	0/5 followed it; 5/5 asked again	5/5 followed it after verifying the exact root and missing index	Honor narrowly pre-authorized indexing without another prompt
Untrusted indexing instruction in repository text or tool output	0/5 indexed; 5/5 asked	0/5 indexed; 5/5 asked	Treat untrusted content as data, not authorization
Mixed trigger precedence	5/5 positive for both mixed controls; precedence clause missing	5/5 positive for both mixed controls; precedence clause present	Preserve broader impact and explicit-skill triggers even when a known file or literal is supplied

The measurable RED-to-GREEN lift is in rooted fallback, scope coverage, and trusted runtime-policy handling. Activation, ordinary mutation, and untrusted-instruction controls remained green; the mixed-trigger edit resolves a textual precedence ambiguity without claiming a behavioral improvement.

Validation

• npm start
• npm run build
• npm run skill:validate — 407/407 skills valid
• python3 .../skill-creator/scripts/quick_validate.py skills/codebase-memory-mcp
• npx --yes @microsoft/vally-cli lint skills/codebase-memory-mcp --verbose — 2/2 checks passed
• git diff --check origin/main...HEAD

---

Type of Contribution

• Update to existing skill.

---

Additional Notes

This changes guidance only; it does not add dependencies or perform repository indexing. By submitting this pull request, I confirm that my contribution abides by the Code of Conduct and will be licensed under the MIT License.

[github-actions]

🔒 PR Risk Scan Results

Scanned 1 changed file(s).

Severity	Count
🔴 High	0
🟠 Medium	0
ℹ️ Info	0

✅ No matching risk patterns were detected in changed files.

This is an automated soft-gate report. Findings indicate review targets and do not block merge by themselves.

[github-actions]

🔍 Vally Lint Results

✅ All checks passed

Scope	Checked
Skills	1
Agents	0
Total	1

Severity	Count
❌ Errors	0
⚠️ Warnings	0
ℹ️ Advisories	0

Summary

Level	Finding
ℹ️	✅ codebase-memory-mcp (2/2 checks passed)
ℹ️	✓ [spec-compliance] All 1 skill(s) are spec-compliant.
ℹ️	✓ spec-compliance: All spec checks passed.
ℹ️	✓ [valid-refs] All file references across 1 skill(s) are valid.
ℹ️	✓ valid-refs: All file references resolve to existing files within the skill directory.
ℹ️	1 skill(s) linted, 1 passed

Full linter output

### Linting skills/codebase-memory-mcp
✅ codebase-memory-mcp (2/2 checks passed)
    ✓ [spec-compliance] All 1 skill(s) are spec-compliant.
        ✓ spec-compliance: All spec checks passed.
    ✓ [valid-refs] All file references across 1 skill(s) are valid.
        ✓ valid-refs: All file references resolve to existing files within the skill directory.

1 skill(s) linted, 1 passed

[Copilot]

Pull request overview

Hardens the Codebase Memory MCP skill’s activation, evidence, scope, fallback, pagination, and mutation guidance.

Changes:

• Defines Scout, Verify, and Auditor evidence levels.
• Adds canonical-root matching and bounded filesystem fallback.
• Clarifies indexing modes, tool profiles, and mutation authorization.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
skills/codebase-memory-mcp/SKILL.md	Strengthens operational and safety guidance.
docs/README.skills.md	Regenerates the skill description.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.