showdar-skills 0.12.0 → 0.12.1

package/CHANGELOG.md

@@ -6,6 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.12.1]
+
+### Fixed
+
+- Added read-only `showdar guard --mutation local-write --json` to block task writes on integration branches until task branch preparation, with an explicit repository-local direct-work opt-in.
+- Updated native harness guidance and mutating skills to require automatic branch preparation and a passing guard before agent-controlled file writes; Cursor routing rules now apply automatically.
+- Re-adding an existing Showdar-managed skill refreshes its packaged SKILL.md from the upgraded CLI only when its recorded hash matches; user-modified skill files are preserved and cause an explicit error.
+- This is an agent/tool-instruction gate, not a cross-harness filesystem interceptor, and does not grant source/remote mutation authority.
+
+
 ## [0.12.0]
 
 ### Added

package/README.md

@@ -47,6 +47,7 @@ printf '%s\n' 'Implement the approved underwriting form and add tests' | showdar
 showdar route --prompt "Explain insurance terminology"
 showdar git-start --dry-run --type feature --name "IDP-123 Add pricing form"
 showdar git-start --type feature --name "IDP-123 Add pricing form"
+showdar guard --mutation local-write --json
 ```
 
 Prefer `--stdin` for arbitrary or multiline prompts. Supply stdin as literal data;
@@ -91,6 +92,18 @@ The four workflows remain native discoverable/installable skills; `route` does n
 introduce workflow selection. Profiles remain primitive-only: `full` contains all
 18 primitives, and the insurance profile remains unchanged.
 
+Before the first local-write task source edit, the coding agent must run
+`showdar guard --mutation local-write --json` and require `ok=true` and
+`data.allowed=true`. When on develop/main/integration, it must execute
+`showdar git-start` (not only suggest it), confirm the branch, and rerun guard.
+This is an instruction-level agent preflight, **not an OS/filesystem hook**:
+tools that ignore Showdar can still write files. Cursor's generated rule now
+uses `alwaysApply: true` so the Git preflight isn't limited to manually
+activated skill calls. Existing project guidance must be refreshed after the
+package update (for example by running `showdar add git` with the new CLI).
+Re-adding an installed skill refreshes its managed SKILL.md and guidance only
+if the owned copy has not been locally modified; drift refuses to overwrite.
+
 Before the first local-write task source edit on develop/development/dev/main/master
 or the repository default/integration branch, prepare a task branch. Priority is
 repository instructions/documented convention, explicit current user instruction,

package/bin/showdar.js

@@ -2,6 +2,7 @@
 import path from 'node:path';
 import { parseArgs } from 'node:util';
 import { startTaskBranch, formatGitStart } from '../src/git-start.js';
+import { guardMutation, formatMutationGuard } from '../src/git-guard.js';
 import { routeRequest, formatRoute } from '../src/runtime-route.js';
 import { homedir } from 'node:os';
 import { readFile } from 'node:fs/promises';
@@ -44,6 +45,10 @@ function printHelp(version, command = null) {
     console.log('Usage: showdar git-start --type <type> --name <task> [--base <branch>] [--dry-run] [--json]');
     return;
   }
+  if (command === 'guard') {
+    console.log('Usage: showdar guard --mutation <read-only|local-write> [--json]');
+    return;
+  }
   if (command === 'init') {
     console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar init ${scopeUsage} [--profile <name>] [--ai <universal|codex|opencode|cursor|claude|all>]\n\nDefaults: scope project, profile full, AI target universal.\nProject scope writes native skills, one native instruction surface, and project .showdar.json. Global scope writes verified user skill directories and ~/.showdar/global.json without instruction files. Codex and universal use .agents/skills in project scope and ~/.agents/skills in global scope; cursor uses .cursor/skills in project scope and ~/.cursor/skills in global scope; --ai all writes each shared destination once, generates OpenCode and Claude commands, and writes only the AGENTS.md block.\n\nProfiles: ${Object.keys(PROFILES).join(', ')}\nDeprecated aliases: ${Object.entries(PROFILE_ALIASES).map(([alias, target]) => `${alias} -> ${target}`).join(', ')}\nAI targets: ${AI_TARGETS.join(', ')}`);
     return;
@@ -56,7 +61,7 @@ function printHelp(version, command = null) {
     console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar add <skill> [--ai <universal|codex|opencode|cursor|claude>] [--scope <project|global>]\n\nExamples:\n  showdar add debug\n  showdar add showdar-security\n  showdar add test --ai cursor\n  showdar add review --scope global --ai claude\n\nDefault scope: project. Default AI target: universal, or the configured .showdar.json value when present.`);
     return;
   }
-  console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar init ${scopeUsage} [--profile <name>] [--ai <universal|codex|opencode|cursor|claude|all>] [--pack <local-path>]\n  showdar add <skill> [--ai <universal|codex|opencode|cursor|claude>] [--scope <project|global>]\n  showdar route (--stdin | --prompt <text>) [--json]\n  showdar git-start --type <type> --name <task> [--base <branch>] [--dry-run] [--json]\n  showdar add-pack <local-path>\n  showdar remove-pack <name>\n  showdar add-workflow <local-path>\n  showdar status ${scopeUsage}\n  showdar doctor ${scopeUsage}\n  showdar validate\n  showdar list [--extensions]\n  showdar remove ${scopeUsage}\n  showdar create-pack <path> [--vendor <vendor>] [--description <text>] [--with-workflow <id>] [--with-profile <name>]\n  showdar validate-pack <local-path> [--json]\n  showdar inspect-pack <local-path> [--json] [--checkpoint <file>]\n  showdar doctor ${scopeUsage} [--extensions] [--json]\n  showdar update-pack <local-path> [--dry-run] [--json]\n  showdar validate\n  showdar list [--extensions] [--json]\n  showdar remove ${scopeUsage}\n\nExtension packs accept local directories/workspace paths only; tarball, URL, Git, and registry sources are rejected.\n\nDefaults: scope project, profile full, AI target universal.\nProfiles: ${Object.keys(PROFILES).join(', ')}\nDeprecated aliases: ${Object.entries(PROFILE_ALIASES).map(([alias, target]) => `${alias} -> ${target}`).join(', ')}\nAI targets: ${AI_TARGETS.join(', ')}`);
+  console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar init ${scopeUsage} [--profile <name>] [--ai <universal|codex|opencode|cursor|claude|all>] [--pack <local-path>]\n  showdar add <skill> [--ai <universal|codex|opencode|cursor|claude>] [--scope <project|global>]\n  showdar route (--stdin | --prompt <text>) [--json]\n  showdar git-start --type <type> --name <task> [--base <branch>] [--dry-run] [--json]\n  showdar guard --mutation <read-only|local-write> [--json]\n  showdar add-pack <local-path>\n  showdar remove-pack <name>\n  showdar add-workflow <local-path>\n  showdar status ${scopeUsage}\n  showdar doctor ${scopeUsage}\n  showdar validate\n  showdar list [--extensions]\n  showdar remove ${scopeUsage}\n  showdar create-pack <path> [--vendor <vendor>] [--description <text>] [--with-workflow <id>] [--with-profile <name>]\n  showdar validate-pack <local-path> [--json]\n  showdar inspect-pack <local-path> [--json] [--checkpoint <file>]\n  showdar doctor ${scopeUsage} [--extensions] [--json]\n  showdar update-pack <local-path> [--dry-run] [--json]\n  showdar validate\n  showdar list [--extensions] [--json]\n  showdar remove ${scopeUsage}\n\nExtension packs accept local directories/workspace paths only; tarball, URL, Git, and registry sources are rejected.\n\nDefaults: scope project, profile full, AI target universal.\nProfiles: ${Object.keys(PROFILES).join(', ')}\nDeprecated aliases: ${Object.entries(PROFILE_ALIASES).map(([alias, target]) => `${alias} -> ${target}`).join(', ')}\nAI targets: ${AI_TARGETS.join(', ')}`);
 }
 
 async function main() {
@@ -70,10 +75,22 @@ async function main() {
     console.log(version);
     return;
   }
-  if (!['route', 'git-start'].includes(command) && (args.includes('--help') || args.includes('-h'))) return printHelp(version, command);
+  if (!['route', 'git-start', 'guard'].includes(command) && (args.includes('--help') || args.includes('-h'))) return printHelp(version, command);
 
   const scope = ['init', 'status', 'doctor', 'remove', 'add'].includes(command) ? scopeAfter(args) : null;
 
+  if (command === 'guard') {
+    const { values } = parseArgs({ args: args.slice(1), options: { mutation: { type: 'string' }, json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } } });
+    if (values.help) return printHelp(version, command);
+    const data = guardMutation({ cwd: projectRoot, mutation: values.mutation });
+    const errors = data.allowed ? [] : [{ code: data.code, message: 'Task-owned source mutation is blocked until Git preflight passes.' }];
+    console.log(values.json
+      ? JSON.stringify({ schemaVersion: 1, command, ok: data.allowed, data, warnings: [], errors }, null, 2)
+      : formatMutationGuard(data));
+    if (!data.allowed) process.exitCode = 1;
+    return;
+  }
+
   if (command === 'git-start') {
     const { values } = parseArgs({ args: args.slice(1), options: { type: { type: 'string' }, name: { type: 'string' }, base: { type: 'string' }, 'dry-run': { type: 'boolean' }, json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } } });
     if (values.help) return printHelp(version, command);
@@ -377,7 +394,7 @@ async function main() {
 
 main().catch((error) => {
   const command = process.argv[2];
-  if (['route', 'git-start'].includes(command) && process.argv.slice(3).includes('--json')) {
+  if (['route', 'git-start', 'guard'].includes(command) && process.argv.slice(3).includes('--json')) {
     console.log(JSON.stringify({ schemaVersion: 1, command, ok: false, data: null, warnings: [], errors: [{ code: 'INVALID_REQUEST', message: error.message }] }, null, 2));
   } else console.error(`showdar: ${error.message}`);
   process.exitCode = 1;

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "showdar-skills",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "Production-grade software engineering lifecycle skills for coding agents.",
   "type": "module",
-  "bin": { "showdar": "./bin/showdar.js" },
+  "bin": {
+    "showdar": "./bin/showdar.js"
+  },
   "scripts": {
     "test": "node --test",
     "validate": "node bin/showdar.js validate",
@@ -16,9 +18,38 @@
     "smoke": "node scripts/package-smoke.mjs",
     "release:check": "node scripts/check-release-version.mjs"
   },
-  "engines": { "node": ">=20" },
-  "files": ["bin", "src", "config", "skills", "commands", "router", "bundles", "profiles", "engine", "README.md", "LICENSE", "CHANGELOG.md", "MIGRATION.md"],
-  "keywords": ["agent-skills", "coding-agents", "codex", "opencode", "claude-code", "software-engineering", "developer-tools", "requirements", "qa", "security", "devops", "workflow"],
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "bin",
+    "src",
+    "config",
+    "skills",
+    "commands",
+    "router",
+    "bundles",
+    "profiles",
+    "engine",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "MIGRATION.md"
+  ],
+  "keywords": [
+    "agent-skills",
+    "coding-agents",
+    "codex",
+    "opencode",
+    "claude-code",
+    "software-engineering",
+    "developer-tools",
+    "requirements",
+    "qa",
+    "security",
+    "devops",
+    "workflow"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",

package/skills/showdar-bugfix/SKILL.md

@@ -5,6 +5,11 @@ description: Use when resolving an observed defect end-to-end, adaptively sequen
 
 # Showdar Bugfix
 
+## Mandatory Git preflight for task-owned writes
+
+Before any task-owned source/config/test/docs write, apply `showdar-git` branch policy: on develop/main/integration, inspect repository conventions and EXECUTE `showdar git-start --type <type> --name "<task>"` to prepare the task branch before editing. Then run `showdar guard --mutation local-write --json` and require `ok=true` and `data.allowed=true` before ANY file-writing tool. If blocked, STOP before editing. On an existing task branch run guard without creating a new branch. Recheck when a read-only stage turns into a write. If CLI is missing, manually prepare and verify safe Git branch state; do not silently write on develop/main. Explicit documented direct-work policy wins; never infer stash, reset, commit, merge, or push.
+
+
 ## Purpose
 
 - Resolve an observed defect safely from evidence to verified fix.

package/skills/showdar-build/SKILL.md

@@ -5,6 +5,11 @@ description: Use when implementing or refactoring an agreed application change w
 
 # Showdar Build
 
+## Mandatory Git preflight for task-owned writes
+
+Before any task-owned source/config/test/docs write, apply `showdar-git` branch policy: on develop/main/integration, inspect repository conventions and EXECUTE `showdar git-start --type <type> --name "<task>"` to prepare the task branch before editing. Then run `showdar guard --mutation local-write --json` and require `ok=true` and `data.allowed=true` before ANY file-writing tool. If blocked, STOP before editing. On an existing task branch run guard without creating a new branch. Recheck when a read-only stage turns into a write. If CLI is missing, manually prepare and verify safe Git branch state; do not silently write on develop/main. Explicit documented direct-work policy wins; never infer stash, reset, commit, merge, or push.
+
+
 ## Purpose
 
 - Convert an approved requirement/plan into maintainable production code.

package/skills/showdar-debug/SKILL.md

@@ -5,6 +5,11 @@ description: Use when observed behavior fails through crashes, regressions, buil
 
 # Showdar Debug
 
+## Mandatory Git preflight for task-owned writes
+
+Before any task-owned source/config/test/docs write, apply `showdar-git` branch policy: on develop/main/integration, inspect repository conventions and EXECUTE `showdar git-start --type <type> --name "<task>"` to prepare the task branch before editing. Then run `showdar guard --mutation local-write --json` and require `ok=true` and `data.allowed=true` before ANY file-writing tool. If blocked, STOP before editing. On an existing task branch run guard without creating a new branch. Recheck when a read-only stage turns into a write. If CLI is missing, manually prepare and verify safe Git branch state; do not silently write on develop/main. Explicit documented direct-work policy wins; never infer stash, reset, commit, merge, or push.
+
+
 ## Purpose
 
 - Find and confirm root cause before modifying production behavior.

package/skills/showdar-design/SKILL.md

@@ -5,6 +5,11 @@ description: Use when product UI needs design direction, UX decisions, responsiv
 
 # Showdar Design
 
+## Mandatory Git preflight for task-owned writes
+
+Before any task-owned source/config/test/docs write, apply `showdar-git` branch policy: on develop/main/integration, inspect repository conventions and EXECUTE `showdar git-start --type <type> --name "<task>"` to prepare the task branch before editing. Then run `showdar guard --mutation local-write --json` and require `ok=true` and `data.allowed=true` before ANY file-writing tool. If blocked, STOP before editing. On an existing task branch run guard without creating a new branch. Recheck when a read-only stage turns into a write. If CLI is missing, manually prepare and verify safe Git branch state; do not silently write on develop/main. Explicit documented direct-work policy wins; never infer stash, reset, commit, merge, or push.
+
+
 ## Purpose
 
 - Produce product-specific UI direction instead of generic component-library output.

package/skills/showdar-feature/SKILL.md

@@ -5,6 +5,11 @@ description: Use when implementing a complete feature end-to-end, adaptively seq
 
 # Showdar Feature
 
+## Mandatory Git preflight for task-owned writes
+
+Before any task-owned source/config/test/docs write, apply `showdar-git` branch policy: on develop/main/integration, inspect repository conventions and EXECUTE `showdar git-start --type <type> --name "<task>"` to prepare the task branch before editing. Then run `showdar guard --mutation local-write --json` and require `ok=true` and `data.allowed=true` before ANY file-writing tool. If blocked, STOP before editing. On an existing task branch run guard without creating a new branch. Recheck when a read-only stage turns into a write. If CLI is missing, manually prepare and verify safe Git branch state; do not silently write on develop/main. Explicit documented direct-work policy wins; never infer stash, reset, commit, merge, or push.
+
+
 ## Purpose
 
 - Implement a complete feature end-to-end by sequencing primitive skills.

package/skills/showdar-git/SKILL.md

@@ -48,6 +48,12 @@ This skill owns repository state transitions, not source-code review or GitHub a
 
 ## Task branch isolation
 
+**Mandatory pre-write gate:** Installing `showdar-git` adds project-wide branch guidance. For every task-owned source/config/test/docs change, including tasks executed by another primitive, inspect current Git state, then run `showdar guard --mutation local-write --json` before file-writing tools. Require `ok=true` and `data.allowed=true`; if blocked, STOP without editing.
+
+On integration/default branches proactively run `showdar git-start --type <type> --name "<task>"` after repository/user convention inspection, then rerun guard. On an existing task branch, run guard without creating a nested branch. If the CLI is unavailable, use equivalent manual safe Git branch preparation and verify branch before editing. Explicit direct-work policy is a reviewed repo-local opt-in (`showdar.gitDirectWork=true`); never silently set it to bypass the gate.
+
+This gate is enforced by agent/tool instructions, not a filesystem interceptor; arbitrary writes outside Showdar remain possible. Neither guard nor git-start authorizes edits, commits, merges, or pushes.
+
 Before the first task-owned source edit for a local-write engineering task, inspect Git state (`git status --short`, current branch, branch history and repository policy). Direct develop/main edits are not the default: on develop, development, dev, main, master or the default/integration branch, prepare a dedicated task branch before source mutation.
 
 Priority: repository instructions/documented branching convention; explicit current user instruction; clearly detected existing convention; Showdar safe default. Explicit trunk-based/direct-work policy wins: do not impose GitFlow. Branch preparation does not authorize source mutation.

package/skills/showdar-incident/SKILL.md

@@ -5,6 +5,11 @@ description: Use when investigating and recovering from an active operational in
 
 # Showdar Incident
 
+## Mandatory Git preflight for task-owned writes
+
+Before any task-owned source/config/test/docs write, apply `showdar-git` branch policy: on develop/main/integration, inspect repository conventions and EXECUTE `showdar git-start --type <type> --name "<task>"` to prepare the task branch before editing. Then run `showdar guard --mutation local-write --json` and require `ok=true` and `data.allowed=true` before ANY file-writing tool. If blocked, STOP before editing. On an existing task branch run guard without creating a new branch. Recheck when a read-only stage turns into a write. If CLI is missing, manually prepare and verify safe Git branch state; do not silently write on develop/main. Explicit documented direct-work policy wins; never infer stash, reset, commit, merge, or push.
+
+
 ## Purpose
 
 - Handle an active operational failure or service-impacting incident.

package/skills/showdar-ops/SKILL.md

@@ -5,6 +5,11 @@ description: Use when inspecting or changing CI/CD, containers, environments, de
 
 # Showdar Ops
 
+## Mandatory Git preflight for task-owned writes
+
+Before any task-owned source/config/test/docs write, apply `showdar-git` branch policy: on develop/main/integration, inspect repository conventions and EXECUTE `showdar git-start --type <type> --name "<task>"` to prepare the task branch before editing. Then run `showdar guard --mutation local-write --json` and require `ok=true` and `data.allowed=true` before ANY file-writing tool. If blocked, STOP before editing. On an existing task branch run guard without creating a new branch. Recheck when a read-only stage turns into a write. If CLI is missing, manually prepare and verify safe Git branch state; do not silently write on develop/main. Explicit documented direct-work policy wins; never infer stash, reset, commit, merge, or push.
+
+
 ## Purpose
 
 - Analyze and perform tightly scoped operational engineering across CI/CD, containers, environments, runtime configuration, deployment, observability, rollback, and release operations.

package/skills/showdar-plan/SKILL.md

@@ -5,6 +5,11 @@ description: Use when agreed behavior needs a bounded implementation plan, chang
 
 # Showdar Plan
 
+## Mandatory Git preflight for task-owned writes
+
+Before any task-owned source/config/test/docs write, apply `showdar-git` branch policy: on develop/main/integration, inspect repository conventions and EXECUTE `showdar git-start --type <type> --name "<task>"` to prepare the task branch before editing. Then run `showdar guard --mutation local-write --json` and require `ok=true` and `data.allowed=true` before ANY file-writing tool. If blocked, STOP before editing. On an existing task branch run guard without creating a new branch. Recheck when a read-only stage turns into a write. If CLI is missing, manually prepare and verify safe Git branch state; do not silently write on develop/main. Explicit documented direct-work policy wins; never infer stash, reset, commit, merge, or push.
+
+
 ## Purpose
 
 - Turn an idea, bug requirement, migration, or design decision into executable engineering work.

package/skills/showdar-recover/SKILL.md

@@ -5,6 +5,11 @@ description: Use when interrupted or partial engineering work must be reconstruc
 
 # Showdar Recover
 
+## Mandatory Git preflight for task-owned writes
+
+Before any task-owned source/config/test/docs write, apply `showdar-git` branch policy: on develop/main/integration, inspect repository conventions and EXECUTE `showdar git-start --type <type> --name "<task>"` to prepare the task branch before editing. Then run `showdar guard --mutation local-write --json` and require `ok=true` and `data.allowed=true` before ANY file-writing tool. If blocked, STOP before editing. On an existing task branch run guard without creating a new branch. Recheck when a read-only stage turns into a write. If CLI is missing, manually prepare and verify safe Git branch state; do not silently write on develop/main. Explicit documented direct-work policy wins; never infer stash, reset, commit, merge, or push.
+
+
 ## Purpose
 
 - Recover context after session interruption, compaction, agent failure, crash, or handoff.

package/skills/showdar-release/SKILL.md

@@ -5,6 +5,11 @@ description: Use when preparing, validating, or executing a release lifecycle, a
 
 # Showdar Release
 
+## Mandatory Git preflight for task-owned writes
+
+Before any task-owned source/config/test/docs write, apply `showdar-git` branch policy: on develop/main/integration, inspect repository conventions and EXECUTE `showdar git-start --type <type> --name "<task>"` to prepare the task branch before editing. Then run `showdar guard --mutation local-write --json` and require `ok=true` and `data.allowed=true` before ANY file-writing tool. If blocked, STOP before editing. On an existing task branch run guard without creating a new branch. Recheck when a read-only stage turns into a write. If CLI is missing, manually prepare and verify safe Git branch state; do not silently write on develop/main. Explicit documented direct-work policy wins; never infer stash, reset, commit, merge, or push.
+
+
 ## Purpose
 
 - Prepare and execute a software release through existing primitive boundaries.

package/skills/showdar-requirements/SKILL.md

@@ -5,6 +5,11 @@ description: Use when product or business input needs explicit behavior, rules,
 
 # Showdar Requirements
 
+## Mandatory Git preflight for task-owned writes
+
+Before any task-owned source/config/test/docs write, apply `showdar-git` branch policy: on develop/main/integration, inspect repository conventions and EXECUTE `showdar git-start --type <type> --name "<task>"` to prepare the task branch before editing. Then run `showdar guard --mutation local-write --json` and require `ok=true` and `data.allowed=true` before ANY file-writing tool. If blocked, STOP before editing. On an existing task branch run guard without creating a new branch. Recheck when a read-only stage turns into a write. If CLI is missing, manually prepare and verify safe Git branch state; do not silently write on develop/main. Explicit documented direct-work policy wins; never infer stash, reset, commit, merge, or push.
+
+
 ## Purpose
 
 - Convert tickets, briefs, conversations, API notes, and observed repository behavior into implementation-ready requirements.

package/skills/showdar-test/SKILL.md

@@ -5,6 +5,11 @@ description: Use when choosing or implementing automated tests for behavior, reg
 
 # Showdar Test
 
+## Mandatory Git preflight for task-owned writes
+
+Before any task-owned source/config/test/docs write, apply `showdar-git` branch policy: on develop/main/integration, inspect repository conventions and EXECUTE `showdar git-start --type <type> --name "<task>"` to prepare the task branch before editing. Then run `showdar guard --mutation local-write --json` and require `ok=true` and `data.allowed=true` before ANY file-writing tool. If blocked, STOP before editing. On an existing task branch run guard without creating a new branch. Recheck when a read-only stage turns into a write. If CLI is missing, manually prepare and verify safe Git branch state; do not silently write on develop/main. Explicit documented direct-work policy wins; never infer stash, reset, commit, merge, or push.
+
+
 ## Purpose
 
 - Match test level to the boundary/risk being proven.

package/skills/showdar-upgrade/SKILL.md

@@ -5,6 +5,11 @@ description: Use when upgrading dependencies, frameworks, runtimes, or native pl
 
 # Showdar Upgrade
 
+## Mandatory Git preflight for task-owned writes
+
+Before any task-owned source/config/test/docs write, apply `showdar-git` branch policy: on develop/main/integration, inspect repository conventions and EXECUTE `showdar git-start --type <type> --name "<task>"` to prepare the task branch before editing. Then run `showdar guard --mutation local-write --json` and require `ok=true` and `data.allowed=true` before ANY file-writing tool. If blocked, STOP before editing. On an existing task branch run guard without creating a new branch. Recheck when a read-only stage turns into a write. If CLI is missing, manually prepare and verify safe Git branch state; do not silently write on develop/main. Explicit documented direct-work policy wins; never infer stash, reset, commit, merge, or push.
+
+
 ## Purpose
 
 - Make upgrades controlled engineering changes rather than version-number edits.

package/src/adapter-renderers.js

@@ -3,7 +3,7 @@ import { ALL_SKILLS } from './catalog.js';
 const RUNTIME_GUIDANCE = `Automatic Showdar selection: route the current request through \`showdar route --stdin --json\` when the Showdar CLI is available. Supply the prompt as literal stdin data, never as interpolated shell syntax. Honor the canonical lifecycle primary; do not substitute another installed skill when it is missing. Report missing skills and suggest \`showdar add <name>\`; never auto-install. Include installed domain matches only as specialized context overlays; load returned advisors only when installed. Domain discovery does not grant authority or replace the lifecycle route.
 Explicit named-skill requests may load that installed skill directly without automatic routing. Workflow skills remain native discoverable choices; the router does not select workflows. If the CLI is unavailable, use native skill discovery/static descriptions below. Do not fetch a CLI through npx or install dependencies automatically.
 Routing does not authorize mutation. Inspect the returned mutation class and current task authority before work. For local-write tasks, before the first task-owned source edit inspect Git state. On develop, development, dev, main, master or the repository default/integration branch, DO NOT begin source edits yet: prepare one branch per coherent task first. Follow repository instructions/documented convention, explicit current user instruction, clearly detected convention, then the Showdar safe default. Explicit trunk/direct-work policy wins.
-Use \`showdar git-start --dry-run --type <type> --name <task>\`, then \`showdar git-start --type <type> --name <task>\`, or equivalent repository-specific preparation. Confirm the task branch before mutating skill execution. Reuse that branch across plan/build/test/review; do not nest branches per skill. Dirty ownership or branch collisions require inspection; never infer stash, reset, restore or clean. Git-start does not authorize source mutation, commit, merge or push. Completion defaults to verify and report on the task branch; merge and push require their own explicit authority.`;
+Before ANY task-owned source/config/test/docs write, execute Git preflight even if the router selected build directly. On integration/default branches inspect repository policy and EXECUTE \`showdar git-start --type <type> --name <task>\` (not just --dry-run), or equivalent repository-safe branch preparation. Then EXECUTE \`showdar guard --mutation local-write --json\` and require ok=true AND data.allowed=true BEFORE invoking any file-writing tool. If blocked, STOP before editing. On a matching task branch run guard without creating a new branch. Recheck before each later mutating stage. Do not infer permission from \`showdar route\`. If the CLI is unavailable, manually inspect Git and confirm the appropriate task branch or documented direct-work policy; never silently write on develop/main. Dirty ownership/branch collisions require inspection; never infer stash/reset/restore/clean. Guard and git-start do not authorize source edits, commit, merge or push. Completion means verify and report.`;
 
 const CANONICAL_ROUTE_ORDER = [
   ['map repository architecture, dependencies, or impact', 'showdar-understand'],
@@ -76,7 +76,7 @@ export function renderCursorRuleBody(skillIds) {
   const body = renderShowdarInstruction(skillIds).trimEnd();
   return `---
 description: Showdar skill and workflow routing guidance for software-engineering tasks
-alwaysApply: false
+alwaysApply: true
 ---
 
 ${body}

package/src/git-guard.js

@@ -0,0 +1,62 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+function git(cwd, args, optional = false) {
+  try {
+    return execFileSync('git', ['--no-optional-locks', ...args], {
+      cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 10000,
+    }).trim();
+  } catch (error) {
+    if (optional && error.status === 1) return null;
+    throw new Error(`Git inspection failed (${args[0]}): ${error.stderr?.toString().trim() || error.message}`);
+  }
+}
+
+/**
+ * Read-only agent preflight. This reports whether a local-write task has
+ * branch isolation; it cannot intercept file writes made by other tools.
+ */
+export function guardMutation({ cwd, mutation }) {
+  if (!['read-only', 'local-write'].includes(mutation)) {
+    throw new Error('guard --mutation must be read-only or local-write.');
+  }
+  if (mutation === 'read-only') {
+    return { allowed: true, code: 'read-only', mutation, currentBranch: null, integrationBranch: null, directWork: false };
+  }
+
+  const root = git(cwd, ['rev-parse', '--show-toplevel']);
+  const currentBranch = git(root, ['symbolic-ref', '--quiet', '--short', 'HEAD'], true);
+  const config = key => git(root, ['config', '--local', '--get', key], true);
+  const directWork = config('showdar.gitDirectWork');
+  if (directWork !== null && !['true', 'false'].includes(directWork)) {
+    throw new Error('showdar.gitDirectWork must be true or false.');
+  }
+  const configuredBase = config('showdar.gitBase');
+  const defaultRef = git(root, ['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], true)?.replace(/^origin\//, '') ?? null;
+  const integrationNames = new Set(['develop', 'development', 'dev', 'main', 'master', configuredBase, defaultRef].filter(Boolean));
+  const context = {
+    mutation, currentBranch, integrationBranch: configuredBase ?? defaultRef,
+    directWork: directWork === 'true',
+  };
+
+  for (const marker of ['MERGE_HEAD', 'CHERRY_PICK_HEAD', 'REVERT_HEAD', 'rebase-merge', 'rebase-apply', 'BISECT_LOG', 'sequencer']) {
+    const location = git(root, ['rev-parse', '--git-path', marker]);
+    if (existsSync(path.resolve(root, location))) {
+      return { allowed: false, code: 'git-operation-active', ...context };
+    }
+  }
+  if (!currentBranch) return { allowed: false, code: 'detached-head', ...context };
+
+  const isIntegration = integrationNames.has(currentBranch);
+  const allowed = !isIntegration || directWork === 'true';
+  const code = !allowed ? 'task-branch-required'
+    : isIntegration ? 'direct-work-configured' : 'task-branch-ready';
+  return { allowed, code, ...context };
+}
+
+export function formatMutationGuard(data) {
+  return `${data.allowed ? 'ALLOWED' : 'BLOCKED'}: ${data.code}
+Mutation: ${data.mutation}
+Branch: ${data.currentBranch ?? '(detached or not inspected)'}${data.allowed ? '' : '\nPrepare a safe task branch with showdar git-start, then rerun guard. Do not write source while blocked.'}`;
+}

package/src/project.js

@@ -590,6 +590,32 @@ export async function addSkill({ cwd, skill, ai = null, scope = null, home = hom
   if (existingManifest?.skills?.includes(skillId)) {
     const refreshedFiles = [];
     const priorOwned = ownedPathSet(existingManifest);
+    const source = path.join(packageRoot, 'skills', skillId);
+    if (!(await exists(path.join(source, 'SKILL.md')))) throw new Error(`Packaged skill source missing: ${skillId}`);
+
+    // Refresh all still-managed native copies, not only generated instructions.
+    // Preflight every destination before changing any of them.
+    const roots = [...new Set((existingManifest.targets ?? [effectiveAi]).map(target =>
+      effectiveScope === 'global'
+        ? globalSkillRootFor(target, { homeRoot: home })
+        : skillRootFor(target, cwd)))];
+    const destinations = [];
+    for (const root of roots) {
+      const destination = path.join(root, skillId);
+      const relative = manifestPathFor(baseRoot, destination);
+      const recorded = (existingManifest.files ?? []).find(file => file.path === relative);
+      if (!recorded) continue; // A skill satisfied by global does not own a project copy.
+      await assertSafeManagedPath(baseRoot, destination);
+      if (!(await exists(destination))) throw new Error(`Managed skill missing; refusing partial refresh: ${relative}`);
+      if (await hashTree(destination) !== recorded.hash) {
+        throw new Error(`Modified Showdar-owned skill; refusing to overwrite user changes: ${relative}`);
+      }
+      destinations.push(destination);
+    }
+
+    for (const destination of destinations) {
+      await copyOwned({ baseRoot, source, destination, priorOwned, newFiles: refreshedFiles });
+    }
     for (const target of existingManifest.commandHarness ?? []) {
       const commandRoot = effectiveScope === 'global' ? globalCommandRootForTarget(target, { homeRoot: home }) : commandRootFor(target, cwd);
       if (commandRoot) await generateCommandFiles({ baseRoot, skillIds: existingManifest.skills, target, commandRoot, priorOwned, newFiles: refreshedFiles });
@@ -600,11 +626,10 @@ export async function addSkill({ cwd, skill, ai = null, scope = null, home = hom
       if (instruction.kind === 'block') await writeManagedBlock(file, existingManifest.skills);
       else if (instruction.kind === 'file') await writeCursorRule(file, existingManifest.skills);
     }
-    if (refreshedFiles.length) {
-      const files = new Map(existingManifest.files.map(f => [f.path, f]));
-      for (const f of refreshedFiles) files.set(f.path, f);
-      await writeJsonAtomic(effectiveScope === 'global' ? globalManifestPath(home) : path.join(cwd, PROJECT_MANIFEST), { ...existingManifest, files: [...files.values()] });
-    }
+    const files = new Map((existingManifest.files ?? []).map(f => [f.path, f]));
+    for (const f of refreshedFiles) files.set(f.path, f);
+    await writeJsonAtomic(effectiveScope === 'global' ? globalManifestPath(home) : path.join(cwd, PROJECT_MANIFEST),
+      { ...existingManifest, packageVersion, files: [...files.values()] });
     return { skill: skillId, root: '', destination: '', added: false, scope: effectiveScope, ai: effectiveAi, profile: existingManifest.profile };
   }
 

package/src/validate.js

@@ -455,8 +455,8 @@ export async function validateRepository(packageRoot) {
   if (!claudeBlock.includes('showdar-skills:start') || !claudeBlock.includes('showdar-skills:end')) {
     errors.push('CLAUDE managed block is missing markers');
   }
-  if (!cursorRule.includes('alwaysApply: false')) errors.push('Cursor rule must use Apply Intelligently metadata');
-  if (cursorRule.includes('alwaysApply: true')) errors.push('Cursor rule must not use alwaysApply:true');
+  if (!cursorRule.includes('alwaysApply: true')) errors.push('Cursor rule must always apply for Git pre-write safety guidance');
+  if (!cursorRule.includes('showdar guard --mutation local-write --json')) errors.push('Cursor rule must include Git pre-write guard');
 
   const commandDir = path.join(packageRoot, 'commands', 'opencode', 'showdar');
   if (await exists(commandDir)) {