Draft: expand claude-lint path verification plan

docs/claude-lint-skill-plan.md

@@ -21,8 +21,9 @@ This is the process used to audit `pg-x` and identify skill/agent installation d
      - `.claude/...`
      - `./...`
      - `../...`
-     - `~/.skills/...`
-   - verify every referenced file exists in the consumer repo
+     - `packages/...`
+     - `~/.claude/...`
+   - verify every referenced file exists in the appropriate resolution scope
    - distinguish live path breakage from harmless examples or placeholders
 
 4. Trace dependency and delegation surfaces.
@@ -66,6 +67,7 @@ Create a `claude-lint` skill that reviews Claude/Codex prompt surfaces for:
 - broken or incomplete JSON fencing
 - bad agent/skill dependency wiring
 - malformed `sc-compose` examples
+- relative and absolute path resolution defects caught by supplemental verification scripts
 - obvious orchestration drift between prompts, templates, and installed agents
 
 ## Scope
@@ -74,6 +76,7 @@ The skill should handle:
 - repo-local `.claude` directories
 - package surfaces such as `packages/*/agents`, `packages/*/skills`, and `packages/*/assets`
 - installed-consumer audits where a package is mirrored into a repo-local `.claude` surface
+- supplemental scripts that mechanically verify path resolution for relative, repo-root, install-time, and home-scoped references
 
 The skill should not try to prove semantic correctness of every agent policy. Its first responsibility is mechanical integrity and contract consistency.
 
@@ -83,6 +86,7 @@ The skill should produce:
 - a critical review report with severity and file references
 - a package-vs-install drift summary when package sources are available
 - a list of broken path references
+- a script-produced path verification report showing which relative and absolute references resolved, failed, or were downgraded to warnings
 - a list of JSON contract mismatches
 - a list of missing registry entries or dependency declarations
 - optional remediation guidance grouped by ownership:
@@ -96,6 +100,9 @@ Proposed package layout:
 ```text
 packages/sc-claude-lint/
 ├── manifest.yaml
+├── scripts/
+│   ├── verify-path-references.py
+│   └── lint-path-resolution.py
 ├── skills/
 │   └── claude-lint/
 │       ├── SKILL.md
@@ -110,6 +117,17 @@ packages/sc-claude-lint/
     └── claude-install-diff-reviewer.md
 ```
 
+Script responsibilities:
+
+- `verify-path-references.py`
+  - crawl prompt, skill, command, and asset surfaces for path-like references
+  - apply the path-resolution rules below
+  - emit machine-readable results for resolved, missing, ambiguous, and warning-only references
+
+- `lint-path-resolution.py`
+  - provide a narrower entry point for validating a specific file, package, or installed `.claude` mirror
+  - support regression fixtures so path bugs can be reproduced without running the full skill orchestration
+
 ## Authoring Plan
 
 1. Write the core skill entrypoint.
@@ -123,41 +141,81 @@ packages/sc-claude-lint/
 3. Write the path validation reference.
    - classify local vs package vs global references
    - document how to resolve relative paths from the owning file
-
-4. Write the JSON contract reference.
+   - document how packaged prompt surfaces resolve installed `.claude/...` paths back to source-package artifacts
+
+4. Design and implement the supplemental path verification scripts.
+   - define the accepted path classes:
+     - repo-root-relative install paths such as `.claude/...`
+     - owner-relative paths such as `./...` and `../...`
+     - package-source paths used only during development
+     - informational runtime home paths such as `~/.claude/...`
+   - make the scripts emit machine-readable findings that the skill can summarize
+   - add regression fixtures for broken relative paths, stale absolute paths, and package/install mismatches
+
+5. Write the JSON contract reference.
    - define what counts as a valid fenced JSON input contract
    - define expected output-envelope checks
    - define how to trace orchestrator -> template -> worker compatibility
 
-5. Write the package-install diff reference.
+6. Write the package-install diff reference.
    - explain how to compare `agents/`, `skills/`, and `assets/`
    - explain how to ignore package-root docs not intended for `.claude`
 
-6. Write the `sc-compose` verification reference.
+7. Write the `sc-compose` verification reference.
    - require real render verification for `.j2` prompt assets
    - define failure classes:
      - broken examples
      - stale CLI syntax
      - undeclared required vars
 
-7. Add a reviewer agent if needed.
+8. Add a reviewer agent if needed.
    - keep the agent prompt sparse
    - make the skill docs the policy source of truth
 
-8. Validate the skill on real repos.
+9. Validate the skill on real repos.
    - re-run against `pg-x`
    - run against at least one repo with a more mature `.claude` surface
+   - run the supplemental path scripts directly against both package source and installed mirrors
    - compare findings quality and noise level
 
 ## Success Criteria
 
 The skill is successful when it can reliably catch:
 - missing registry files
 - invalid or missing referenced docs
+- relative and absolute path resolution failures verified by scripts, not just prose review
 - package/install drift
 - stale agent names in orchestrators
 - malformed JSON contract examples
 - malformed `sc-compose` render examples
 - incomplete dependency wiring between skills and agents
 
 without producing large volumes of low-value prose findings.
+
+## Path Resolution Rules
+
+These rules should drive both the `claude-lint` skill guidance and the mechanical validator.
+
+1. Repo-local installed paths: `.claude/...`
+   - In a consumer repo, treat these as repo-root-relative.
+   - Example: `.claude/agents/req-qa.md` resolves from repo root.
+
+2. Owner-relative paths: `./...` and `../...`
+   - Resolve from the file that contains the reference.
+   - Example: `skills/codex-orchestration/SKILL.md` can refer to `./templates/dev-assignment.json.j2`.
+
+3. Packaged prompt surfaces that mention installed `.claude/...` paths
+   - When the source file lives under `packages/<package>/agents`, `commands`, `skills`, or `assets`, resolve install-time `.claude/...` references back to the package source tree first.
+   - Example:
+     - source prompt: `packages/sc-rust/agents/rust-developer.md`
+     - reference: `.claude/skills/rust-development/guidelines.txt`
+     - source target: `packages/sc-rust/skills/rust-development/guidelines.txt`
+   - If there is no packaged artifact match, fall back to repo-local runtime dependencies such as `.claude/agents/registry.yaml`.
+
+4. Source-tree-only references: `packages/...`
+   - Treat these as invalid inside installable prompt surfaces.
+   - Prompt artifacts should reference either installed `.claude/...` paths or owner-relative files.
+
+5. Runtime home paths: `~/.claude/...`
+   - Do not treat these as hard install-time file dependencies.
+   - Keep them as warnings or informational notes unless the specific lint mode is auditing runtime operations.