obsidian-owl/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:

<!-- platform:claude-code -->

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

<!-- /platform --> <!-- platform:opencode -->

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

<!-- /platform -->

• 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.

Gap analysis (MEDIUM freedom):

• Load the coverage model from protocols/guardrails-patterns.md.
• Map detected tools against the ten enforcement dimensions. Detected tool for a dimension → covered. No tool → gap. Gaps become recommendations.
• Present the gap analysis summary to the user before recommending.

Recommendation (HIGH freedom):

• Organize recommendations by enforcement layer. Load hook patterns from protocols/guardrails-patterns.md.
• Each layer is independently approvable. User chooses which layers to configure.
• For commit hooks: present applicable frameworks with trade-offs. User always chooses — never auto-select.
• Read existing hooks first, show diff, merge (don't overwrite), detect duplicates.
• Delegate to specwright-researcher for unfamiliar stacks. If tools conflict, present trade-offs.

Configuration (LOW freedom):

• External file writes: diff-show-approve. Installation commands require explicit approval.
• Update {projectArtifactsRoot}/config.json with detected tool commands when the tracked project-artifact root exists.
• When present, update git.runtime.mode / git.runtime.projectVisibleRoot in config separately from tracked work-artifact publication.
• When present, update the approved work-artifact publication choice in config separately from clone-local runtime state and separately from tracked work-artifact publication. Follow protocols/context.md for config updates.
• Preserve the root split: tracked project policy stays under {projectArtifactsRoot}, while Git-admin session state remains local-only under the runtime roots.
• Never modify CONSTITUTION.md (sw-learn's responsibility).

Headless (LOW freedom):

• Follow protocols/headless.md for non-interactive detection and default policies.
• When headless: apply all layers using detected tools with conservative defaults.
• Write headless result file on ALL exit paths including abort.

Protocol References

• protocols/guardrails-detection.md -- three-step stack and guardrail detection
• protocols/guardrails-patterns.md -- coverage model, enforcement patterns, framework options
• protocols/context.md -- config.json format and loading
• protocols/headless.md -- non-interactive execution detection and defaults
• protocols/delegation.md -- agent delegation for researcher

Failure Modes

| Condition | Action | |-----------|--------| | No dependency manifest found | Ask user about language/framework directly | | Detected tool fails --version check | Warn user, skip that tool, ask for correct command | | Install command fails | Show error, let user retry or skip | | Detected tools conflict | Present trade-offs, let user choose | | Unsupported CI platform | Warn, skip CI/CD layer | | Compaction during config | Read config.json and external files, resume next missing item |