From 1aab6cd7ef253f8be0f3cb1c88d2a35897590a4d Mon Sep 17 00:00:00 2001 From: JRS1986 <1651269+JRS1986@users.noreply.github.com> Date: Sat, 19 Sep 2026 19:01:42 +0200 Subject: [PATCH 1/2] Fix stale generated agent config; refresh model catalog Claude Code: 'defaultMode: ask' is not a permission mode and bare-path deny entries are not permission rules, so the credential deny list had no effect. Write defaultMode 'default', Read(...) deny rules, and 'attribution' in place of the deprecated includeCoAuthoredBy. Codex: replace the retired approval_mode with approval_policy/sandbox_mode, and move skills to .agents/skills//SKILL.md with Agent Skills frontmatter, since Codex does not discover flat .codex/skills files. Also: @jackchen_me/open-multi-agent -> @open-multi-agent/core (deprecated on npm), drop two Ollama tags that do not exist, refresh local and cloud model defaults, install Claude Code via the native installer, add Python 3.14 to CI, and document RouteLLM as a legacy backend. --- .../PULL_REQUEST_TEMPLATE/agentic-change.md | 2 +- .github/workflows/ci.yml | 2 +- CHANGELOG.md | 43 +++++++++++++++++ README.md | 12 +++-- docs/docs/wiki/Review-Backlog.md | 2 +- docs/docs/wiki/Tool-Adapters.md | 14 ++++-- docs/docs/wiki/Upgrading.md | 18 +++++++ pyproject.toml | 1 + src/coding_scaffold/adapters.py | 48 +++++++++++++++---- src/coding_scaffold/installers.py | 10 ++-- src/coding_scaffold/model_catalog.py | 29 ++++++----- src/coding_scaffold/pr_template.py | 2 +- .../templates/adapters/codex-config.toml | 4 +- .../templates/adapters/codex-skills-readme.md | 13 +++-- .../adapters/open-multi-agent-example.ts | 4 +- .../templates/adapters/open-multi-agent.md | 2 +- .../templates/writers/tools.md | 2 +- tests/conftest.py | 4 +- tests/fixtures/golden/adapter_paths.txt | 6 +-- tests/test_adapters.py | 24 +++++++--- tests/test_installers.py | 4 +- tests/test_router.py | 16 +++---- tests/test_writers.py | 6 +-- 23 files changed, 193 insertions(+), 75 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE/agentic-change.md b/.github/PULL_REQUEST_TEMPLATE/agentic-change.md index 3178cfe..5bed0a2 100644 --- a/.github/PULL_REQUEST_TEMPLATE/agentic-change.md +++ b/.github/PULL_REQUEST_TEMPLATE/agentic-change.md @@ -10,7 +10,7 @@ leaving it blank. ## Agentic coding disclosure - **Agent / tool used:** -- **Model / provider:** +- **Model / provider:** - **Human operator:** - **Task:** diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c594e76..de53239 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -10,7 +10,7 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - python-version: ["3.11", "3.12", "3.13"] + python-version: ["3.11", "3.12", "3.13", "3.14"] steps: - uses: actions/checkout@v5 - uses: astral-sh/setup-uv@v5 diff --git a/CHANGELOG.md b/CHANGELOG.md index daf2a92..3146813 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,49 @@ aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] +### Fixed + +- **Claude Code `settings.json` now uses valid permission syntax.** The generated + `"defaultMode": "ask"` was not a Claude Code permission mode, and the deny list + used bare paths (`"**/.env"`), which are not permission rules — so the credential + deny list had no effect. The adapter now writes `"defaultMode": "default"` and + `Read(...)` deny rules (`Read(**/.env)`, `Read(./.coding-scaffold/.env.local)`, …). + The deprecated `includeCoAuthoredBy: false` is replaced by + `"attribution": {"commit": "", "pr": ""}`. Run `coding-scaffold setup update`. +- **Codex `config.toml` now uses current keys.** `approval_mode = "suggest"` came + from the retired TypeScript Codex CLI and is not a valid top-level key today; the + adapter now writes `approval_policy = "on-request"` and + `sandbox_mode = "workspace-write"`. Codex only loads a project-level + `.codex/config.toml` after you trust the project. +- **Codex skills moved to `.agents/skills//SKILL.md`** with Agent Skills + frontmatter (`name`, `description`). Codex does not discover flat files under + `.codex/skills/`. See + [Upgrading](docs/docs/wiki/Upgrading.md#codex-skills-moved-in-080) for cleanup of + the old files. +- **`open-multi-agent` add-on installs `@open-multi-agent/core`.** The previous + `@jackchen_me/open-multi-agent` package is deprecated on npm; the install plan, + detection path, guide, and TypeScript example now use the new name. +- **Model catalog no longer recommends non-existent Ollama tags.** + `deepseek-coder-v2:16b-lite-instruct` and `qwen/qwen3-coder-40b` do not exist in + the Ollama registry. + +### Changed + +- **Local model catalog refreshed** to current Ollama tags: `qwen3.5:9b`, + `gpt-oss:20b` (routine) and `devstral-small-2:24b`, `qwen3-coder:30b`, + `qwen3.6:35b-a3b-coding`, `qwen3-coder-next` (heavy-lift). Machines with 8GB RAM + still get no local candidate. Existing `routing.json` files keep their old values + until you re-run `setup run`. +- **Cloud model defaults pinned to current ids** (models.dev naming): + `anthropic/claude-sonnet-5` / `anthropic/claude-haiku-4-5`, `openai/gpt-5.6` / + `openai/gpt-5.4-mini`, `google/gemini-3.1-pro-preview` / `google/gemini-flash-latest`. +- **Claude Code installs via the official native installer** + (`curl -fsSL https://claude.ai/install.sh | bash`) instead of npm, matching the + upstream recommendation. Nothing is installed without consent, as before. +- **Python 3.14 added** to the CI matrix and classifiers. +- **RouteLLM documented as a legacy backend** — upstream has had no commits since + August 2024. The backend still works; the README now says so. + ### Deprecated - **All 14 hidden flat command aliases** (`init`, `wizard`, `update`, `setup-tool`, diff --git a/README.md b/README.md index c1fe67b..a9791ee 100644 --- a/README.md +++ b/README.md @@ -184,8 +184,8 @@ cd ~/dev/my-project ``` Setup can run before any model is configured. It validates the selected coding tool and, when -stdin is interactive, asks before installing a missing tool. OpenCode and Hermes use their official -install scripts; Claude Code, Codex, OpenClaude, and Pi use npm packages. It can also configure +stdin is interactive, asks before installing a missing tool. OpenCode, Hermes, and Claude Code use +their official install scripts; Codex, OpenClaude, and Pi use npm packages. It can also configure the knowledge backend and optional shared Git remote during setup. Nothing is installed silently. If you already have `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, Azure variables, `GITHUB_TOKEN`, or a @@ -637,7 +637,9 @@ combine it with reviewed credentials, CI checks, identity policy, and network co ## Advanced Options RouteLLM can provide one OpenAI-compatible endpoint that routes actual requests between a -weak/routine model and a strong/heavy-lift model: +weak/routine model and a strong/heavy-lift model. Note that upstream RouteLLM has had no commits +since August 2024; treat this backend as legacy and evaluate a maintained gateway (for example +LiteLLM's auto-router) before depending on it: ```bash coding-scaffold setup addon --target ~/dev/my-project --addon routellm @@ -701,7 +703,7 @@ Optional commands can also generate: - `opencode.json`, `.opencode/agents/`, and `.opencode/commands/`. - `CLAUDE.md`, `.claude/settings.json`, `.claude/commands/`, and `.claude/agents/`. -- `AGENTS.md`, `.codex/config.toml`, and `.codex/skills/`. +- `AGENTS.md`, `.codex/config.toml`, and `.agents/skills/`. - `.coding-scaffold/team/sources///`: third-party manifest content imported by `team sync` (cloned repos keep `.git` inside an `_repo/` subdirectory for fast-forward pulls). - `.coding-scaffold/ROUTELLM.md` and `routellm.config.yaml`. @@ -732,7 +734,7 @@ showing every command. The most common commands are: ## Design Goals - Cross-platform Linux and WSL behavior. -- Tested Python 3.11 through 3.13, with WSL detection guarded against missing or restricted +- Tested Python 3.11 through 3.14, with WSL detection guarded against missing or restricted `/proc/version`. - No secret collection; the scaffold only records whether credentials appear available. - Local-first routing with explicit cloud escalation. diff --git a/docs/docs/wiki/Review-Backlog.md b/docs/docs/wiki/Review-Backlog.md index 59dc85c..bc54210 100644 --- a/docs/docs/wiki/Review-Backlog.md +++ b/docs/docs/wiki/Review-Backlog.md @@ -18,7 +18,7 @@ linkable — see the cross-references for where the work landed. - **P1-03 Add A Native Claude Code Adapter** — `coding-scaffold tools adapt --tool claude-code` generates `CLAUDE.md`, `.claude/settings.json`, slash commands, and the reviewer subagent. - **P1-04 Add A Native Codex Adapter** — `coding-scaffold tools adapt --tool codex` generates - `AGENTS.md`, `.codex/config.toml`, and `.codex/skills/`. + `AGENTS.md`, `.codex/config.toml`, and `.agents/skills/` (moved from `.codex/skills/` in 0.8.0). - **P1-05 Add A Compatibility Matrix** — [Tool Adapters / Compatibility Matrix](Tool-Adapters.md#compatibility-matrix) with 11 capabilities × 6 tools and support-depth labels. - **P2-01 Make The Knowledge Lifecycle Explicit** — raw/wiki/decisions/sessions structure plus diff --git a/docs/docs/wiki/Tool-Adapters.md b/docs/docs/wiki/Tool-Adapters.md index 54ebfac..af0d8d5 100644 --- a/docs/docs/wiki/Tool-Adapters.md +++ b/docs/docs/wiki/Tool-Adapters.md @@ -80,8 +80,14 @@ Generated files include: - `AGENTS.md` - `.codex/config.toml` -- `.codex/skills/README.md` -- `.codex/skills/first-session.md` +- `.agents/skills/README.md` +- `.agents/skills/first-session/SKILL.md` +- `.agents/skills/knowledge-propose/SKILL.md` + +Skills use the [Agent Skills](https://agentskills.io) folder layout, which Codex discovers under +`.agents/skills/`. Codex only loads the project-level `.codex/config.toml` after you trust the +project; the generated file sets `approval_policy = "on-request"` and +`sandbox_mode = "workspace-write"`. CodingScaffold does not store OpenAI credentials or control Codex execution. Use Codex's native model and approval-mode controls. @@ -142,8 +148,8 @@ capability or CodingScaffold has no opinion about it. | Capability | OpenCode | Claude Code | Codex | OpenClaude | Hermes | Pi | | --- | --- | --- | --- | --- | --- | --- | -| Install support | ✓ official script | ✓ npm package | ✓ npm package | ✓ npm package | ✓ official script | ✓ npm package | -| Project instructions | ✓ `AGENTS.md` + scaffold guide | ✓ `CLAUDE.md` | ✓ `AGENTS.md` + `.codex/` | ✓ `OPENCLAUDE.md` | ✓ `HERMES.md` | ✓ `PI.md` + `AGENTS.md` | +| Install support | ✓ official script | ✓ official script | ✓ npm package | ✓ npm package | ✓ official script | ✓ npm package | +| Project instructions | ✓ `AGENTS.md` + scaffold guide | ✓ `CLAUDE.md` | ✓ `AGENTS.md` + `.codex/` + `.agents/skills/` | ✓ `OPENCLAUDE.md` | ✓ `HERMES.md` | ✓ `PI.md` + `AGENTS.md` | | Slash commands / skills | ✓ 4 generated | ✓ 2 generated | skills only | doc-only | doc-only | doc-only | | Agents / subagents | ✓ explorer / implementer / reviewer | ✓ reviewer | — | — | — | — | | Permissions / approval | ✓ via policy pack | ✓ via `.claude/settings.json` | tool's own approval mode | — | — | — | diff --git a/docs/docs/wiki/Upgrading.md b/docs/docs/wiki/Upgrading.md index 4a8bf11..2bafb54 100644 --- a/docs/docs/wiki/Upgrading.md +++ b/docs/docs/wiki/Upgrading.md @@ -145,6 +145,24 @@ to `policy.network.allowlist`", and your update produced rename. Merge by renaming the key in your edited file and dropping the sidecar. +## Codex skills moved in 0.8.0 + +Codex discovers skills as [Agent Skills](https://agentskills.io) folders under +`.agents/skills//SKILL.md`. Earlier scaffold versions wrote flat files to +`.codex/skills/`, which Codex does not load. After `coding-scaffold setup update` +(or `tools adapt --tool codex`), the new files exist and the old ones are left in +place because the scaffold never deletes your files. Remove them once you have +moved any local edits across: + +```bash +git rm -r .codex/skills +``` + +The same release rewrites `.codex/config.toml` (`approval_policy` / +`sandbox_mode` replace the retired `approval_mode`) and `.claude/settings.json` +(valid `defaultMode`, `Read(...)` deny rules, `attribution`). If you edited those +files, reconcile the staged `.new` versions as described above. + ## Flat aliases deprecated in 0.8.0 The hidden flat command aliases are deprecated in 0.8.0 and will be **removed in diff --git a/pyproject.toml b/pyproject.toml index ff60d58..c5610e3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -16,6 +16,7 @@ classifiers = [ "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", + "Programming Language :: Python :: 3.14", ] [project.optional-dependencies] diff --git a/src/coding_scaffold/adapters.py b/src/coding_scaffold/adapters.py index cf40e7a..eb81871 100644 --- a/src/coding_scaffold/adapters.py +++ b/src/coding_scaffold/adapters.py @@ -130,9 +130,32 @@ def _write_codex(root: Path, routing: dict[str, object]) -> AdapterResult: files: list[Path] = [] skipped: list[Path] = [] collect_text(files, skipped, root / "AGENTS.md", _codex_agents_md(routing)) - collect_text(files, skipped, root / ".codex" / "skills" / "README.md", _codex_skills_readme()) - collect_text(files, skipped, root / ".codex" / "skills" / "first-session.md", _codex_first_session_skill()) - collect_text(files, skipped, root / ".codex" / "skills" / "knowledge-propose.md", _knowledge_propose_command()) + # Codex discovers skills as Agent Skills folders under `.agents/skills/` + # (agentskills.io layout), not as flat files under `.codex/skills/`. + skills = root / ".agents" / "skills" + collect_text(files, skipped, skills / "README.md", _codex_skills_readme()) + collect_text( + files, + skipped, + skills / "first-session" / "SKILL.md", + _agent_skill( + "first-session", + "Use when starting work in this repository for the first time: inspect before " + "editing, find run/test commands, and propose one safe improvement.", + _codex_first_session_skill(), + ), + ) + collect_text( + files, + skipped, + skills / "knowledge-propose" / "SKILL.md", + _agent_skill( + "knowledge-propose", + "Use at the end of a substantial session to draft reviewable, reusable project " + "knowledge proposals. Never stores raw transcripts or secrets.", + _knowledge_propose_command(), + ), + ) collect_text(files, skipped, root / ".codex" / "config.toml", _codex_config_toml()) return AdapterResult(files, skipped) @@ -199,6 +222,11 @@ def _opencode_recheck_route() -> str: return read_template("adapters/opencode-recheck-route.md") +def _agent_skill(name: str, description: str, body: str) -> str: + """Wrap a template body in Agent Skills frontmatter (`name` must match the folder).""" + return f"---\nname: {name}\ndescription: {description}\n---\n\n{body}" + + def _knowledge_propose_command() -> str: return read_template("adapters/knowledge-propose.md") @@ -215,15 +243,15 @@ def _claude_md(routing: dict[str, object]) -> str: def _claude_settings() -> dict[str, object]: return { "permissions": { - "defaultMode": "ask", + "defaultMode": "default", "deny": [ - ".coding-scaffold/.env.local", - ".coding-scaffold/credentials.local.json", - "**/.env", - "**/.env.*", + "Read(./.coding-scaffold/.env.local)", + "Read(./.coding-scaffold/credentials.local.json)", + "Read(**/.env)", + "Read(**/.env.*)", ], }, - "includeCoAuthoredBy": False, + "attribution": {"commit": "", "pr": ""}, } @@ -332,7 +360,7 @@ def _open_multi_agent_team(routing: dict[str, object]) -> dict[str, object]: return { "backend": "open-multi-agent", "intent": "Turn validated local agentic workflows into repeatable TypeScript automation.", - "install": "npm install @jackchen_me/open-multi-agent", + "install": "npm install @open-multi-agent/core", "agents": [ { "name": "explorer", diff --git a/src/coding_scaffold/installers.py b/src/coding_scaffold/installers.py index 51b5fd7..dd5c23d 100644 --- a/src/coding_scaffold/installers.py +++ b/src/coding_scaffold/installers.py @@ -94,8 +94,8 @@ def _plan_for(tool: str) -> ToolInstallPlan: tool="claude-code", executable="claude", detected=shutil.which("claude") is not None, - install_command=["npm", "install", "-g", "@anthropic-ai/claude-code"], - install_description="Install Claude Code globally with npm.", + install_command=["bash", "-lc", "curl -fsSL https://claude.ai/install.sh | bash"], + install_description="Install Claude Code with the official native installer.", post_install="Claude Code installed. Start it in a project with: claude", ) if tool == "codex": @@ -177,9 +177,9 @@ def _addon_plan_for(addon: str, target: Path | None = None) -> ToolInstallPlan: if addon == "open-multi-agent": return ToolInstallPlan( tool="open-multi-agent", - executable="node package @jackchen_me/open-multi-agent", - detected=(root / "node_modules" / "@jackchen_me" / "open-multi-agent").exists(), - install_command=["npm", "install", "@jackchen_me/open-multi-agent"], + executable="node package @open-multi-agent/core", + detected=(root / "node_modules" / "@open-multi-agent" / "core").exists(), + install_command=["npm", "install", "@open-multi-agent/core"], install_description="Install Open Multi-Agent into the target Node.js project.", post_install="Open Multi-Agent installed. Generate workflow files with: coding-scaffold workflow --target .", cwd=root, diff --git a/src/coding_scaffold/model_catalog.py b/src/coding_scaffold/model_catalog.py index 17c54fb..3d5df9b 100644 --- a/src/coding_scaffold/model_catalog.py +++ b/src/coding_scaffold/model_catalog.py @@ -16,33 +16,38 @@ class ModelCandidate: notes: str +# Ollama tags, verified against registry.ollama.ai. Sizing leaves headroom for +# the KV cache on top of the download size. Review this list each release — +# local coding models turn over every few months. LOCAL_CODER_MODELS = [ - ModelCandidate("qwen2.5-coder:7b-instruct", "weak", 10, 6, "Fast baseline for small edits."), - ModelCandidate("qwen2.5-coder:14b-instruct", "weak", 18, 10, "Good local default."), - ModelCandidate("deepseek-coder-v2:16b-lite-instruct", "weak", 22, 12, "Useful MoE-style local option."), - ModelCandidate("codestral:22b", "strong", 32, 16, "Strong code completion/editing option."), - ModelCandidate("qwen2.5-coder:32b-instruct", "strong", 32, 24, "Strong local coding model."), - ModelCandidate("qwen/qwen3-coder-40b", "strong", 56, 32, "User-preferred 40B-class Qwen coder slot."), + ModelCandidate("qwen3.5:9b", "weak", 10, 8, "Fast default for small edits and explanation."), + ModelCandidate("gpt-oss:20b", "weak", 24, 16, "Strong routine model for 16GB-class GPUs."), + ModelCandidate("devstral-small-2:24b", "strong", 32, 20, "Agentic coding model; tight on 16GB cards."), + ModelCandidate("qwen3-coder:30b", "strong", 32, 24, "Strong local coding default (MoE, 3B active)."), + ModelCandidate("qwen3.6:35b-a3b-coding", "strong", 48, 32, "Coding-tuned MoE for 32GB+ GPUs."), + ModelCandidate("qwen3-coder-next", "strong", 80, 64, "Workstation-class coder; ~52GB download."), ] +# Pinned provider model ids (models.dev naming, as used by OpenCode). Hosted +# model lineups change quickly; treat these as reviewed defaults, not truth. CLOUD_STRONG_MODELS = { - "anthropic": "anthropic/claude-sonnet", - "openai": "openai/gpt-4.1", + "anthropic": "anthropic/claude-sonnet-5", + "openai": "openai/gpt-5.6", "azure-openai": "azure-openai/{deployment}", "azure-ai": "azure-ai/{deployment}", "openrouter": "openrouter/auto", "github-models": "github/models", - "gemini": "google/gemini-pro", + "gemini": "google/gemini-3.1-pro-preview", "groq": "groq/compound", } CLOUD_ROUTINE_MODELS = { - "anthropic": "anthropic/claude-haiku", - "openai": "openai/gpt-4.1-mini", + "anthropic": "anthropic/claude-haiku-4-5", + "openai": "openai/gpt-5.4-mini", "azure-openai": "azure-openai/{deployment}", "azure-ai": "azure-ai/{deployment}", "openrouter": "openrouter/auto", "github-models": "github/models", - "gemini": "google/gemini-flash", + "gemini": "google/gemini-flash-latest", "groq": "groq/compound", } diff --git a/src/coding_scaffold/pr_template.py b/src/coding_scaffold/pr_template.py index 76e0351..24e9433 100644 --- a/src/coding_scaffold/pr_template.py +++ b/src/coding_scaffold/pr_template.py @@ -51,7 +51,7 @@ def _agentic_pr_template() -> str: ## Agentic coding disclosure - **Agent / tool used:** -- **Model / provider:** +- **Model / provider:** - **Human operator:** - **Task:** diff --git a/src/coding_scaffold/templates/adapters/codex-config.toml b/src/coding_scaffold/templates/adapters/codex-config.toml index 5514841..c839ed5 100644 --- a/src/coding_scaffold/templates/adapters/codex-config.toml +++ b/src/coding_scaffold/templates/adapters/codex-config.toml @@ -1,4 +1,6 @@ # Project-local CodingScaffold guidance for Codex. +# Codex only loads this file after you trust the project. # Do not store secrets here. Use Codex, OpenAI, or provider auth flows for credentials. -approval_mode = "suggest" +approval_policy = "on-request" +sandbox_mode = "workspace-write" diff --git a/src/coding_scaffold/templates/adapters/codex-skills-readme.md b/src/coding_scaffold/templates/adapters/codex-skills-readme.md index 1234557..d555c6c 100644 --- a/src/coding_scaffold/templates/adapters/codex-skills-readme.md +++ b/src/coding_scaffold/templates/adapters/codex-skills-readme.md @@ -1,8 +1,11 @@ -# Codex Skills +# Agent Skills -Project-local skills capture repeatable workflows that Codex should follow. Keep them short, -reviewable, and tied to real project checks. +Project-local skills capture repeatable workflows that Codex should follow. Each skill is a folder +with a `SKILL.md` whose frontmatter `name` matches the folder name (Agent Skills layout, see +https://agentskills.io). Codex, OpenCode, and other compatible tools discover `.agents/skills/` +automatically. Keep skills short, reviewable, and tied to real project checks. -Suggested starter: +Starters: -- `first-session.md`: inspect before editing and propose one safe improvement. +- `first-session/SKILL.md`: inspect before editing and propose one safe improvement. +- `knowledge-propose/SKILL.md`: draft reviewable knowledge proposals at the end of a session. diff --git a/src/coding_scaffold/templates/adapters/open-multi-agent-example.ts b/src/coding_scaffold/templates/adapters/open-multi-agent-example.ts index 8bab11e..ab1ec26 100644 --- a/src/coding_scaffold/templates/adapters/open-multi-agent-example.ts +++ b/src/coding_scaffold/templates/adapters/open-multi-agent-example.ts @@ -1,5 +1,5 @@ -import { OpenMultiAgent } from '@jackchen_me/open-multi-agent' -import type { AgentConfig } from '@jackchen_me/open-multi-agent' +import { OpenMultiAgent } from '@open-multi-agent/core' +import type { AgentConfig } from '@open-multi-agent/core' const explorer: AgentConfig = { name: 'explorer', diff --git a/src/coding_scaffold/templates/adapters/open-multi-agent.md b/src/coding_scaffold/templates/adapters/open-multi-agent.md index 8583677..2e6ba77 100644 --- a/src/coding_scaffold/templates/adapters/open-multi-agent.md +++ b/src/coding_scaffold/templates/adapters/open-multi-agent.md @@ -21,7 +21,7 @@ security triage, migration planning, or other repeatable engineering processes. ## Install ```bash -npm install @jackchen_me/open-multi-agent +npm install @open-multi-agent/core ``` ## Generated Files diff --git a/src/coding_scaffold/templates/writers/tools.md b/src/coding_scaffold/templates/writers/tools.md index e840115..d743e8c 100644 --- a/src/coding_scaffold/templates/writers/tools.md +++ b/src/coding_scaffold/templates/writers/tools.md @@ -76,7 +76,7 @@ Generate Codex-native project files: coding-scaffold tools adapt --target . --tool codex ``` -This writes `AGENTS.md`, `.codex/config.toml`, and `.codex/skills/`. +This writes `AGENTS.md`, `.codex/config.toml`, and Agent Skills under `.agents/skills/`. ## OpenClaude diff --git a/tests/conftest.py b/tests/conftest.py index 56c75a0..0bba1be 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -105,8 +105,8 @@ def factory( def routing_plan_factory() -> Callable[..., RoutingPlan]: def factory( strategy: str = "local-first-router", - weak_model: str | None = "qwen2.5-coder:14b-instruct", - strong_model: str | None = "qwen2.5-coder:32b-instruct", + weak_model: str | None = "qwen3.5:9b", + strong_model: str | None = "qwen3-coder:30b", route_threshold: float = ROUTELLM_MF_DEFAULT_THRESHOLD, local_endpoint: str | None = "http://127.0.0.1:11434/v1", cloud_provider: str | None = None, diff --git a/tests/fixtures/golden/adapter_paths.txt b/tests/fixtures/golden/adapter_paths.txt index f237621..68562db 100644 --- a/tests/fixtures/golden/adapter_paths.txt +++ b/tests/fixtures/golden/adapter_paths.txt @@ -1,12 +1,12 @@ +.agents/skills/README.md +.agents/skills/first-session/SKILL.md +.agents/skills/knowledge-propose/SKILL.md .claude/agents/reviewer.md .claude/commands/agentic-change.md .claude/commands/first-session.md .claude/commands/knowledge-propose.md .claude/settings.json .codex/config.toml -.codex/skills/README.md -.codex/skills/first-session.md -.codex/skills/knowledge-propose.md .opencode/agents/explorer.md .opencode/agents/implementer.md .opencode/agents/reviewer.md diff --git a/tests/test_adapters.py b/tests/test_adapters.py index 09f1818..5df302e 100644 --- a/tests/test_adapters.py +++ b/tests/test_adapters.py @@ -1,4 +1,5 @@ import json +import tomllib from coding_scaffold.adapters import write_route_backend, write_tool_adapter, write_workflow_backend @@ -43,7 +44,13 @@ def test_write_claude_code_adapter_creates_native_files(tmp_path) -> None: assert "reviewer.md" in names assert "claude-heavy" in (tmp_path / ".claude" / "agents" / "reviewer.md").read_text() assert "Knowledge Nudge" in (tmp_path / "CLAUDE.md").read_text() - assert "defaultMode" in (tmp_path / ".claude" / "settings.json").read_text() + settings = json.loads((tmp_path / ".claude" / "settings.json").read_text()) + # "ask" is not a Claude Code permission mode, and bare paths are not permission rules. + assert settings["permissions"]["defaultMode"] == "default" + assert "Read(**/.env)" in settings["permissions"]["deny"] + assert all(rule.startswith("Read(") for rule in settings["permissions"]["deny"]) + assert settings["attribution"] == {"commit": "", "pr": ""} + assert "includeCoAuthoredBy" not in settings def test_write_codex_adapter_creates_native_files(tmp_path) -> None: @@ -53,9 +60,12 @@ def test_write_codex_adapter_creates_native_files(tmp_path) -> None: assert "AGENTS.md" in names assert "config.toml" in names assert "README.md" in names - assert "first-session.md" in names - assert "knowledge-propose.md" in names - assert "approval_mode" in (tmp_path / ".codex" / "config.toml").read_text() + config = tomllib.loads((tmp_path / ".codex" / "config.toml").read_text()) + assert config == {"approval_policy": "on-request", "sandbox_mode": "workspace-write"} + for skill in ("first-session", "knowledge-propose"): + text = (tmp_path / ".agents" / "skills" / skill / "SKILL.md").read_text() + assert text.startswith(f"---\nname: {skill}\ndescription: ") + assert not (tmp_path / ".codex" / "skills").exists() agents = (tmp_path / "AGENTS.md").read_text() assert "does not replace Codex" in agents assert "Knowledge Nudge" in agents @@ -101,12 +111,12 @@ def test_routellm_yaml_quotes_model_names_with_special_chars() -> None: output = _routellm_yaml( { "weak_model": "weird: 'value with # hash'", - "strong_model": "qwen2.5-coder:7b-instruct", + "strong_model": "qwen3.5:9b", } ) assert '"weird: \'value with # hash\'"' in output - assert '"qwen2.5-coder:7b-instruct"' in output + assert '"qwen3.5:9b"' in output try: import yaml # type: ignore[import-not-found] @@ -114,7 +124,7 @@ def test_routellm_yaml_quotes_model_names_with_special_chars() -> None: return parsed = yaml.safe_load(output) assert parsed["weak_model"] == "weird: 'value with # hash'" - assert parsed["strong_model"] == "qwen2.5-coder:7b-instruct" + assert parsed["strong_model"] == "qwen3.5:9b" def test_write_open_multi_agent_backend_creates_docs_config_and_example(tmp_path) -> None: diff --git a/tests/test_installers.py b/tests/test_installers.py index bfc1a01..d9ecfb7 100644 --- a/tests/test_installers.py +++ b/tests/test_installers.py @@ -38,7 +38,7 @@ def test_install_missing_tools_supports_claude_code(monkeypatch) -> None: assert results[0].tool == "claude-code" assert results[0].status == "missing" - assert "@anthropic-ai/claude-code" in results[0].message + assert "claude.ai/install.sh" in results[0].message def test_install_missing_tools_supports_codex(monkeypatch) -> None: @@ -107,7 +107,7 @@ class Completed: ) assert results[0].status == "installed" - assert calls == [(["npm", "install", "@jackchen_me/open-multi-agent"], tmp_path)] + assert calls == [(["npm", "install", "@open-multi-agent/core"], tmp_path)] def test_install_missing_addon_clones_caveman_compression(tmp_path, monkeypatch) -> None: diff --git a/tests/test_router.py b/tests/test_router.py index d8d593f..fec22f1 100644 --- a/tests/test_router.py +++ b/tests/test_router.py @@ -45,7 +45,7 @@ def test_cloud_can_backfill_strong_model(hardware_profile, provider_factory) -> assert plan.cloud_provider == "anthropic" assert plan.cloud_model_family == "anthropic" - assert plan.strong_model == "anthropic/claude-sonnet" + assert plan.strong_model == "anthropic/claude-sonnet-5" def test_strong_route_falls_back_to_routine_when_no_heavy_model_exists(hardware_profile) -> None: @@ -55,8 +55,8 @@ def test_strong_route_falls_back_to_routine_when_no_heavy_model_exists(hardware_ [], ) - assert plan.weak_model == "qwen2.5-coder:7b-instruct" - assert plan.strong_model == "qwen2.5-coder:7b-instruct" + assert plan.weak_model == "qwen3.5:9b" + assert plan.strong_model == "qwen3.5:9b" def test_azure_provider_keeps_endpoint_and_model_family_separate( @@ -83,14 +83,14 @@ def test_azure_provider_keeps_endpoint_and_model_family_separate( def test_local_model_thresholds_pick_expected_strong_models(hardware_profile) -> None: - qwen_32b_plan = build_routing_plan( + coder_30b_plan = build_routing_plan( IntakeAnswers(privacy="local-only"), hardware_profile( cpu_count=16, gpu_name="GPU", vram_gb=24, llmfit_available=False, local_runtimes=[] ), [], ) - qwen_40b_plan = build_routing_plan( + coder_35b_plan = build_routing_plan( IntakeAnswers(privacy="local-only"), hardware_profile( cpu_count=16, @@ -103,8 +103,8 @@ def test_local_model_thresholds_pick_expected_strong_models(hardware_profile) -> [], ) - assert qwen_32b_plan.strong_model == "qwen2.5-coder:32b-instruct" - assert qwen_40b_plan.strong_model == "qwen/qwen3-coder-40b" + assert coder_30b_plan.strong_model == "qwen3-coder:30b" + assert coder_35b_plan.strong_model == "qwen3.6:35b-a3b-coding" def test_missing_vram_does_not_exclude_ram_only_candidates(hardware_profile) -> None: @@ -114,7 +114,7 @@ def test_missing_vram_does_not_exclude_ram_only_candidates(hardware_profile) -> [], ) - assert plan.weak_model == "qwen2.5-coder:7b-instruct" + assert plan.weak_model == "qwen3.5:9b" def test_select_local_model_is_independent_of_catalog_order(monkeypatch, hardware_profile) -> None: diff --git a/tests/test_writers.py b/tests/test_writers.py index 91613cd..119801c 100644 --- a/tests/test_writers.py +++ b/tests/test_writers.py @@ -84,13 +84,13 @@ def test_routellm_yaml_quotes_model_names_with_special_chars(routing_plan_factor plan = routing_plan_factory( weak_model="weird: 'value with # hash'", - strong_model="qwen2.5-coder:7b-instruct", + strong_model="qwen3.5:9b", route_threshold=0.1, ) output = _routellm_yaml(plan) assert "\"weird: 'value with # hash'\"" in output - assert '"qwen2.5-coder:7b-instruct"' in output + assert '"qwen3.5:9b"' in output assert '"http://127.0.0.1:11434/v1"' in output try: @@ -99,5 +99,5 @@ def test_routellm_yaml_quotes_model_names_with_special_chars(routing_plan_factor return parsed = yaml.safe_load(output) assert parsed["weak_model"] == "weird: 'value with # hash'" - assert parsed["strong_model"] == "qwen2.5-coder:7b-instruct" + assert parsed["strong_model"] == "qwen3.5:9b" assert parsed["providers"]["local"]["base_url"] == "http://127.0.0.1:11434/v1" From 5215554360163f2a0302346aaf91d50763e45a23 Mon Sep 17 00:00:00 2001 From: JRS1986 <1651269+JRS1986@users.noreply.github.com> Date: Sat, 19 Sep 2026 19:55:26 +0200 Subject: [PATCH 2/2] Release v0.8.0 with MCP and skill fixes, compatibility checks and hooks --- .../sessions/2026-09-19-agentic-change.md | 107 ++++++ .gitignore | 4 + CHANGELOG.md | 25 ++ docs/docs/wiki/Security.md | 16 +- docs/docs/wiki/Skills-and-Agents.md | 34 +- docs/docs/wiki/Tool-Adapters.md | 69 ++++ docs/docs/wiki/Upgrading.md | 29 ++ pyproject.toml | 2 +- src/coding_scaffold/adapters.py | 5 +- src/coding_scaffold/cli.py | 70 +++- src/coding_scaffold/cli_help.py | 26 +- src/coding_scaffold/compatibility.py | 342 ++++++++++++++++++ src/coding_scaffold/doctor.py | 5 + src/coding_scaffold/eval_harness.py | 5 + src/coding_scaffold/hooks.py | 156 ++++++++ src/coding_scaffold/mcp.py | 13 +- src/coding_scaffold/skill_metadata.py | 87 +++++ src/coding_scaffold/skills.py | 168 +++++++-- .../templates/writers/scaffold.gitignore | 1 + tests/fixtures/compatibility/README.md | 17 + tests/fixtures/compatibility/claude-mcp.json | 6 + .../compatibility/native-contract.json | 13 + tests/fixtures/golden/adapter_paths.txt | 1 + tests/fixtures/golden/scaffold_paths.txt | 1 + tests/test_compatibility.py | 150 ++++++++ tests/test_hooks.py | 133 +++++++ tests/test_native_skills.py | 211 +++++++++++ uv.lock | 2 +- 28 files changed, 1645 insertions(+), 53 deletions(-) create mode 100644 .coding-scaffold/sessions/2026-09-19-agentic-change.md create mode 100644 src/coding_scaffold/compatibility.py create mode 100644 src/coding_scaffold/hooks.py create mode 100644 src/coding_scaffold/skill_metadata.py create mode 100644 tests/fixtures/compatibility/README.md create mode 100644 tests/fixtures/compatibility/claude-mcp.json create mode 100644 tests/fixtures/compatibility/native-contract.json create mode 100644 tests/test_compatibility.py create mode 100644 tests/test_hooks.py create mode 100644 tests/test_native_skills.py diff --git a/.coding-scaffold/sessions/2026-09-19-agentic-change.md b/.coding-scaffold/sessions/2026-09-19-agentic-change.md new file mode 100644 index 0000000..d2b427b --- /dev/null +++ b/.coding-scaffold/sessions/2026-09-19-agentic-change.md @@ -0,0 +1,107 @@ + + +# Session Trace — 2026-09-19 + +## Task + +Refresh MCP and skill governance; add offline compatibility checks and optional lifecycle hooks + +## Plan + + + +- Detect Claude project MCP configuration and fail readiness on unreadable configurations. +- Unify project skill discovery and version full-package approvals with explicit legacy migration. +- Add offline native configuration contracts, provenance and doctor freshness findings. +- Generate optional Codex/Claude lifecycle hooks; test preservation, privacy and loop prevention. +- Document adoption and verify the full suite and repository smoke checks. +- Prepare v0.8.0, validate the package and docs, and publish after CI passes. + +## Files Inspected + + + +- AGENTS.md, pyproject.toml, existing adapters, updater, doctor, MCP and skill implementations. +- Existing CLI help, golden outputs, upgrade tests and scaffold fixture factories. +- Official Agent Skills, Codex configuration/hooks, Claude settings/MCP/hooks and OpenCode documentation. + +## Files Changed + + + +- src/coding_scaffold/mcp.py and eval_harness.py: detect .mcp.json and reject malformed candidate configuration. +- src/coding_scaffold/skills.py and skill_metadata.py: native locations, required scalar frontmatter, complete-package checksums and migration handling. +- src/coding_scaffold/compatibility.py: offline field checks, source/review metadata and freshness warnings. +- src/coding_scaffold/hooks.py: optional native configuration merging and bounded local lifecycle handler. +- src/coding_scaffold/adapters.py, doctor.py, cli.py and cli_help.py: expose and integrate the new behavior. +- src/coding_scaffold/templates/writers/scaffold.gitignore: ignore local aggregate hook reports. +- tests/test_native_skills.py, test_compatibility.py, test_hooks.py and fixtures: regression, contract, migration and offline execution coverage. +- CHANGELOG.md and wiki Security, Skills and Agents, Tool Adapters, Upgrading: describe usage and limitations. +- .gitignore: include this review trace and exclude generated local graphify output. +- pyproject.toml, uv.lock and CHANGELOG.md: promote the accumulated changes to v0.8.0. + +## Commands Run + + + +- coding-scaffold session init --target . --task "Refresh MCP and skill governance; add offline compatibility checks and optional lifecycle hooks" +- UV_CACHE_DIR=/private/tmp/coding-scaffold-uv-cache uv run --offline ruff check +- UV_CACHE_DIR=/private/tmp/coding-scaffold-uv-cache uv run --offline pytest -q +- UV_CACHE_DIR=/private/tmp/coding-scaffold-uv-cache uv run --offline coding-scaffold context lint --target . +- UV_CACHE_DIR=/private/tmp/coding-scaffold-uv-cache uv run --offline coding-scaffold eval run --target . +- UV_CACHE_DIR=/private/tmp/coding-scaffold-uv-cache uv run --offline coding-scaffold tools compatibility --target . +- git diff --check +- Intermediate targeted runs caught expected golden-path additions, an unused test import and a fixture using manual mode; each was corrected. +- Release validation: `uv lock`, `uv sync --locked --extra dev`, `uv run --offline --locked ruff check`, `uv run --offline --locked pytest -q` and the context/eval/compatibility smoke commands above. +- `uv build --offline --out-dir /private/tmp/coding-scaffold-v0.8.0-dist` and `npm run build` from docs/. + +## Test Result + + + +- Passed: 734 tests (66 added); failed: 0; skipped: 0. Release validation completed in 2.98 seconds. +- Ruff and context lint passed; readiness passed 9/9 enabled checks. +- Compatibility: zero errors; one missing-provenance warning in this repository, which has not adopted a generated compatibility manifest. +- Wheel and source distribution built successfully. Documentation built successfully with a non-fatal local Rspack cache-write warning. +- Installed the built wheel into an isolated Python 3.14 environment; verified version 0.8.0, new module imports, native hook generation, native skill creation and compatibility checks. + +## Risks + + + +- Required frontmatter is checked with a documented scalar subset, not a general YAML parser. +- Checks cover reviewed native fields and dated documentation snapshots; installed tool versions and live model availability are not probed. +- Lifecycle hooks check scaffold metadata, not project test results or tool permissions. Native hook execution/trust was not exercised in a live agent session. +- Whole-package checksums are unsigned local drift markers; legacy approvals require review and reapproval. +- No new dependencies, runtime network/model calls or telemetry. Local hook reports contain counts and a timestamp, not transcripts. + +## Follow-up Recommendations + + + +- Review native hooks before enabling them in a target project; keep the CLI on the agent's PATH. +- Review upstream contracts and update fixtures and provenance together when the review window expires. +- Jev remains outside this implementation scope. + +## Reusable Knowledge Discovered + + + +- Claude project MCP definitions use root .mcp.json with mcpServers, not settings.json's legacy mcp mapping. +- Native Agent Skills do not require a scaffold manifest. Project-local aliases must be deduplicated without reading external skill roots. +- Approving only SKILL.md and manifest.json misses executable helper changes; hash complete package paths, contents and executable bits. +- Hooks need an explicit stop-loop guard and must not confuse metadata readiness with successful project tests. diff --git a/.gitignore b/.gitignore index 8a21f1a..0b060cf 100644 --- a/.gitignore +++ b/.gitignore @@ -8,6 +8,7 @@ !.coding-scaffold/sessions/ .coding-scaffold/sessions/* !.coding-scaffold/sessions/.gitkeep +!.coding-scaffold/sessions/2026-09-19-agentic-change.md .claude/settings.local.json .claude/worktrees/ @@ -19,6 +20,9 @@ __pycache__/ *.egg-info/ .DS_Store +# Generated local code graph, including machine-specific paths and caches. +/graphify-out/ + # rspress docs node_modules dist/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 3146813..5858f3e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,8 +7,33 @@ aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] +## [0.8.0] — 2026-09-19 + +### Added + +- Offline `tools compatibility` checks for reviewed native configuration fields, + hook structures, skill frontmatter and review freshness; `--strict` also fails + on warnings. Generated compatibility manifests include upstream source URLs, + dated review snapshots and model catalog provenance. `doctor` surfaces findings. +- Opt-in `tools hooks --tool codex|claude-code` generates native `SessionStart` + and `Stop` handlers, preserving existing settings and hooks. The handler runs + local metadata checks and writes aggregate results; it runs no project commands, + makes no network/model calls and stores no transcripts. Stop continuation is + limited to one attempt. Setup/update do not enable hooks automatically. +- Native skill locations for `skills new/approve/export --location` and linting + under `.agents/skills`, `.claude/skills` and `.opencode/skills`. Native manifests + and scaffold-specific headings are optional. + ### Fixed +- Claude project `.mcp.json` servers are now scanned; malformed MCP candidate + configuration fails readiness rather than silently passing an empty-server check. +- Skill approvals now cover the full package, including helper scripts, supporting + files, paths and executable bits. Legacy checksums emit a review/migration warning. + Package links and external directory aliases are rejected before approval/export. +- New skill packages include required descriptions. Generated Codex descriptions + are YAML-quoted. Offline native contract fixtures cover adapter/hook output. + - **Claude Code `settings.json` now uses valid permission syntax.** The generated `"defaultMode": "ask"` was not a Claude Code permission mode, and the deny list used bare paths (`"**/.env"`), which are not permission rules — so the credential diff --git a/docs/docs/wiki/Security.md b/docs/docs/wiki/Security.md index 64f5b58..5038659 100644 --- a/docs/docs/wiki/Security.md +++ b/docs/docs/wiki/Security.md @@ -161,6 +161,11 @@ coding-scaffold mcp diff # report changes since the last snapshot sudo, bash -c), broad filesystem access (root or home), unapproved servers (when the policy has a non-empty approved list), denied servers (as errors), and review-required capabilities. +The scanner includes Claude Code's project `.mcp.json` / `mcpServers` format, +alongside the existing OpenCode, Claude settings and Codex TOML locations. It does +not load user-global MCP configuration. Malformed candidate configuration is an +error and fails the readiness check instead of being treated as an empty server list. + `mcp snapshot` + `mcp diff` together let you commit a known-good state and detect drift in CI. `mcp diff` exits non-zero when anything changed since the snapshot, so it can gate merges that quietly added a server. @@ -175,7 +180,7 @@ manifest.json machine-readable metadata (owner, version, risk_level, capabiliti scripts/ optional helpers tests/ optional verification scripts README.md usage and examples -CHECKSUM sha256(SKILL.md || manifest.json) frozen at approval +CHECKSUM v2 digest of package paths, contents and executable bits ``` `coding-scaffold skills lint` checks every skill for: @@ -192,6 +197,15 @@ CHECKSUM sha256(SKILL.md || manifest.json) frozen at approval `skills export ` produces a sharable `tar.gz` for inter-team reuse. +Native project skills under `.agents/skills`, `.claude/skills` and `.opencode/skills` +are scanned too, with required Agent Skills frontmatter. Native manifests and the +scaffold's section conventions are optional. Use `--location agents`, `claude` or +`opencode` for creation, approval and export in those folders. Package links are +rejected so approval cannot silently omit linked executable content. Legacy +two-file checksums are still recognized and reported as needing review; they are +never silently upgraded. A checksum is not a signature and cannot defend against +someone changing both the package and the checksum. + ## What this scaffold does not promise - It does not sandbox agent execution. diff --git a/docs/docs/wiki/Skills-and-Agents.md b/docs/docs/wiki/Skills-and-Agents.md index 63520c5..6740eb2 100644 --- a/docs/docs/wiki/Skills-and-Agents.md +++ b/docs/docs/wiki/Skills-and-Agents.md @@ -19,6 +19,39 @@ This creates: ## What A Good Skill Contains +For a native Agent Skills package, use the plural `skills` commands: + +```bash +coding-scaffold skills new release-review --location agents --owner @platform +coding-scaffold skills lint --target . +coding-scaffold skills approve release-review --location agents +coding-scaffold skills export release-review --location agents --output release-review.tar.gz +``` + +Locations are `scaffold` (the existing default, `.coding-scaffold/skills`), `agents` +(`.agents/skills`), `claude` (`.claude/skills`) and `opencode` (`.opencode/skills`). +`skills lint` inspects all four project-local folders, without reading user-global +skills. Native findings include their relative folder path, so duplicate names +remain distinguishable. In-project directory aliases are scanned once. + +Generated packages include `name` and `description` frontmatter. The offline +validator accepts plain/quoted strings and indented folded/literal blocks for +these fields; it does not implement a general YAML parser. Names must match their +folder and use lowercase letters/digits separated by hyphens. Native packages do +not require the scaffold-specific manifest or section headings. If a native +package includes a manifest, it is validated. All skills are checked for broad +triggers and hidden instructions. + +New approvals cover the complete package, including file paths, contents, +executable bits and supporting instructions. Old approvals produce a migration +warning until reviewed and approved again. External directory links and links or +special files within a package are rejected; copy their contents into regular +project files before approval or export. A checksum is a local drift marker, not +a signature or execution permission. See [Upgrading](Upgrading.md#skill-approval-migration). + +The singular `skill` command above retains its legacy Markdown/slash-command +behavior; it does not create a native Agent Skills package. + A good skill is short and procedural: - when to use it @@ -53,4 +86,3 @@ Skills should be reviewed when they: - encode project-specific architecture rules The best skills are not clever prompts. They are reliable engineering habits. - diff --git a/docs/docs/wiki/Tool-Adapters.md b/docs/docs/wiki/Tool-Adapters.md index af0d8d5..fbc495a 100644 --- a/docs/docs/wiki/Tool-Adapters.md +++ b/docs/docs/wiki/Tool-Adapters.md @@ -152,6 +152,7 @@ capability or CodingScaffold has no opinion about it. | Project instructions | ✓ `AGENTS.md` + scaffold guide | ✓ `CLAUDE.md` | ✓ `AGENTS.md` + `.codex/` + `.agents/skills/` | ✓ `OPENCLAUDE.md` | ✓ `HERMES.md` | ✓ `PI.md` + `AGENTS.md` | | Slash commands / skills | ✓ 4 generated | ✓ 2 generated | skills only | doc-only | doc-only | doc-only | | Agents / subagents | ✓ explorer / implementer / reviewer | ✓ reviewer | — | — | — | — | +| Optional lifecycle hooks | — | ✓ `SessionStart` / `Stop` | ✓ `SessionStart` / `Stop` | — | — | — | | Permissions / approval | ✓ via policy pack | ✓ via `.claude/settings.json` | tool's own approval mode | — | — | — | | MCP servers | ✓ disable list in policy | settings + docs | — | tool's own | tool's own | — | | Local model endpoint | ✓ provider detection | tool's own | tool's own | tool's own | tool's own | tool's own | @@ -174,6 +175,74 @@ Known gaps: runtime model routing is only available where the tool exposes an Op backend swap (today: OpenCode via RouteLLM). For other tools the scaffold relies on the tool's own provider configuration plus `tools select-model` recommendations. +## Offline Compatibility Checks + +```bash +coding-scaffold tools compatibility --target . +coding-scaffold tools compatibility --target . --json +coding-scaffold tools compatibility --target . --strict +``` + +Checks cover reviewed fields in Codex TOML, Claude settings, OpenCode JSON, Claude +project `.mcp.json`, hook structures, and required Agent Skills frontmatter. Unknown +settings are retained. These are focused contract checks, not full upstream schema +validation, installed-version detection, or live model-availability checks. + +Adapter generation saves `.coding-scaffold/compatibility.json` with upstream source +URLs, documentation snapshot identifiers, review dates, and model catalog entries. +Unversioned documentation is labeled as a dated snapshot rather than a tested CLI +version. Guidance-only adapters explicitly record that they are not contract-tested. +Model entries record recommendation provenance, including floating aliases and +deployment placeholders; a recorded review does not guarantee account access. + +`doctor` surfaces malformed configurations, missing reviews and reviews older than +90 days. `tools compatibility` exits 1 on errors; `--strict` also fails on warnings. +No network requests or commands run. `setup update` refreshes the saved provenance +using its normal checksum / `.new` behavior, preserving local edits. Updating a +scaffold does not automatically replace existing routing choices. + +Maintainers should review upstream documentation before changing the review date. +Update the adapters and the independently maintained examples under +`tests/fixtures/compatibility/` together, then run the offline test suite. + +## Optional Lifecycle Hooks + +Hooks are enabled only by an explicit command, separately from setup/adapt/update: + +```bash +coding-scaffold tools hooks --target . --tool codex +coding-scaffold tools hooks --target . --tool claude-code +# Both tools can be selected in one invocation with repeated --tool flags. +``` + +The command merges its handlers into `.codex/hooks.json` or +`.claude/settings.json`. Existing settings and other hooks are preserved; repeated +runs do not duplicate the handlers. Malformed existing configuration is left +untouched. Keep `coding-scaffold` on the agent's PATH and review/trust the native +configuration before use (Codex: `/hooks`). Project hook support also depends on +the installed agent version and its managed policies. + +- `SessionStart` returns a short compatibility summary to the agent. +- `Stop` runs context lint, skill lint and compatibility checks, then saves counts + and a timestamp in `.coding-scaffold/hook-report.json`. +- Metadata errors request one continuation. If `stop_hook_active` is already set, + errors remain in the report and a message is returned without another block. + +The native handler has a 15-second timeout. `tools hook-run` consumes at most 1 MiB +of JSON from stdin and uses the nearest project/worktree root above its `cwd`. +The report contains no prompts, transcripts, tool commands, outputs or session IDs. +Hooks do not run the project's test suite, execute project scripts, approve tool +calls, contact a model, or enforce a security boundary. A clean hook report is not +evidence that project tests passed. Generated ignore rules exclude the report; +existing projects can add `.coding-scaffold/hook-report.json` to `.gitignore`. + +To disable, remove the handlers whose command is +`coding-scaffold tools hook-run` from the native config, leaving other handlers +intact. To inspect a report, read `.coding-scaffold/hook-report.json` locally. + +Upstream contracts: [Codex hooks](https://learn.chatgpt.com/docs/hooks), +[Claude hooks](https://code.claude.com/docs/en/hooks). + ## Optional Tooling Tool adapters are the coding surface. Add-ons support model sizing, routing, team automation, and diff --git a/docs/docs/wiki/Upgrading.md b/docs/docs/wiki/Upgrading.md index 2bafb54..60ead05 100644 --- a/docs/docs/wiki/Upgrading.md +++ b/docs/docs/wiki/Upgrading.md @@ -1,5 +1,34 @@ # Upgrading CodingScaffold +## Skill Approval Migration + +After upgrading, run `coding-scaffold skills lint --target .`. It now includes +project-native skill folders and validates required `name` / `description` +frontmatter. Add missing descriptions to older packages before using them as +native skills. Native packages do not need a scaffold-specific manifest. + +Existing 64-character checksums are recognized as legacy approvals of just +`SKILL.md` and `manifest.json`. Review all scripts and supporting files, then run: + +```bash +coding-scaffold skills approve my-skill --target . +# For a package under .agents/skills: +coding-scaffold skills approve my-skill --target . --location agents +``` + +The replacement `v2:` checksum covers the complete package except the root +`CHECKSUM` file itself. File additions, deletions, renames, content edits and +executable-bit changes produce drift warnings. Skills remain in their existing +locations; nothing is moved or re-approved automatically. + +Run `coding-scaffold setup update --target .` to add the compatibility provenance +manifest and refresh generated skill descriptions. Edited files retain the normal +`.new` review flow. Review the new `tools compatibility` report before enabling +optional [lifecycle hooks](Tool-Adapters.md#optional-lifecycle-hooks). Setup and +updates never enable hooks automatically. + +## Generated File Updates + `coding-scaffold setup update` refreshes the generated files in `.coding-scaffold/` (plus `AGENTS.md`, `CLAUDE.md`, etc.) without losing your edits. This page explains the contract end-to-end so the upgrade path is diff --git a/pyproject.toml b/pyproject.toml index c5610e3..ee46663 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "coding-scaffold" -version = "0.7.0" +version = "0.8.0" description = "Local-first coding agent scaffold with hardware probing, provider discovery, and routing config generation." readme = "README.md" requires-python = ">=3.11" diff --git a/src/coding_scaffold/adapters.py b/src/coding_scaffold/adapters.py index eb81871..b33eb8c 100644 --- a/src/coding_scaffold/adapters.py +++ b/src/coding_scaffold/adapters.py @@ -8,6 +8,7 @@ from .model_catalog import ROUTELLM_MF_DEFAULT_THRESHOLD from .template_resources import read_template, render_template from .routing_io import load_routing_payload +from .compatibility import COMPATIBILITY_RELATIVE, compatibility_manifest @dataclass(frozen=True) @@ -41,6 +42,8 @@ def write_tool_adapter(target: Path, tool: str | list[str]) -> AdapterResult: result = AdapterResult([], []) files.extend(result.files) skipped.extend(result.skipped) + if any(selected != "manual" for selected in tools): + collect_json(files, skipped, root / COMPATIBILITY_RELATIVE, compatibility_manifest()) return AdapterResult(files, skipped) @@ -224,7 +227,7 @@ def _opencode_recheck_route() -> str: def _agent_skill(name: str, description: str, body: str) -> str: """Wrap a template body in Agent Skills frontmatter (`name` must match the folder).""" - return f"---\nname: {name}\ndescription: {description}\n---\n\n{body}" + return f"---\nname: {name}\ndescription: {json.dumps(description)}\n---\n\n{body}" def _knowledge_propose_command() -> str: diff --git a/src/coding_scaffold/cli.py b/src/coding_scaffold/cli.py index 3174bb9..4494158 100644 --- a/src/coding_scaffold/cli.py +++ b/src/coding_scaffold/cli.py @@ -45,6 +45,9 @@ write_memory_config, ) from .doctor import format_doctor_text, run_doctor +from .compatibility import check_compatibility +from .hooks import run_hook, write_hooks +from .skills import SKILL_LOCATIONS from .personas import PERSONAS as _PERSONAS, DEFAULT_PERSONA from .pilot import format_pilot_text, run_pilot from .tour import format_tour @@ -436,16 +439,19 @@ def build_parser() -> argparse.ArgumentParser: skills_new.add_argument("name", help="Skill name (slugified into the directory name).") _add_target_arg(skills_new) skills_new.add_argument("--owner", default=None, help="Skill owner handle for manifest.json.") + skills_new.add_argument("--location", choices=list(SKILL_LOCATIONS), default="scaffold") _add_json_arg(skills_new) - skills_lint = skills_sub.add_parser("lint", help="Lint every skill under .coding-scaffold/skills/.") + skills_lint = skills_sub.add_parser("lint", help="Lint scaffold and project-native skill folders.") _add_target_arg(skills_lint) _add_json_arg(skills_lint) skills_approve = skills_sub.add_parser("approve", help="Record the current CHECKSUM for a skill.") skills_approve.add_argument("name", help="Skill directory name.") + skills_approve.add_argument("--location", choices=list(SKILL_LOCATIONS), default="scaffold") _add_target_arg(skills_approve) _add_json_arg(skills_approve) skills_export = skills_sub.add_parser("export", help="Bundle a skill into a tar.gz archive.") skills_export.add_argument("name", help="Skill directory name.") + skills_export.add_argument("--location", choices=list(SKILL_LOCATIONS), default="scaffold") _add_target_arg(skills_export) skills_export.add_argument("--output", type=Path, default=None, help="Output archive path (default: .tar.gz in --target).") @@ -604,6 +610,15 @@ def build_parser() -> argparse.ArgumentParser: _add_tools_workflow_args(tools_workflow) tools_orchestrate = tools_sub.add_parser("orchestrate", help="Create an agent orchestration plan.") _add_tools_orchestrate_args(tools_orchestrate) + compatibility = tools_sub.add_parser("compatibility", help="Check native configuration and review freshness offline.") + _add_target_arg(compatibility) + _add_json_arg(compatibility) + compatibility.add_argument("--strict", action="store_true", help="Also fail on warnings such as overdue reviews.") + hooks = tools_sub.add_parser("hooks", help="Opt in to local lifecycle checks for Codex or Claude Code.") + _add_target_arg(hooks) + _add_json_arg(hooks) + hooks.add_argument("--tool", action="append", required=True, choices=["codex", "claude-code"]) + tools_sub.add_parser("hook-run", help="Handle a native lifecycle event from JSON on stdin.") adapt = sub.add_parser("adapt", help=argparse.SUPPRESS) _add_tools_adapt_args(adapt) @@ -1087,6 +1102,9 @@ def _normalize_grouped_command(args: argparse.Namespace) -> None: "select-model": "select-model", "workflow": "workflow", "orchestrate": "orchestrate", + "compatibility": "compatibility", + "hooks": "hooks", + "hook-run": "hook-run", }[args.tools_action] @@ -1554,7 +1572,7 @@ def _cmd_mcp_diff(args: argparse.Namespace) -> int: def _cmd_skills_new(args: argparse.Namespace) -> int: - result = new_skill(args.target, args.name, owner=args.owner) + result = new_skill(args.target, args.name, owner=args.owner, location=args.location) if args.json: _print_json(result.to_dict()) else: @@ -1576,7 +1594,7 @@ def _cmd_skills_lint(args: argparse.Namespace) -> int: def _cmd_skills_approve(args: argparse.Namespace) -> int: - outcome = approve_skill(args.target, args.name) + outcome = approve_skill(args.target, args.name, location=args.location) if args.json: _print_json(outcome) else: @@ -1588,7 +1606,7 @@ def _cmd_skills_approve(args: argparse.Namespace) -> int: def _cmd_skills_export(args: argparse.Namespace) -> int: - outcome = export_skill(args.target, args.name, output=args.output) + outcome = export_skill(args.target, args.name, output=args.output, location=args.location) if args.json: _print_json(outcome) else: @@ -1860,6 +1878,45 @@ def _cmd_adapt(args: argparse.Namespace) -> int: return 0 +def _cmd_compatibility(args: argparse.Namespace) -> int: + report = check_compatibility(args.target) + if args.json: + _print_json(report.to_dict()) + else: + print(f"compatibility: {report.error_count} error(s), {len(report.findings) - report.error_count} warning(s).") + for item in report.findings: + print(f" [{item.severity}] {item.path}: {item.message}") + print("Offline checks cover reviewed config fields; they do not verify installed tool versions or model availability.") + return 1 if report.error_count or (args.strict and report.findings) else 0 + + +def _cmd_hooks(args: argparse.Namespace) -> int: + result = write_hooks(args.target, args.tools) + if args.json: + _print_json(result) + else: + for path in result["files"]: + print(f"Wrote hooks: {path}") + for path in result["skipped"]: + print(f"Hooks already configured: {path}") + for note in result["notes"]: + print(note) + return 0 + + +def _cmd_hook_run(args: argparse.Namespace) -> int: + # Bound input and never echo native payloads (they can contain prompts and secrets). + raw = sys.stdin.read(1_048_577) + try: + if len(raw.encode("utf-8")) > 1_048_576: + raise ValueError + payload = json.loads(raw) + except ValueError as exc: + raise CliError("Invalid or oversized hook JSON.", "Send a native event smaller than 1 MiB on stdin.") from exc + _print_json(run_hook(payload)) + return 0 + + def _cmd_route(args: argparse.Namespace) -> int: result = write_route_backend(args.target, args.backend) print(f"Wrote {len(result.files)} routing backend file(s).") @@ -2005,6 +2062,9 @@ def _cmd_init_or_wizard(args: argparse.Namespace) -> int: "policy": _cmd_policy, "update": _cmd_update, "adapt": _cmd_adapt, + "compatibility": _cmd_compatibility, + "hooks": _cmd_hooks, + "hook-run": _cmd_hook_run, "route": _cmd_route, "select-model": _cmd_select_model, "workflow": _cmd_workflow, @@ -2320,7 +2380,7 @@ def _print_mcp_diff(diff: McpDiff) -> None: def _print_skills_lint(report: SkillLintReport) -> None: if not report.skills_scanned: - print("skills lint: no skills found under `.coding-scaffold/skills/`.") + print("skills lint: no skills found in scaffold or project-native skill folders.") return print( f"skills lint: scanned {len(report.skills_scanned)} skill(s); " diff --git a/src/coding_scaffold/cli_help.py b/src/coding_scaffold/cli_help.py index b515a4c..e4bba56 100644 --- a/src/coding_scaffold/cli_help.py +++ b/src/coding_scaffold/cli_help.py @@ -43,6 +43,18 @@ def epilog(self) -> str: # Path tuples are command names walked through the subparser tree, e.g. # ("setup", "run") for `coding-scaffold setup run`. HELP_REGISTRY: dict[tuple[str, ...], CommandDoc] = { + ("tools", "compatibility"): CommandDoc( + description="Check reviewed native config fields, skill frontmatter and compatibility review dates without network or subprocess calls.", + examples=["coding-scaffold tools compatibility --target . --json", "coding-scaffold tools compatibility --target . --strict"], + ), + ("tools", "hooks"): CommandDoc( + description="Opt in to SessionStart and Stop hooks for local scaffold checks. Merges handlers without replacing existing settings. Review and trust hooks in the native agent.", + examples=["coding-scaffold tools hooks --target . --tool codex", "coding-scaffold tools hooks --target . --tool claude-code"], + ), + ("tools", "hook-run"): CommandDoc( + description="Native hook entry point. Reads bounded JSON from stdin, checks local metadata, and writes only aggregate check results. Does not run project tests or store transcripts.", + examples=['printf \'{"hook_event_name":"Stop","cwd":"/path/to/repo"}\' | coding-scaffold tools hook-run'], + ), # ----- top-level ------------------------------------------------------ ("probe",): CommandDoc( description=( @@ -410,34 +422,34 @@ def epilog(self) -> str: ), # ----- skills --------------------------------------------------------- ("skills",): CommandDoc( - description="Manage reviewable skill packs under .coding-scaffold/skills/.", + description="Manage reviewable skill packs and project-native Agent Skills.", examples=[ - "coding-scaffold skills new --name release-review", + "coding-scaffold skills new release-review", "coding-scaffold skills lint", ], ), ("skills", "new"): CommandDoc( description="Scaffold a new skill directory with SKILL.md and helpers.", examples=[ - "coding-scaffold skills new --name release-review", + "coding-scaffold skills new release-review --location agents", ], ), ("skills", "lint"): CommandDoc( - description="Lint every skill under .coding-scaffold/skills/.", + description="Lint project skills in .coding-scaffold/skills, .agents/skills, .claude/skills and .opencode/skills. Native manifests are optional.", examples=[ "coding-scaffold skills lint", ], ), ("skills", "approve"): CommandDoc( - description="Record the current CHECKSUM for a skill (signs it as reviewed).", + description="Record a versioned checksum of the entire skill package after review. This is a drift marker, not a cryptographic signature.", examples=[ - "coding-scaffold skills approve --name release-review", + "coding-scaffold skills approve release-review --location agents", ], ), ("skills", "export"): CommandDoc( description="Bundle a skill into a tar.gz archive for sharing.", examples=[ - "coding-scaffold skills export --name release-review --out release-review.tar.gz", + "coding-scaffold skills export release-review --location agents --output release-review.tar.gz", ], ), # ----- eval ----------------------------------------------------------- diff --git a/src/coding_scaffold/compatibility.py b/src/coding_scaffold/compatibility.py new file mode 100644 index 0000000..5042eff --- /dev/null +++ b/src/coding_scaffold/compatibility.py @@ -0,0 +1,342 @@ +"""Offline checks for reviewed native configuration contracts, not live tool probes.""" + +from __future__ import annotations + +import json +import tomllib +from dataclasses import asdict, dataclass, field +from datetime import date +from pathlib import Path + +from .file_ops import sha256_text +from .model_catalog import CLOUD_ROUTINE_MODELS, CLOUD_STRONG_MODELS, LOCAL_CODER_MODELS +from .skills import lint_skills + + +COMPATIBILITY_RELATIVE = Path(".coding-scaffold/compatibility.json") +REVIEWED_AT = "2026-09-19" +REVIEW_INTERVAL_DAYS = 90 +# Unversioned upstream docs are identified by their snapshot date, not an invented CLI version. +ADAPTER_SOURCES = { + "codex": ( + "https://learn.chatgpt.com/docs/config-file/config-reference", + "https://learn.chatgpt.com/docs/hooks", + ), + "claude-code": ( + "https://code.claude.com/docs/en/settings", + "https://code.claude.com/docs/en/mcp", + "https://code.claude.com/docs/en/hooks", + ), + "opencode": ("https://opencode.ai/config.json", "https://opencode.ai/docs/skills/"), + "hermes": ("https://github.com/NousResearch/hermes-agent",), + "pi": ("https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent",), + "openclaude": ("https://github.com/gitlawb/openclaude",), +} + + +def compatibility_manifest() -> dict[str, object]: + """Freeze provenance with generated files; refresh uses the normal .new workflow.""" + models = [ + { + "id": model.name, + "upstream_version": model.name, + "source_url": f"https://ollama.com/library/{model.name}", + "reviewed_at": REVIEWED_AT, + } + for model in LOCAL_CODER_MODELS + ] + models.extend( + { + "id": model, + "upstream_version": model, + "source_url": "https://models.dev/", + "reviewed_at": REVIEWED_AT, + } + for model in sorted(set(CLOUD_ROUTINE_MODELS.values()) | set(CLOUD_STRONG_MODELS.values())) + ) + return { + "schema_version": 1, + "review_interval_days": REVIEW_INTERVAL_DAYS, + "adapters": { + tool: { + "upstream_version": f"documentation snapshot {REVIEWED_AT}" + if tool + in { + "codex", + "claude-code", + "opencode", + } + else None, + "reviewed_at": REVIEWED_AT + if tool in {"codex", "claude-code", "opencode"} + else None, + "source_urls": list(sources), + "scope": "native-config" + if tool in {"codex", "claude-code", "opencode"} + else "guidance-only; not contract-tested", + } + for tool, sources in ADAPTER_SOURCES.items() + }, + "model_catalog": { + "reviewed_at": REVIEWED_AT, + "upstream_version": "bundled catalog snapshot", + "source_urls": ["https://models.dev/", "https://ollama.com/library"], + "digest": sha256_text(json.dumps(models, sort_keys=True)), + "models": models, + "scope": "Recommendation provenance; no live availability or account access check.", + }, + } + + +@dataclass(frozen=True) +class CompatibilityFinding: + severity: str + path: str + rule: str + message: str + + +@dataclass(frozen=True) +class CompatibilityReport: + findings: list[CompatibilityFinding] = field(default_factory=list) + scanned_files: list[str] = field(default_factory=list) + provenance: dict[str, object] = field(default_factory=dict) + + @property + def error_count(self) -> int: + return sum(f.severity == "error" for f in self.findings) + + def to_dict(self) -> dict[str, object]: + return { + **asdict(self), + "errors": self.error_count, + "warnings": sum(f.severity == "warning" for f in self.findings), + } + + +def check_compatibility(target: Path, *, today: date | None = None) -> CompatibilityReport: + root = target.expanduser().resolve() + findings: list[CompatibilityFinding] = [] + scanned: list[str] = [] + today = today or date.today() + + def issue(path: str, rule: str, message: str, severity: str = "error") -> None: + findings.append(CompatibilityFinding(severity, path, rule, message)) + + def read(relative: str) -> dict | None: + path = root / relative + if not path.exists(): + return None + scanned.append(relative) + try: + raw = path.read_text(encoding="utf-8-sig") + payload = tomllib.loads(raw) if path.suffix == ".toml" else json.loads(raw) + if not isinstance(payload, dict): + raise ValueError + return payload + except (OSError, UnicodeError, ValueError): + issue(relative, "invalid-config", "Configuration must be a readable JSON/TOML object.") + return None + + for relative in ( + ".codex/config.toml", + ".claude/settings.json", + ".claude/settings.local.json", + "opencode.json", + ".mcp.json", + ".codex/hooks.json", + ): + payload = read(relative) + if payload is None: + continue + if relative == ".codex/config.toml": + if "approval_mode" in payload: + issue( + relative, + "retired-key", + "Replace approval_mode with approval_policy; review sandbox_mode separately.", + ) + for key, choices in { + "approval_policy": ("untrusted", "on-failure", "on-request", "never"), + "sandbox_mode": ("read-only", "workspace-write", "danger-full-access"), + }.items(): + value = payload.get(key) + # Newer Codex also accepts a granular approval-policy table. + if ( + value is not None + and not (key == "approval_policy" and isinstance(value, dict)) + and value not in choices + ): + issue( + relative, + "invalid-value", + f"Review unsupported {key} against the upstream config reference.", + ) + if relative == "opencode.json": + if "share" in payload and payload["share"] not in ("manual", "auto", "disabled"): + issue(relative, "invalid-value", "share must be manual, auto or disabled.") + if "default_agent" in payload and not isinstance(payload["default_agent"], str): + issue(relative, "invalid-value", "default_agent must name an agent.") + if relative.startswith(".claude/"): + permissions = payload.get("permissions", {}) + if not isinstance(permissions, dict): + issue(relative, "invalid-permissions", "permissions must be an object.") + else: + mode = permissions.get("defaultMode") + if mode is not None and mode not in ( + "default", + "acceptEdits", + "plan", + "dontAsk", + "bypassPermissions", + "auto", + ): + issue( + relative, + "invalid-permissions", + "permissions.defaultMode is not a reviewed native mode.", + ) + for key in ("allow", "ask", "deny"): + rules = permissions.get(key, []) + if not isinstance(rules, list) or any( + not isinstance(rule, str) or not re_permission(rule) for rule in rules + ): + issue( + relative, + "invalid-permissions", + f"permissions.{key} needs tool rules such as Read(**/.env), not bare paths.", + ) + if "includeCoAuthoredBy" in payload: + issue( + relative, + "retired-key", + "Use attribution.commit and attribution.pr instead of includeCoAuthoredBy.", + "warning", + ) + for key in ( + ("mcpServers",) + if relative == ".mcp.json" + else ("mcp",) + if relative == "opencode.json" + else ("mcp_servers",) + if relative.endswith(".toml") + else () + ): + servers = payload.get(key, {}) + if not isinstance(servers, dict) or any( + not isinstance(item, dict) for item in servers.values() + ): + issue(relative, "invalid-mcp", f"{key} must map server names to objects.") + if "hooks" in payload: + findings.extend(validate_hooks(payload["hooks"], relative)) + + for finding in lint_skills(root).findings: + if finding.rule in {"invalid-frontmatter", "missing-skill-md", "unreadable"}: + issue(finding.skill or "skills", finding.rule, finding.message) + + saved = read(str(COMPATIBILITY_RELATIVE)) + if ( + saved is None + and not (root / COMPATIBILITY_RELATIVE).exists() + and (scanned or (root / ".coding-scaffold/routing.json").exists()) + ): + issue( + str(COMPATIBILITY_RELATIVE), + "missing-provenance", + "No saved compatibility review; using bundled contracts. Run setup update for generated projects.", + "warning", + ) + provenance = saved if saved is not None else compatibility_manifest() + if ( + provenance.get("schema_version") != 1 + or not isinstance(provenance.get("adapters"), dict) + or not isinstance(provenance.get("model_catalog"), dict) + ): + issue( + str(COMPATIBILITY_RELATIVE), + "invalid-provenance", + "Expected compatibility manifest schema_version 1, adapters and model_catalog objects.", + ) + else: + relevant = [] + for tool, marker in ( + ("codex", ".codex"), + ("claude-code", ".claude"), + ("opencode", "opencode.json"), + ("hermes", ".coding-scaffold/HERMES.md"), + ("pi", ".coding-scaffold/PI.md"), + ("openclaude", ".coding-scaffold/OPENCLAUDE.md"), + ): + if (root / marker).exists(): + relevant.append((tool, provenance["adapters"].get(tool))) + if (root / ".coding-scaffold/routing.json").exists(): + relevant.append(("model_catalog", provenance["model_catalog"])) + if ( + provenance["model_catalog"].get("digest") + != compatibility_manifest()["model_catalog"]["digest"] + ): + issue( + str(COMPATIBILITY_RELATIVE), + "catalog-changed", + "Bundled model catalog changed; review routing recommendations and refresh generated files.", + "warning", + ) + for name, record in relevant: + try: + reviewed = date.fromisoformat(record["reviewed_at"]) + age = (today - reviewed).days + except (TypeError, KeyError, ValueError): + issue( + str(COMPATIBILITY_RELATIVE), + "unreviewed", + f"{name}: no recorded compatibility review.", + "warning", + ) + continue + if age > REVIEW_INTERVAL_DAYS or age < 0: + issue( + str(COMPATIBILITY_RELATIVE), + "review-overdue", + f"{name}: review date {reviewed}; recheck upstream documentation and run setup update.", + "warning", + ) + return CompatibilityReport(findings, scanned, provenance) + + +def re_permission(rule: str) -> bool: + import re + + return bool(re.fullmatch(r"[A-Za-z][A-Za-z0-9_*.-]*(?:\([^\n]*\))?", rule)) + + +def validate_hooks(hooks: object, path: str) -> list[CompatibilityFinding]: + """Validate shared structural fields without rejecting future native hook types/events.""" + + def invalid() -> list[CompatibilityFinding]: + return [ + CompatibilityFinding( + "error", + path, + "invalid-hooks", + "hooks must map events to matcher groups containing typed hook handlers; command hooks need a non-empty command.", + ) + ] + + if not isinstance(hooks, dict): + return invalid() + for event, groups in hooks.items(): + if event in {"managed_dir", "windows_managed_dir"} and isinstance(groups, str): + continue + if not isinstance(groups, list): + return invalid() + for group in groups: + if not isinstance(group, dict) or not isinstance(group.get("hooks"), list): + return invalid() + for hook in group["hooks"]: + if not isinstance(hook, dict) or not isinstance(hook.get("type"), str): + return invalid() + if hook["type"] == "command" and ( + not isinstance(hook.get("command"), str) or not hook["command"].strip() + ): + return invalid() + return [] diff --git a/src/coding_scaffold/doctor.py b/src/coding_scaffold/doctor.py index e149abb..94d49c6 100644 --- a/src/coding_scaffold/doctor.py +++ b/src/coding_scaffold/doctor.py @@ -20,6 +20,7 @@ from .hardware import probe_hardware from .personas import DEFAULT_PERSONA, PERSONAS, get_persona from .pr_template import PR_TEMPLATE_RELATIVE +from .compatibility import check_compatibility @dataclass(frozen=True) @@ -84,6 +85,10 @@ def run_doctor( root = (target or Path.cwd()).expanduser().resolve() artifacts = _survey_artifacts(root) notes = _system_notes(use_cache=use_cache) + compatibility = check_compatibility(root) + notes.extend(f"Compatibility ({item.severity}): {item.message}" for item in compatibility.findings) + if compatibility.findings: + notes.append("Run `coding-scaffold tools compatibility --target .` for paths and review provenance.") if persona == DEFAULT_PERSONA: next_steps = _recommend_next_steps(artifacts) ignore = list(ADVANCED_FOR_NOW) diff --git a/src/coding_scaffold/eval_harness.py b/src/coding_scaffold/eval_harness.py index 4c127f2..c23f30f 100644 --- a/src/coding_scaffold/eval_harness.py +++ b/src/coding_scaffold/eval_harness.py @@ -430,6 +430,11 @@ def _check_mcp_policy(root: Path) -> EvalCheck: # that a candidate config file is present. `.claude/settings.local.json` exists in many # Claude Code installs without any MCP entries. report = scan_mcp(root) + if any(f.rule == "invalid-config" for f in report.findings): + return EvalCheck( + name="mcp_policy_exists_if_mcp_detected", category="governance", passed=False, + message="MCP configuration could not be inspected. Run `coding-scaffold mcp scan`.", + ) server_count = len(report.servers) policy_present = (root / MCP_POLICY_RELATIVE).exists() if server_count == 0: diff --git a/src/coding_scaffold/hooks.py b/src/coding_scaffold/hooks.py new file mode 100644 index 0000000..1ff3bb1 --- /dev/null +++ b/src/coding_scaffold/hooks.py @@ -0,0 +1,156 @@ +"""Opt-in native lifecycle hooks that run bounded, local scaffold checks only.""" + +from __future__ import annotations + +import json +from datetime import UTC, datetime +from pathlib import Path + +from .compatibility import check_compatibility, validate_hooks +from .context_lint import lint_context +from .errors import CliError +from .file_ops import write_json +from .skills import lint_skills + + +HOOK_COMMAND = "coding-scaffold tools hook-run" +HOOK_CONFIGS = {"codex": ".codex/hooks.json", "claude-code": ".claude/settings.json"} +HOOK_REPORT_RELATIVE = Path(".coding-scaffold/hook-report.json") + + +def write_hooks(target: Path, tools: list[str]) -> dict[str, object]: + """Explicit opt-in; merge only our hooks, preserving all existing settings/handlers.""" + root = target.expanduser().resolve() + pending: list[tuple[Path, dict]] = [] + skipped: list[str] = [] + # Validate every requested config before writing any of them. + for tool in dict.fromkeys(tools): + if tool not in HOOK_CONFIGS: + raise CliError( + f"Lifecycle hooks are not supported for {tool}.", "Choose codex or claude-code." + ) + path = root / HOOK_CONFIGS[tool] + if not path.resolve().is_relative_to(root): + raise CliError( + "Hook configuration leaves the project.", "Use a project-local config file." + ) + try: + payload = json.loads(path.read_text(encoding="utf-8-sig")) if path.exists() else {} + if not isinstance(payload, dict) or validate_hooks(payload.get("hooks", {}), str(path)): + raise ValueError + except (OSError, UnicodeError, ValueError) as exc: + raise CliError( + f"Cannot merge hooks into {HOOK_CONFIGS[tool]}.", + "Fix the existing JSON/hook structure and retry.", + ) from exc + hooks = payload.setdefault("hooks", {}) + changed = False + for event in ("SessionStart", "Stop"): + groups = hooks.setdefault(event, []) + # Do not replace user customizations of an existing scaffold handler. + if any( + handler.get("command") == HOOK_COMMAND + for group in groups + for handler in group["hooks"] + ): + continue + groups.append({"hooks": [{"type": "command", "command": HOOK_COMMAND, "timeout": 15}]}) + changed = True + if changed: + pending.append((path, payload)) + else: + skipped.append(str(path)) + for path, payload in pending: + write_json(path, payload) + return { + "files": [str(path) for path, _ in pending], + "skipped": skipped, + "notes": [ + "coding-scaffold must be on the agent's PATH; review and trust native hooks before use.", + "Hooks run local metadata checks, not your project's test suite. No chat transcripts are saved.", + "Stop writes .coding-scaffold/hook-report.json; add it to your ignore rules if desired.", + ], + } + + +def run_hook(payload: object) -> dict[str, object]: + """Consume only event/cwd/loop-guard fields; never execute or persist tool/chat input.""" + if ( + not isinstance(payload, dict) + or not isinstance(payload.get("hook_event_name"), str) + or payload["hook_event_name"] not in {"SessionStart", "Stop"} + ): + raise CliError( + "Unsupported lifecycle hook input.", "Send a SessionStart or Stop JSON object on stdin." + ) + cwd = payload.get("cwd") + if "stop_hook_active" in payload and not isinstance(payload["stop_hook_active"], bool): + raise CliError("Invalid stop_hook_active value.", "Use a JSON boolean for the loop guard.") + if not isinstance(cwd, str) or not Path(cwd).is_absolute() or not Path(cwd).is_dir(): + raise CliError( + "Hook input requires an existing absolute cwd.", + "Let the native agent supply the working directory.", + ) + current = Path(cwd).resolve() + root = next( + ( + path + for path in (current, *current.parents) + if (path / ".git").exists() or (path / ".coding-scaffold").is_dir() + ), + current, + ) + compatibility = check_compatibility(root) + event = payload["hook_event_name"] + if event == "SessionStart": + count = len(compatibility.findings) + return { + "hookSpecificOutput": { + "hookEventName": event, + "additionalContext": ( + f"CodingScaffold: {count} compatibility finding(s). " + "Use coding-scaffold tools compatibility --target . for details. " + "The Stop hook checks scaffold metadata only; use the project's documented verification commands." + ), + } + } + context = lint_context(root) + skills = lint_skills(root) + counts = { + "context_errors": context.error_count, + "skill_errors": skills.error_count, + "compatibility_errors": compatibility.error_count, + } + has_errors = any(counts.values()) + counts.update( + { + "context_warnings": context.warning_count, + "skill_warnings": skills.warning_count, + "compatibility_warnings": len(compatibility.findings) - compatibility.error_count, + } + ) + report_path = root / HOOK_REPORT_RELATIVE + if not report_path.resolve().is_relative_to(root): + raise CliError( + "Hook report path leaves the project.", "Keep .coding-scaffold local to this worktree." + ) + # Only aggregate local results. No session IDs, user text, commands or tool outputs. + write_json( + report_path, + { + "schema_version": 1, + "event": "Stop", + "checks": counts, + "checked_at": datetime.now(UTC).isoformat(), + "project_tests_run": False, + }, + ) + if has_errors: + reason = ( + "CodingScaffold found metadata errors. Run context lint, skills lint, and " + "tools compatibility for details; fix errors relevant to this change." + ) + if not payload.get("stop_hook_active"): + return {"decision": "block", "reason": reason} + return {"systemMessage": reason + " Automatic continuation is limited to one attempt."} + return {} diff --git a/src/coding_scaffold/mcp.py b/src/coding_scaffold/mcp.py index 1db2329..fca29dd 100644 --- a/src/coding_scaffold/mcp.py +++ b/src/coding_scaffold/mcp.py @@ -29,6 +29,7 @@ # Codex's `.codex/config.toml` puts servers under `[mcp_servers.]` (snake_case); older # Codex layouts and some templates use a plain `[mcp]` table. We accept both. MCP_CONFIG_SOURCES: tuple[tuple[str, str], ...] = ( + (".mcp.json", "mcpServers"), ("opencode.json", "mcp"), (".claude/settings.json", "mcp"), (".claude/settings.local.json", "mcp"), @@ -278,6 +279,9 @@ def scan_mcp(target: Path) -> McpReport: payload = _load_config(full) if payload is None: warnings.append(f"Could not parse {rel_path}.") + findings.append(McpFinding("error", "invalid-config", None, rel_path, + "Cannot inspect unreadable or malformed MCP configuration.", + "Fix the JSON/TOML object before scanning again.")) continue if not isinstance(payload, dict): continue @@ -286,9 +290,16 @@ def scan_mcp(target: Path) -> McpReport: if mcp_section is None and rel_path.endswith(".toml"): mcp_section = payload.get("mcp") if not isinstance(mcp_section, dict): + if mcp_section is not None: + findings.append(McpFinding("error", "invalid-config", None, rel_path, + f"{mcp_key} must map names to server objects.", + "Fix the MCP server mapping and scan again.")) continue for server_name, server_config in sorted(mcp_section.items()): if not isinstance(server_config, dict): + findings.append(McpFinding("error", "invalid-config", server_name, rel_path, + "MCP server configuration must be an object.", + "Fix this server entry and scan again.")) continue servers.append(_parse_server(server_name, server_config, source=rel_path)) @@ -628,6 +639,6 @@ def _load_config(path: Path) -> dict[str, object] | None: payload = tomllib.load(fh) else: payload = json.loads(path.read_text(encoding="utf-8-sig")) - except (OSError, json.JSONDecodeError, tomllib.TOMLDecodeError): + except (OSError, UnicodeError, json.JSONDecodeError, tomllib.TOMLDecodeError): return None return payload if isinstance(payload, dict) else None diff --git a/src/coding_scaffold/skill_metadata.py b/src/coding_scaffold/skill_metadata.py new file mode 100644 index 0000000..2a6b5e6 --- /dev/null +++ b/src/coding_scaffold/skill_metadata.py @@ -0,0 +1,87 @@ +"""Offline validation of Agent Skills' required scalar frontmatter fields. + +This is deliberately not a YAML loader. It reads plain/quoted strings and indented +folded/literal blocks, ignores unrelated metadata, and rejects ambiguous required +fields instead of executing tags or resolving aliases. +""" + +from __future__ import annotations + +import json +import re + + +def validate_skill_metadata(text: str, directory_name: str) -> list[str]: + lines = text.lstrip("\ufeff").splitlines() + if not lines or lines[0].strip() != "---": + return ["SKILL.md needs YAML frontmatter with name and description."] + end = next((i for i in range(1, len(lines)) if lines[i].strip() == "---"), None) + if end is None: + return ["SKILL.md frontmatter is missing its closing --- delimiter."] + values: dict[str, str] = {} + errors: list[str] = [] + for index in range(1, end): + match = re.match(r"^(name|description):\s*(.*)$", lines[index]) + if not match: + continue + key, raw = match.groups() + if not raw.startswith(('"', "'")): + raw = re.split(r"\s+#", raw, maxsplit=1)[0].strip() + if key in values: + errors.append(f"Duplicate frontmatter field: {key}.") + continuation = [] + for line in lines[index + 1 : end]: + if line and not line[0].isspace(): + break + continuation.append(line.strip()) + try: + if re.fullmatch(r"[>|][+-]?", raw): + value = " ".join(continuation).strip() + elif raw.startswith('"'): + value, consumed = json.JSONDecoder().raw_decode(raw) + trailing = raw[consumed:].strip() + if not isinstance(value, str) or (trailing and not trailing.startswith("#")): + raise ValueError + elif raw.startswith("'"): + quoted = re.fullmatch(r"'((?:[^']|'')*)'(?:\s+#.*)?", raw) + if not quoted: + raise ValueError + value = quoted.group(1).replace("''", "'") + else: + raw = re.split(r"\s+#", raw, maxsplit=1)[0].strip() + if ( + raw.startswith(("[", "{", "!", "&", "*")) + or raw + in { + "null", + "Null", + "NULL", + "~", + "true", + "false", + "True", + "False", + } + or re.fullmatch(r"[-+]?\d+(\.\d+)?", raw) + ): + raise ValueError + if re.search(r":\s", raw): + raise ValueError + value = " ".join([raw, *continuation]).strip() + values[key] = value + except (ValueError, TypeError): + errors.append( + f"{key} must be a plain, quoted, or block string; quote special YAML syntax." + ) + values[key] = "" + name = values.get("name", "") + if not name or len(name) > 64 or not re.fullmatch(r"[a-z0-9]+(?:-[a-z0-9]+)*", name): + errors.append( + "name must be 1–64 lowercase letters/digits with single hyphens between words." + ) + elif name != directory_name: + errors.append(f"name {name!r} must match directory {directory_name!r}.") + description = values.get("description", "") + if not description or len(description) > 1024: + errors.append("description must be a non-empty string of at most 1024 characters.") + return errors diff --git a/src/coding_scaffold/skills.py b/src/coding_scaffold/skills.py index 02e1e7e..7e8c7e0 100644 --- a/src/coding_scaffold/skills.py +++ b/src/coding_scaffold/skills.py @@ -7,7 +7,7 @@ scripts/ - optional helper scripts tests/ - optional verification scripts README.md - usage/examples - CHECKSUM - sha256(SKILL.md || manifest.json) frozen at approval time + CHECKSUM - versioned digest of the complete package frozen at approval time This module supports four operations: @@ -24,15 +24,22 @@ import json import re import tarfile -from dataclasses import dataclass, field +from dataclasses import dataclass, field, replace from datetime import UTC, datetime from pathlib import Path from .errors import CliError from .file_ops import sha256_bytes +from .skill_metadata import validate_skill_metadata SKILLS_RELATIVE = Path(".coding-scaffold") / "skills" +SKILL_LOCATIONS = { + "scaffold": SKILLS_RELATIVE, + "agents": Path(".agents/skills"), + "claude": Path(".claude/skills"), + "opencode": Path(".opencode/skills"), +} REQUIRED_MANIFEST_FIELDS: tuple[str, ...] = ( "name", @@ -155,12 +162,15 @@ def to_dict(self) -> dict[str, object]: # --------------------------------------------------------------------------- -def new_skill(target: Path, name: str, *, owner: str | None = None) -> SkillResult: +def new_skill( + target: Path, name: str, *, owner: str | None = None, location: str = "scaffold", +) -> SkillResult: """Scaffold a new skill at `.coding-scaffold/skills//`.""" root = target.expanduser().resolve() - safe = _safe_skill_name(name) - skill_dir = root / SKILLS_RELATIVE / safe + safe = _resolve_skill_name(root, name, location) + skill_dir = root / SKILL_LOCATIONS[location] / safe + _check_project_path(root, skill_dir) files: list[Path] = [] skipped: list[Path] = [] @@ -171,6 +181,7 @@ def new_skill(target: Path, name: str, *, owner: str | None = None) -> SkillResu tests_dir = skill_dir / "tests" skill_dir.mkdir(parents=True, exist_ok=True) + _package_entries(skill_dir) scripts_dir.mkdir(parents=True, exist_ok=True) tests_dir.mkdir(parents=True, exist_ok=True) @@ -195,6 +206,7 @@ def _write_if_absent(path: Path, content: str, files: list[Path], skipped: list[ def _skill_md_template(name: str) -> str: return f"""--- name: {name} +description: Use when explicitly asked to run the {name} workflow. status: draft --- @@ -266,20 +278,34 @@ def _readme_template(name: str) -> str: def lint_skills(target: Path) -> SkillLintReport: root = target.expanduser().resolve() - skills_dir = root / SKILLS_RELATIVE findings: list[SkillFinding] = [] skills_scanned: list[str] = [] warnings: list[str] = [] - if not skills_dir.exists(): - return SkillLintReport(findings=[], skills_scanned=[], warnings=[]) - for skill_dir in sorted(skills_dir.iterdir()): - if not skill_dir.is_dir(): + seen: set[Path] = set() + for location, relative in SKILL_LOCATIONS.items(): + skills_dir = root / relative + if not skills_dir.exists(): continue - if skill_dir.name.startswith("."): + try: + _check_project_path(root, skills_dir) + candidates = sorted(skills_dir.iterdir()) + except (OSError, CliError) as exc: + findings.append(_package_finding(str(relative), "unreadable", str(exc))) continue - skill = skill_dir.name - skills_scanned.append(skill) - findings.extend(_lint_one_skill(skill, skill_dir)) + for skill_dir in candidates: + if skill_dir.name.startswith(".") or not skill_dir.is_dir(): + continue + skill = skill_dir.name if location == "scaffold" else str(relative / skill_dir.name) + try: + _check_project_path(root, skill_dir) + if skill_dir.resolve() in seen: + continue + seen.add(skill_dir.resolve()) + skills_scanned.append(skill) + _package_entries(skill_dir) + findings.extend(_lint_one_skill(skill, skill_dir, native=location != "scaffold")) + except (OSError, UnicodeError, CliError) as exc: + findings.append(_package_finding(skill, "unreadable", str(exc))) findings.sort(key=lambda f: ( {"error": 0, "warning": 1, "info": 2}[f.severity], f.skill or "", @@ -290,7 +316,7 @@ def lint_skills(target: Path) -> SkillLintReport: return SkillLintReport(findings=findings, skills_scanned=skills_scanned, warnings=warnings) -def _lint_one_skill(skill: str, skill_dir: Path) -> list[SkillFinding]: +def _lint_one_skill(skill: str, skill_dir: Path, *, native: bool = False) -> list[SkillFinding]: findings: list[SkillFinding] = [] skill_md = skill_dir / "SKILL.md" manifest_path = skill_dir / "manifest.json" @@ -306,9 +332,9 @@ def _lint_one_skill(skill: str, skill_dir: Path) -> list[SkillFinding]: suggested_fix="Create SKILL.md with at minimum a 'When to use' and 'Verification' section.", )) else: - findings.extend(_lint_skill_md(skill, skill_md)) + findings.extend(_lint_skill_md(skill, skill_md, native=native)) - if not manifest_path.exists(): + if not manifest_path.exists() and not native: findings.append(SkillFinding( severity="error", rule="missing-manifest", @@ -320,14 +346,21 @@ def _lint_one_skill(skill: str, skill_dir: Path) -> list[SkillFinding]: "Create manifest.json with name, version, owner, risk_level, and description." ), )) - else: + elif manifest_path.exists(): findings.extend(_lint_manifest(skill, manifest_path)) # Approval / drift check. checksum_file = skill_dir / "CHECKSUM" - if checksum_file.exists() and skill_md.exists() and manifest_path.exists(): + if checksum_file.exists() and skill_md.exists(): recorded = checksum_file.read_text(encoding="utf-8-sig").strip() - current = _compute_checksum(skill_md, manifest_path) + current = _package_checksum(skill_dir) + if re.fullmatch(r"[0-9a-f]{64}", recorded): + findings.append(replace( + _package_finding(skill, "legacy-checksum", "Approval covers only SKILL.md and " + "manifest.json; review the complete package and approve again."), + severity="warning", + )) + current = _compute_checksum(skill_md, manifest_path) if manifest_path.exists() else "" if recorded != current: findings.append(SkillFinding( severity="warning", @@ -336,7 +369,7 @@ def _lint_one_skill(skill: str, skill_dir: Path) -> list[SkillFinding]: file=str(checksum_file.relative_to(skill_dir)), line=None, message=( - "SKILL.md or manifest.json changed since the recorded approval." + "Skill package changed since the recorded approval." ), suggested_fix=( "Review the diff and re-run `coding-scaffold skills approve " @@ -346,7 +379,7 @@ def _lint_one_skill(skill: str, skill_dir: Path) -> list[SkillFinding]: return findings -def _lint_skill_md(skill: str, path: Path) -> list[SkillFinding]: +def _lint_skill_md(skill: str, path: Path, *, native: bool = False) -> list[SkillFinding]: findings: list[SkillFinding] = [] try: text = path.read_text(encoding="utf-8-sig") @@ -360,6 +393,8 @@ def _lint_skill_md(skill: str, path: Path) -> list[SkillFinding]: message=f"Could not read SKILL.md: {exc}", suggested_fix="Make sure the file is UTF-8 and readable.", )] + for message in validate_skill_metadata(text, path.parent.name): + findings.append(_package_finding(skill, "invalid-frontmatter", message)) lower = text.lower() # Broad / always-on language. for lineno, raw_line in enumerate(text.splitlines(), start=1): @@ -396,7 +431,7 @@ def _lint_skill_md(skill: str, path: Path) -> list[SkillFinding]: break # Missing required sections. - required_headings = ("when to use", "verification") + required_headings = () if native else ("when to use", "verification") for heading in required_headings: if not re.search(rf"^##\s+{re.escape(heading)}\b", text, flags=re.IGNORECASE | re.MULTILINE): findings.append(SkillFinding( @@ -419,7 +454,7 @@ def _lint_skill_md(skill: str, path: Path) -> list[SkillFinding]: flags=re.IGNORECASE | re.DOTALL, ) declared_text = declared.group(1).lower() if declared else "" - for keyword, capability in SENSITIVE_CAPABILITY_KEYWORDS: + for keyword, capability in (() if native else SENSITIVE_CAPABILITY_KEYWORDS): if keyword in lower and capability not in declared_text: findings.append(SkillFinding( severity="warning", @@ -518,23 +553,24 @@ def _lint_manifest(skill: str, path: Path) -> list[SkillFinding]: # --------------------------------------------------------------------------- -def approve_skill(target: Path, name: str) -> dict[str, object]: - """Compute the checksum of SKILL.md + manifest.json and record it in `CHECKSUM`.""" +def approve_skill(target: Path, name: str, *, location: str = "scaffold") -> dict[str, object]: + """Record a versioned checksum covering every package file, path and executable bit.""" root = target.expanduser().resolve() - safe = _safe_skill_name(name) - skill_dir = root / SKILLS_RELATIVE / safe + safe = _resolve_skill_name(root, name, location) + skill_dir = root / SKILL_LOCATIONS[location] / safe + _check_project_path(root, skill_dir) if not skill_dir.exists(): return {"approved": False, "skill": safe, "warning": f"Skill {safe!r} does not exist."} skill_md = skill_dir / "SKILL.md" manifest = skill_dir / "manifest.json" - if not skill_md.exists() or not manifest.exists(): + if not skill_md.exists() or (location == "scaffold" and not manifest.exists()): return { "approved": False, "skill": safe, "warning": "SKILL.md and manifest.json must exist before approval.", } - checksum = _compute_checksum(skill_md, manifest) + checksum = _package_checksum(skill_dir) checksum_file = skill_dir / "CHECKSUM" checksum_file.write_text(checksum + "\n", encoding="utf-8") return { @@ -545,17 +581,23 @@ def approve_skill(target: Path, name: str) -> dict[str, object]: } -def export_skill(target: Path, name: str, *, output: Path | None = None) -> dict[str, object]: +def export_skill( + target: Path, name: str, *, output: Path | None = None, location: str = "scaffold", +) -> dict[str, object]: """Bundle a skill directory into a tar.gz archive for sharing.""" root = target.expanduser().resolve() - safe = _safe_skill_name(name) - skill_dir = root / SKILLS_RELATIVE / safe + safe = _resolve_skill_name(root, name, location) + skill_dir = root / SKILL_LOCATIONS[location] / safe + _check_project_path(root, skill_dir) if not skill_dir.exists(): return {"exported": False, "skill": safe, "warning": f"Skill {safe!r} does not exist."} output_path = output.expanduser().resolve() if output else root / f"{safe}.tar.gz" + if output_path.is_relative_to(skill_dir.resolve()): + raise CliError("Export destination is inside the skill package.", "Choose an output outside the skill directory.") + _package_entries(skill_dir) # Reject links/special files before creating an archive. with tarfile.open(output_path, "w:gz") as tar: - tar.add(skill_dir, arcname=safe) + tar.add(skill_dir.resolve(), arcname=safe) return {"exported": True, "skill": safe, "archive": str(output_path)} @@ -567,7 +609,7 @@ def export_skill(target: Path, name: str, *, output: Path | None = None) -> dict def _safe_skill_name(name: str) -> str: cleaned = re.sub(r"[^A-Za-z0-9._-]+", "-", name.strip()) cleaned = re.sub(r"-+", "-", cleaned).strip("-").lower() - if not cleaned: + if not cleaned or cleaned in {".", ".."}: raise CliError( "Skill name cannot be empty.", 'Pass a descriptive name, e.g. --name "Release Review".', @@ -577,3 +619,59 @@ def _safe_skill_name(name: str) -> str: def _compute_checksum(skill_md: Path, manifest: Path) -> str: return sha256_bytes(skill_md.read_bytes() + b"\x00" + manifest.read_bytes()) + + +def _resolve_skill_name(root: Path, name: str, location: str) -> str: + legacy = _safe_skill_name(name) + # Keep existing pre-standard names addressable without moving their directories. + if (root / SKILL_LOCATIONS[location] / legacy).exists(): + return legacy + canonical = re.sub(r"[^a-z0-9]+", "-", legacy).strip("-")[:64].rstrip("-") + if not canonical: + raise CliError("Skill name needs letters or digits.", "Choose a descriptive skill name.") + return canonical + + +def _check_project_path(root: Path, path: Path) -> None: + if not path.resolve().is_relative_to(root): + raise CliError("Skill path leaves the target project.", "Keep skills and their links inside --target.") + + +def _package_entries(skill_dir: Path) -> list[Path]: + """Do not follow package links: approval must never omit executable content.""" + entries: list[Path] = [] + + def visit(directory: Path) -> None: + for path in sorted(directory.iterdir()): + if path.is_symlink() or not (path.is_file() or path.is_dir()): + raise CliError( + f"Unsupported link or special file in skill: {path.relative_to(skill_dir)}.", + "Replace package links with regular files before lint, approval or export.", + ) + if path == skill_dir / "CHECKSUM": + continue + entries.append(path) + if path.is_dir(): + visit(path) + + visit(skill_dir) + return entries + + +def _package_checksum(skill_dir: Path) -> str: + records = [] + for path in _package_entries(skill_dir): + records.append([ + path.relative_to(skill_dir).as_posix(), + "directory" if path.is_dir() else "file", + bool(path.stat().st_mode & 0o111) if path.is_file() else False, + sha256_bytes(path.read_bytes()) if path.is_file() else "", + ]) + return "v2:" + sha256_bytes(json.dumps(records, ensure_ascii=True).encode("utf-8")) + + +def _package_finding(skill: str, rule: str, message: str) -> SkillFinding: + return SkillFinding( + severity="error", rule=rule, skill=skill, file="SKILL.md", line=None, + message=message, suggested_fix="Review the skill package and run skills lint again.", + ) diff --git a/src/coding_scaffold/templates/writers/scaffold.gitignore b/src/coding_scaffold/templates/writers/scaffold.gitignore index e3dbadc..9560342 100644 --- a/src/coding_scaffold/templates/writers/scaffold.gitignore +++ b/src/coding_scaffold/templates/writers/scaffold.gitignore @@ -2,3 +2,4 @@ credentials.local.json *.secret.* team/ +hook-report.json diff --git a/tests/fixtures/compatibility/README.md b/tests/fixtures/compatibility/README.md new file mode 100644 index 0000000..d4bf839 --- /dev/null +++ b/tests/fixtures/compatibility/README.md @@ -0,0 +1,17 @@ +# Native contract fixtures + +Reviewed 2026-09-19. These are small, manually reviewed examples of the fields we +generate, not complete copies of upstream schemas. Tests run offline; no fixture +commands or MCP endpoints are executed. + +- Codex config: https://learn.chatgpt.com/docs/config-file/config-reference +- Codex hooks: https://learn.chatgpt.com/docs/hooks +- Claude settings: https://code.claude.com/docs/en/settings +- Claude MCP: https://code.claude.com/docs/en/mcp#project-scope +- Claude hooks: https://code.claude.com/docs/en/hooks +- OpenCode schema: https://opencode.ai/config.json +- Skills: https://agentskills.io/specification + +When upstream changes, review the actual fields first, then update these fixtures, +the adapters, compatibility review metadata, and migration documentation together. +Do not regenerate expected fixtures from the implementation under test. diff --git a/tests/fixtures/compatibility/claude-mcp.json b/tests/fixtures/compatibility/claude-mcp.json new file mode 100644 index 0000000..7344cb0 --- /dev/null +++ b/tests/fixtures/compatibility/claude-mcp.json @@ -0,0 +1,6 @@ +{ + "mcpServers": { + "local-example": {"command": "npx", "args": ["-y", "@example/server@1.2.3", "/project"]}, + "remote-example": {"type": "http", "url": "https://example.com/mcp"} + } +} diff --git a/tests/fixtures/compatibility/native-contract.json b/tests/fixtures/compatibility/native-contract.json new file mode 100644 index 0000000..3eaabb7 --- /dev/null +++ b/tests/fixtures/compatibility/native-contract.json @@ -0,0 +1,13 @@ +{ + "snapshot_date": "2026-09-19", + "codex": {"approval_policy": "on-request", "sandbox_mode": "workspace-write"}, + "claude-code": { + "permissions": { + "defaultMode": "default", + "deny": ["Read(./.coding-scaffold/.env.local)", "Read(./.coding-scaffold/credentials.local.json)", "Read(**/.env)", "Read(**/.env.*)"] + }, + "attribution": {"commit": "", "pr": ""} + }, + "opencode": {"$schema": "https://opencode.ai/config.json", "default_agent": "plan", "share": "disabled"}, + "hook": {"type": "command", "command": "coding-scaffold tools hook-run", "timeout": 15} +} diff --git a/tests/fixtures/golden/adapter_paths.txt b/tests/fixtures/golden/adapter_paths.txt index 68562db..c7c3026 100644 --- a/tests/fixtures/golden/adapter_paths.txt +++ b/tests/fixtures/golden/adapter_paths.txt @@ -7,6 +7,7 @@ .claude/commands/knowledge-propose.md .claude/settings.json .codex/config.toml +.coding-scaffold/compatibility.json .opencode/agents/explorer.md .opencode/agents/implementer.md .opencode/agents/reviewer.md diff --git a/tests/fixtures/golden/scaffold_paths.txt b/tests/fixtures/golden/scaffold_paths.txt index a8a65fb..2dbd53f 100644 --- a/tests/fixtures/golden/scaffold_paths.txt +++ b/tests/fixtures/golden/scaffold_paths.txt @@ -8,6 +8,7 @@ .coding-scaffold/ORCHESTRATION.md .coding-scaffold/SKILLS.md .coding-scaffold/TOOLS.md +.coding-scaffold/compatibility.json .coding-scaffold/credentials.example.json .coding-scaffold/hardware.json .coding-scaffold/hermes.json diff --git a/tests/test_compatibility.py b/tests/test_compatibility.py new file mode 100644 index 0000000..22227e7 --- /dev/null +++ b/tests/test_compatibility.py @@ -0,0 +1,150 @@ +from __future__ import annotations + +import json +import socket +import subprocess +import tomllib +from dataclasses import replace +from datetime import date +from pathlib import Path + +import pytest + +from coding_scaffold.adapters import write_tool_adapter +from coding_scaffold.cli import main +from coding_scaffold.compatibility import COMPATIBILITY_RELATIVE, check_compatibility +from coding_scaffold.doctor import run_doctor +from coding_scaffold.eval_harness import run_eval +from coding_scaffold.hooks import write_hooks +from coding_scaffold.mcp import scan_mcp +from coding_scaffold.updater import refresh_scaffold + + +FIXTURES = Path(__file__).parent / "fixtures/compatibility" +TODAY = date(2026, 9, 19) + + +def test_generated_native_contracts_against_reviewed_fixtures(tmp_path): + expected = json.loads((FIXTURES / "native-contract.json").read_text()) + write_tool_adapter(tmp_path, ["codex", "claude-code", "opencode"]) + assert tomllib.loads((tmp_path / ".codex/config.toml").read_text()) == expected["codex"] + assert json.loads((tmp_path / ".claude/settings.json").read_text()) == expected["claude-code"] + assert json.loads((tmp_path / "opencode.json").read_text()) == expected["opencode"] + assert check_compatibility(tmp_path, today=TODAY).findings == [] + write_hooks(tmp_path, ["codex", "claude-code"]) + for relative in (".codex/hooks.json", ".claude/settings.json"): + hooks = json.loads((tmp_path / relative).read_text())["hooks"] + assert set(hooks) == {"SessionStart", "Stop"} + for event in hooks.values(): + assert event == [{"hooks": [expected["hook"]]}] + assert check_compatibility(tmp_path, today=TODAY).error_count == 0 + + +def test_standard_claude_mcp_is_scanned_and_gates_eval(tmp_path): + (tmp_path / ".mcp.json").write_bytes((FIXTURES / "claude-mcp.json").read_bytes()) + report = scan_mcp(tmp_path) + assert len(report.servers) == 2 + assert {s.kind for s in report.servers} == {"local", "remote"} + assert report.servers[0].package_version == "1.2.3" + check = next( + c for c in run_eval(tmp_path).checks if c.name == "mcp_policy_exists_if_mcp_detected" + ) + assert not check.passed + assert check.detail["server_count"] == 2 + + +@pytest.mark.parametrize( + "content", ["{broken", "[]", '{"mcpServers": []}', '{"mcpServers":{"bad":1}}'] +) +def test_malformed_mcp_cannot_pass_readiness_by_skipping(tmp_path, content): + (tmp_path / ".mcp.json").write_text(content) + assert scan_mcp(tmp_path).error_count > 0 + assert check_compatibility(tmp_path, today=TODAY).error_count > 0 + check = next( + c for c in run_eval(tmp_path).checks if c.name == "mcp_policy_exists_if_mcp_detected" + ) + assert not check.passed + + +@pytest.mark.parametrize( + ("relative", "content"), + [ + (".codex/config.toml", 'approval_mode = "suggest"'), + (".codex/config.toml", 'approval_policy = "suggest"'), + (".claude/settings.json", '{"permissions":{"defaultMode":"ask"}}'), + (".claude/settings.json", '{"permissions":{"deny":["**/.env"]}}'), + (".claude/settings.json", '{"permissions":[]}'), + (".codex/hooks.json", '{"hooks":{"Stop":[{"hooks":[{"type":"command"}]}]}}'), + ], +) +def test_retired_and_invalid_config_is_actionable(tmp_path, relative, content, capsys): + path = tmp_path / relative + path.parent.mkdir(parents=True) + path.write_text(content) + assert main(["tools", "compatibility", "--target", str(tmp_path), "--json"]) == 1 + assert json.loads(capsys.readouterr().out)["errors"] > 0 + + +def test_provenance_is_saved_and_overdue_reviews_reported(tmp_path, monkeypatch): + write_tool_adapter(tmp_path, "codex") + path = tmp_path / COMPATIBILITY_RELATIVE + payload = json.loads(path.read_text()) + assert payload["adapters"]["codex"]["source_urls"] + assert all( + m["source_url"] and m["upstream_version"] for m in payload["model_catalog"]["models"] + ) + payload["adapters"]["codex"]["reviewed_at"] = "2020-01-01" + path.write_text(json.dumps(payload)) + report = check_compatibility(tmp_path, today=TODAY) + assert report.error_count == 0 + assert any(f.rule == "review-overdue" for f in report.findings) + monkeypatch.setattr("coding_scaffold.doctor._system_notes", lambda **kwargs: []) + assert any("2020-01-01" in note for note in run_doctor(tmp_path).notes) + assert main(["tools", "compatibility", "--target", str(tmp_path), "--strict"]) == 1 + + +def test_invalid_provenance_is_reported_not_crashed(tmp_path): + path = tmp_path / COMPATIBILITY_RELATIVE + path.parent.mkdir(parents=True) + path.write_text('{"schema_version":1,"adapters":[],"model_catalog":null}') + assert any(f.rule == "invalid-provenance" for f in check_compatibility(tmp_path).findings) + + +def test_refresh_preserves_edited_provenance_and_enabled_hooks(tmp_path, scaffold_inputs): + fixture = scaffold_inputs() + intake = replace(fixture.intake, tools=["codex", "claude-code"]) + args = (tmp_path, intake, fixture.hardware, fixture.providers, fixture.routing) + refresh_scaffold(*args) + path = tmp_path / COMPATIBILITY_RELATIVE + payload = json.loads(path.read_text()) + payload["team_note"] = "Reviewed by platform" + path.write_text(json.dumps(payload)) + write_hooks(tmp_path, ["codex", "claude-code"]) + before = (tmp_path / ".claude/settings.json").read_bytes() + result = refresh_scaffold(*args) + assert json.loads(path.read_text())["team_note"] == "Reviewed by platform" + assert path.with_name("compatibility.json.new") in result.staged + assert (tmp_path / ".claude/settings.json").read_bytes() == before + assert (tmp_path / ".codex/hooks.json").exists() + + +def test_checks_are_offline_and_read_only(tmp_path, monkeypatch): + write_tool_adapter(tmp_path, "codex") + before = {p.relative_to(tmp_path): p.read_bytes() for p in tmp_path.rglob("*") if p.is_file()} + + def forbidden(*args, **kwargs): + raise AssertionError("Offline checks cannot open sockets or execute commands") + + monkeypatch.setattr(socket, "socket", forbidden) + monkeypatch.setattr(subprocess, "Popen", forbidden) + assert check_compatibility(tmp_path, today=TODAY).error_count == 0 + after = {p.relative_to(tmp_path): p.read_bytes() for p in tmp_path.rglob("*") if p.is_file()} + assert before == after + + +def test_legacy_project_reports_missing_snapshot(tmp_path): + (tmp_path / ".codex").mkdir() + (tmp_path / ".codex/config.toml").write_text('approval_policy = "on-request"') + report = check_compatibility(tmp_path, today=TODAY) + assert report.error_count == 0 + assert any(f.rule == "missing-provenance" for f in report.findings) diff --git a/tests/test_hooks.py b/tests/test_hooks.py new file mode 100644 index 0000000..12898ce --- /dev/null +++ b/tests/test_hooks.py @@ -0,0 +1,133 @@ +from __future__ import annotations + +import io +import json +import socket +import subprocess + +import pytest + +from coding_scaffold.cli import main +from coding_scaffold.errors import CliError +from coding_scaffold.hooks import HOOK_COMMAND, HOOK_REPORT_RELATIVE, run_hook, write_hooks + + +def test_hooks_opt_in_merges_without_replacing_user_settings(tmp_path): + path = tmp_path / ".claude/settings.json" + path.parent.mkdir() + user_hook = {"matcher": "startup", "hooks": [{"type": "command", "command": "echo custom"}]} + settings = {"permissions": {"deny": ["Read(**/.env)"]}, "hooks": {"SessionStart": [user_hook]}} + path.write_text(json.dumps(settings)) + result = write_hooks(tmp_path, ["claude-code", "codex"]) + saved = json.loads(path.read_text()) + assert saved["permissions"] == settings["permissions"] + assert saved["hooks"]["SessionStart"][0] == user_hook + before = path.read_bytes() + assert len(result["files"]) == 2 + assert write_hooks(tmp_path, ["claude-code", "codex"])["files"] == [] + assert path.read_bytes() == before + + +def test_existing_customized_handler_is_preserved(tmp_path): + write_hooks(tmp_path, ["codex"]) + path = tmp_path / ".codex/hooks.json" + payload = json.loads(path.read_text()) + payload["hooks"]["Stop"][0]["hooks"][0]["timeout"] = 30 + path.write_text(json.dumps(payload)) + assert write_hooks(tmp_path, ["codex"])["files"] == [] + assert json.loads(path.read_text())["hooks"]["Stop"][0]["hooks"][0]["timeout"] == 30 + + +def test_invalid_existing_config_prevents_partial_install(tmp_path): + (tmp_path / ".claude").mkdir() + path = tmp_path / ".claude/settings.json" + path.write_text("{bad") + with pytest.raises(CliError, match="Cannot merge"): + write_hooks(tmp_path, ["codex", "claude-code"]) + assert not (tmp_path / ".codex/hooks.json").exists() + assert path.read_text() == "{bad" + + +def test_hook_runs_do_not_execute_commands_or_store_sensitive_payload(tmp_path, monkeypatch): + def forbidden(*args, **kwargs): + raise AssertionError("Hooks must not execute commands or open sockets") + + monkeypatch.setattr(socket, "socket", forbidden) + monkeypatch.setattr(subprocess, "Popen", forbidden) + payload = { + "hook_event_name": "SessionStart", + "cwd": str(tmp_path), + "last_assistant_message": "SECRET_CHAT", + "tool_input": {"command": "SECRET_COMMAND"}, + } + assert run_hook(payload)["hookSpecificOutput"]["hookEventName"] == "SessionStart" + assert list(tmp_path.iterdir()) == [] + payload["hook_event_name"] = "Stop" + assert run_hook(payload) == {} + report = (tmp_path / HOOK_REPORT_RELATIVE).read_text() + assert "SECRET" not in report + assert json.loads(report)["project_tests_run"] is False + + +def test_stop_errors_continue_once_and_report_remains_failed(tmp_path): + (tmp_path / ".codex").mkdir() + (tmp_path / ".codex/config.toml").write_text('approval_mode = "suggest"') + payload = {"hook_event_name": "Stop", "cwd": str(tmp_path)} + assert run_hook(payload)["decision"] == "block" + result = run_hook({**payload, "stop_hook_active": True}) + assert "decision" not in result + assert "limited to one" in result["systemMessage"] + report = json.loads((tmp_path / HOOK_REPORT_RELATIVE).read_text()) + assert report["checks"]["compatibility_errors"] == 1 + + +def test_hook_uses_worktree_root_from_nested_cwd(tmp_path): + (tmp_path / ".git").write_text("gitdir: /not-read") + nested = tmp_path / "src/nested" + nested.mkdir(parents=True) + run_hook({"hook_event_name": "Stop", "cwd": str(nested)}) + assert (tmp_path / HOOK_REPORT_RELATIVE).exists() + assert not (nested / ".coding-scaffold").exists() + + +@pytest.mark.parametrize( + "payload", + [ + [], + {}, + {"hook_event_name": "Stop", "cwd": "."}, + {"hook_event_name": "PostToolUse", "cwd": "/"}, + ], +) +def test_invalid_event_payload_is_rejected(payload): + with pytest.raises(CliError): + run_hook(payload) + + +def test_hook_cli_outputs_only_native_json(tmp_path, monkeypatch, capsys): + assert main(["tools", "hooks", "--target", str(tmp_path), "--tool", "codex", "--json"]) == 0 + assert HOOK_COMMAND in (tmp_path / ".codex/hooks.json").read_text() + capsys.readouterr() + monkeypatch.setattr( + "sys.stdin", io.StringIO(json.dumps({"hook_event_name": "Stop", "cwd": str(tmp_path)})) + ) + assert main(["tools", "hook-run"]) == 0 + assert json.loads(capsys.readouterr().out) == {} + + +@pytest.mark.parametrize( + "payload", + [ + {"hook_event_name": []}, + {"hook_event_name": "Stop", "cwd": "/", "stop_hook_active": "false"}, + ], +) +def test_malformed_event_fields_raise_actionable_errors(payload): + with pytest.raises(CliError): + run_hook(payload) + + +def test_oversized_hook_payload_is_rejected_without_echo(monkeypatch, capsys): + monkeypatch.setattr("sys.stdin", io.StringIO("SECRET" * 180_000)) + assert main(["tools", "hook-run"]) == 1 + assert "SECRET" not in capsys.readouterr().err diff --git a/tests/test_native_skills.py b/tests/test_native_skills.py new file mode 100644 index 0000000..527894e --- /dev/null +++ b/tests/test_native_skills.py @@ -0,0 +1,211 @@ +from __future__ import annotations + +import json + +import pytest + +from coding_scaffold.adapters import write_tool_adapter +from coding_scaffold.cli import main +from coding_scaffold.errors import CliError +from coding_scaffold.file_ops import sha256_bytes +from coding_scaffold.skill_metadata import validate_skill_metadata +from coding_scaffold.skills import ( + SKILL_LOCATIONS, + approve_skill, + export_skill, + lint_skills, + new_skill, +) + + +def test_generated_codex_skills_are_inspected(tmp_path): + write_tool_adapter(tmp_path, "codex") + report = lint_skills(tmp_path) + assert len(report.skills_scanned) == 2 + assert report.error_count == 0 + assert not any(f.rule.startswith("missing-") for f in report.findings) + path = tmp_path / ".agents/skills/first-session/SKILL.md" + path.write_text("---\nname: wrong-name\ndescription: Test.\n---\n") + assert any(f.rule == "invalid-frontmatter" for f in lint_skills(tmp_path).findings) + + +@pytest.mark.parametrize("location", list(SKILL_LOCATIONS)) +def test_native_skill_cli_lifecycle(tmp_path, location, capsys): + assert ( + main( + [ + "skills", + "new", + "demo", + "--target", + str(tmp_path), + "--location", + location, + "--owner", + "team", + ] + ) + == 0 + ) + assert ( + main(["skills", "approve", "demo", "--target", str(tmp_path), "--location", location]) == 0 + ) + assert ( + main(["skills", "export", "demo", "--target", str(tmp_path), "--location", location]) == 0 + ) + assert (tmp_path / "demo.tar.gz").exists() + assert lint_skills(tmp_path).error_count == 0 + + +@pytest.mark.parametrize("change", ["edit", "add", "delete", "rename", "executable", "reference"]) +def test_full_package_approval_detects_changes(tmp_path, change): + path = new_skill(tmp_path, "demo", owner="team").path + helper = path / "scripts/helper.py" + helper.write_text("print('before')\n") + reference = path / "README.md" + approve_skill(tmp_path, "demo") + assert not any(f.rule == "checksum-drift" for f in lint_skills(tmp_path).findings) + if change == "edit": + helper.write_text("print('after')\n") + elif change == "add": + (path / "scripts/new.py").write_text("pass\n") + elif change == "delete": + helper.unlink() + elif change == "rename": + helper.rename(path / "scripts/renamed.py") + elif change == "executable": + helper.chmod(helper.stat().st_mode ^ 0o100) + else: + reference.write_text("Changed supporting instructions.\n") + assert any(f.rule == "checksum-drift" for f in lint_skills(tmp_path).findings) + approve_skill(tmp_path, "demo") + assert not any(f.rule == "checksum-drift" for f in lint_skills(tmp_path).findings) + + +def test_legacy_checksum_requires_review_and_can_be_migrated(tmp_path): + path = new_skill(tmp_path, "demo", owner="team").path + digest = sha256_bytes( + (path / "SKILL.md").read_bytes() + b"\0" + (path / "manifest.json").read_bytes() + ) + (path / "CHECKSUM").write_text(digest) + report = lint_skills(tmp_path) + assert any(f.rule == "legacy-checksum" for f in report.findings) + assert not any(f.rule == "checksum-drift" for f in report.findings) + assert approve_skill(tmp_path, "demo")["checksum"].startswith("v2:") + assert not any(f.rule == "legacy-checksum" for f in lint_skills(tmp_path).findings) + + +def test_native_skills_do_not_require_scaffold_manifest(tmp_path): + path = tmp_path / ".claude/skills/demo" + path.mkdir(parents=True) + (path / "SKILL.md").write_text("---\nname: demo\ndescription: Run the demo.\n---\n# Demo\n") + assert lint_skills(tmp_path).findings == [] + assert approve_skill(tmp_path, "demo", location="claude")["approved"] + + +def test_duplicate_names_are_distinguished_and_internal_aliases_deduplicated(tmp_path): + first = new_skill(tmp_path, "demo", owner="team", location="agents").path + new_skill(tmp_path, "demo", owner="team", location="opencode") + (tmp_path / ".claude/skills").mkdir(parents=True) + (tmp_path / ".claude/skills/demo").symlink_to(first, target_is_directory=True) + assert lint_skills(tmp_path).skills_scanned == [".agents/skills/demo", ".opencode/skills/demo"] + + +def test_package_links_cannot_hide_changed_helpers(tmp_path): + path = new_skill(tmp_path, "demo").path + external = tmp_path / "outside.py" + external.write_text("pass\n") + (path / "scripts/helper.py").symlink_to(external) + assert lint_skills(tmp_path).error_count > 0 + with pytest.raises(CliError, match="link"): + approve_skill(tmp_path, "demo") + with pytest.raises(CliError, match="link"): + export_skill(tmp_path, "demo") + assert not (tmp_path / "demo.tar.gz").exists() + + +def test_external_skill_directory_is_not_read(tmp_path): + project = tmp_path / "project" + (project / ".agents/skills").mkdir(parents=True) + external = tmp_path / "external" + external.mkdir() + (project / ".agents/skills/demo").symlink_to(external, target_is_directory=True) + assert lint_skills(project).error_count == 1 + with pytest.raises(CliError, match="leaves"): + new_skill(project, "demo", location="agents") + + +@pytest.mark.parametrize("name", [".", ".."]) +def test_traversal_skill_names_rejected(tmp_path, name): + with pytest.raises(CliError): + new_skill(tmp_path, name) + assert not (tmp_path / ".coding-scaffold").exists() + + +@pytest.mark.parametrize( + "description", + [ + "Run a demo.", + '"Run a demo: with a colon."', + "'Use the team''s demo.'", + ">-\n Run a demo\n when asked.", + "|\n Run a demo.\n Check its output.", + ], +) +def test_required_frontmatter_scalar_forms(description): + text = f"---\nname: demo\ndescription: {description}\nmetadata:\n owner: team\n---\n" + assert validate_skill_metadata(text, "demo") == [] + + +@pytest.mark.parametrize( + "frontmatter", + [ + "name: demo", + "name: wrong\ndescription: Demo", + "name: demo\ndescription: []", + "name: demo\ndescription: null", + "name: demo\ndescription: Demo\nname: demo", + "name: demo\ndescription: " + "x" * 1025, + ], +) +def test_invalid_required_frontmatter(frontmatter): + assert validate_skill_metadata(f"---\n{frontmatter}\n---\n", "demo") + + +def test_export_inside_package_is_rejected(tmp_path): + path = new_skill(tmp_path, "demo").path + with pytest.raises(CliError, match="inside"): + export_skill(tmp_path, "demo", output=path / "self.tar.gz") + + +def test_native_lint_json_identifies_source(tmp_path, capsys): + new_skill(tmp_path, "demo", owner="team", location="agents") + assert main(["skills", "lint", "--target", str(tmp_path), "--json"]) == 0 + assert json.loads(capsys.readouterr().out)["skills_scanned"] == [".agents/skills/demo"] + + +@pytest.mark.parametrize( + "description", ['"Example: demo." # comment', "'Example: demo.' # comment"] +) +def test_quoted_frontmatter_allows_yaml_comments(description): + assert ( + validate_skill_metadata(f"---\nname: demo\ndescription: {description}\n---\n", "demo") == [] + ) + + +def test_slug_normalization_is_shared_by_create_approve_and_export(tmp_path): + name = "Demo_Release.v2" + result = new_skill(tmp_path, name, owner="team") + assert result.skill == "demo-release-v2" + assert approve_skill(tmp_path, name)["approved"] + assert export_skill(tmp_path, name)["exported"] + assert lint_skills(tmp_path).error_count == 0 + + +def test_existing_pre_standard_names_remain_addressable(tmp_path): + result = new_skill(tmp_path, "demo", owner="team") + legacy = result.path.with_name("demo_v1") + result.path.rename(legacy) + assert approve_skill(tmp_path, "demo_v1")["approved"] + assert export_skill(tmp_path, "demo_v1")["exported"] + assert new_skill(tmp_path, "demo_v1").path == legacy diff --git a/uv.lock b/uv.lock index 32137d8..f0c7825 100644 --- a/uv.lock +++ b/uv.lock @@ -286,7 +286,7 @@ wheels = [ [[package]] name = "coding-scaffold" -version = "0.7.0" +version = "0.8.0" source = { editable = "." } [package.optional-dependencies]