sw-guard

Specwright Guard

Goal

Detect the project's stack and interactively configure deterministic guardrails across four enforcement layers (session, commit, push, CI/CD). Each layer is independently approvable. Existing guardrails are preserved during re-runs.

Inputs

• The codebase (dependency manifests, config files, existing hooks)
• {projectArtifactsRoot}/config.json -- project configuration (optional -- not required)
• {projectArtifactsRoot}/CONSTITUTION.md -- practices to follow (if present)
• Existing agent hooks, git hooks, CI workflows

Outputs

When complete, user-approved guardrails are configured. Artifacts may include:

• .claude/settings.json or .claude/settings.local.json -- session-level hooks. User chooses destination (shareable vs gitignored).

• .opencode/plugins/*.ts -- session-level plugin hooks.

• Pre-commit hook configurations (framework chosen by user)
• Pre-push hook configurations (test runner, coverage thresholds)
• CI/CD workflow files (backstop checks, integration tests, security scanning)
• {projectArtifactsRoot}/config.json -- updated with detected tool commands (if present)

Note: CONSTITUTION.md is NOT modified. Constitutional updates are the responsibility of sw-learn.

Constraints

Detection (MEDIUM freedom):

• Follow protocols/guardrails-detection.md for the three-step detection algorithm (manifest scan, config file scan, existing guardrail scan).
• Detection scope includes traditional tools (linters, formatters, test runners) and semantic analysis tools: ast-grep (sg), OpenGrep (opengrep), and platform LSP (Claude Code .lsp.json, Opencode built-in, cli-lsp-client standalone).
• If {projectArtifactsRoot}/config.json exists, read commands.* fields as authoritative; supplement with detection for unconfigured dimensions.
• If {projectArtifactsRoot}/config.json does not exist, rely entirely on detection. Validate detected tools by running them (e.g., --version check). Present standalone recommendations with explicit "detected via heuristics" labeling.
• When Git workflow config is present or inferred, seed or migrate git.targets and git.freshness from the detected Git workflow strategy without requiring users to define a custom branch DSL.
• Detect or confirm target-role defaults, freshness checkpoints, runtime mode as an explicit Git policy choice, and any optional work-artifact publication mode as one explicit Git policy surface.
• Recommend project-visible for Claude-oriented installs unless the user explicitly wants git-admin runtime roots.
• Recommend a tracked work-artifact root under .specwright/works for new interactive installs unless the user explicitly prefers clone-local-only auditable work artifacts.
• When describing runtime policy, use the same operator vocabulary as the adapters and status surfaces: project-visible roots under .specwright-local/ for interactive installs, git-admin roots under .git/specwright/ for compatibility, /sw-status for the current runtime view, and /sw-adopt for explicit same-work adoption.
• Keep runtime mode separately from tracked work-artifact publication and separately from clone-local runtime state.
• Treat .specwright/config.json and the anchor docs as a shared project-level policy surface across developers and agent sessions, not as clone-local runtime state.
• For unfamiliar stacks or niche tools, use WebSearch to identify tooling conventions.
• Detect existing guardrails before recommending. Show delta on re-runs.