pdlc-os/skills/safety-guardrails

Safety Guardrails — Reference

When this skill activates

This skill is the canonical reference for PDLC's safety model. It is consulted by:

• The PreToolUse guardrails hook (hooks/pdlc-guardrails.js) on every Bash, Edit, and Write tool call.
• The /override command, when a user wants to bypass the deploy-before-Operation block.
• Every other PDLC skill, when surfacing intent before a potentially-dangerous action (see "Agent norms" below).

When in doubt about what the guardrails hook will do — check this document first.

---

What the hook enforces

There are exactly two enforced rules.

1. Deploy gated to Operation phase (hard block, overridable)

A Bash command that matches a known deploy pattern is blocked when docs/pdlc/memory/STATE.md says the project's current phase is anything other than Operation.

Trigger patterns: fly deploy, vercel deploy, npm run deploy, yarn deploy, pnpm deploy, heroku ... deploy, aws ... deploy, gcloud ... deploy, docker ... push, kubectl apply, terraform apply, pulumi up, cdk deploy, eb deploy, sam deploy, serverless deploy.

Block message: the user sees a red banner naming the blocked command and the override path.

Bypass: run /override "<the blocked command>". The override prompts for a single confirmation, executes the command, and records the bypass to docs/pdlc/memory/DECISIONS.md as a new ADR.

Fallback: if STATE.md is missing or doesn't contain a ## Current Phase block, the hook gives benefit of the doubt and allows the command. This avoids breaking fresh repos that haven't run /setup yet.

Why this rule exists: PDLC's Ship flow runs smoke tests, UX Verify, security checks, and writes deployment provenance to DEPLOYMENTS.md and the episode file. A direct fly deploy from the terminal skips all of that. The block nudges the user toward /ship while leaving an explicit escape hatch for emergencies.

2. Memory-file write logging (passive, never blocks)

Any direct Edit, Write, or Bash-redirection (sed / awk / tee / mv / cp / cat / > / >>) targeting a file under docs/pdlc/memory/ whose basename is one of:

• CONSTITUTION.md
• DECISIONS.md
• STATE.md
• ROADMAP.md
• INTENT.md
• OVERVIEW.md
• CHANGELOG.md

…emits a passive log line of the form:

⚠️ Logged: <ToolName> on PDLC memory file <basename>

The action proceeds normally — there is no halt, no confirmation prompt, no override required. The log surfaces in the tool-call transcript so /diagnose can reconcile unexpected drift later.

Scoped to memory path: the rule only fires when the file path contains docs/pdlc/memory/. Files merely named CONSTITUTION.md elsewhere on disk (test fixtures, unrelated user notes) are not flagged.

---

Cross-cutting machinery

Non-PDLC project early-exit

The hook checks for <cwd>/docs/pdlc/memory/ at startup. If it doesn't exist, the hook returns allow immediately. Sessions in non-PDLC projects pay roughly 1ms per tool call and receive no enforcement.

Metadata-command short-circuit

The deploy-pattern regex would false-positive on a git commit -m "added gcloud deploy step to docs" or a gh release create --notes "...terraform apply..." — the commit body legitimately describes a deploy without executing it. To avoid this, the following outer commands short-circuit the deploy check:

• git commit
• git tag -m / git tag -a
• gh release ... / gh pr ... / gh issue ...
• gh api ...

The memory-file logging rule is not short-circuited — these commands legitimately mention memory file names in commit bodies, but they don't write to those files via the bash command itself, so the file-write regex won't match.

Night-shift bypass

When docs/pdlc/memory/pdlc-night-shift.json has active: true, the deploy-gate hard block is downgraded to a passive log:

⚠️ [night-shift bypass] Deploy command would normally be blocked outside Operation phase — action allowed: <command>

The action proceeds. Production deploys are still blocked by the three-layer ban in hooks/pdlc-night-shift.js — that ban does not route through this guardrails hook.

Why the bypass exists: the deploy block normally prompts for /override, which requires a human at the keyboard. In /night-shift mode there is no human; halting the hook would turn a safety mechanism into a hang. Runtime safety is enforced by three independent layers, not by this hook:

1. Driver-agent discipline. Pulse, Neo, Atlas, and the rest of the team don't initiate destructive operations as part of any normal Build/Ship/Verify flow. The autonomous loop sticks to feature branches, merge commits, and per-contract deploy targets.
2. Contract abort_conditions. The Completion Contract drafted at Step ② enumerates abort triggers the run owns: Phantom Critical security findings, P0 UX findings from Ship Verify Step 11.5, smoke-test failures, merge conflicts, stagnation, wall-clock/token caps. These are detected by the driver and the evaluator.
3. Three-layer production-deploy ban. Production deployment is blocked at contract-target selection (Contract Party Step 2.6), at activate-time validation (Step 3.0), and at runtime in hooks/pdlc-night-shift.js. None of that flow routes through the PreToolUse guardrails.

---

Agent norms (not hook-enforced)

Every PDLC agent (Pulse, Neo, Atlas, Phantom, Echo, Bolt, Muse, Jarvis, Sentinel) should pause and surface intent before taking any of the following actions. These are not blocked by the guardrails hook. Claude Code's native permission system prompts on most of them in default mode. In bypassPermissions mode (superclaude, /night-shift), agents are expected to exercise judgment.

• Force-pushing to main or master
• rm -rf outside the project directory, or anywhere with files not on the current branch
• git reset --hard on a branch with un-pushed work
• DROP TABLE or any destructive DDL without a migration file already committed
• Production database migrations or schema changes
• Hardcoded secrets or credentials in source
• Shipping with critical dependency vulnerabilities (from npm audit or equivalent)
• Shipping with P0 UX findings from Ship Verify Step 11.5 (verbatim ban-list copy, keyboard-broken interactives where the design committed to focus, accessibility regressions vs the as-built scorecard)
• External API calls that write/post/send: curl POST/PUT/PATCH/DELETE to external URLs — Slack webhooks, email APIs, payment processors, third-party services
• Closing all open Beads tasks in a single operation
• Deleting files not created on the current branch

"Surface intent" means: print one line stating what you're about to do, then proceed. In bypassPermissions mode this is the only check standing between the action and execution, so the line matters — make it specific. ("About to force-push origin/main to overwrite the merge conflict at commit abc123" beats "force-pushing now.")

---

Override Protocol

The /override command (alias for /override) bypasses the deploy gate. It is the only hook-enforced rule that has an override path.

The protocol is in skills/override/SKILL.md. Summary:

1. The user invokes /override "<the blocked command>".
2. The skill displays the command in red along with the reason it was blocked.
3. A single confirmation is required (single-confirm because there is only one rule to override — see CLAUDE.md commit history for the rationale).
4. On confirmation, the skill records a new ADR in DECISIONS.md and executes the command.
5. On cancellation, the skill exits without executing.

The override is permanently logged in DECISIONS.md. It cannot be hidden, deleted, or batch-confirmed.

---

Rules

• The deploy gate is determined by the command pattern and the STATE.md phase, not by context or intent. A fly deploy from a Construction-phase project is blocked even if the user says "it's fine."
• The override cannot be scripted, pre-approved, or batch-confirmed. Each instance requires its own confirmation.
• Memory-file write logging always logs, even when the write is benign (e.g. /decide writing to DECISIONS.md). The log is descriptive, not punitive.
• All deploy-gate overrides are logged in DECISIONS.md. Memory-file writes are logged transiently in the tool-call transcript; /diagnose reconciles them against expected PDLC command activity.
• If the hook can't parse STATE.md (corrupt, malformed, missing ## Current Phase header), it defaults to "Operation" — benefit of the doubt. The trade-off: fresh / broken repos don't break, at the cost of a missed block in a corrupt-state edge case.
• The guardrail system does not override human authority — it enforces deliberate decision-making for one specific risk class (deploys outside the proper flow). The human can always authorize the action via /override.
• Under /night-shift, the deploy gate does not block — see the Night-shift bypass section above. Every bypassed event is logged with [night-shift bypass] so the morning audit can see what fired.

---

Why the framework is this small

PDLC v2.x originally enforced a three-tier system (hard block / pause-and-confirm / logged warning) covering force-push, rm -rf, git reset --hard, prod DB writes, external API write calls, DROP TABLE, and protected-file edits. The trim that produced the current model removed everything Claude Code's native permission system already handles, leaving only the rules that encode genuinely-PDLC-specific semantics (phase-gated deploys, memory-file drift detection).

The agent-norms list above is the replacement for the dropped hook rules: same coverage, enforced by agent discipline + Claude Code permissions rather than a regex hook. This avoids false-positives on commit messages, test fixtures, and non-PDLC sessions, and keeps the hook small enough to read in one sitting.