@deftai/directive-content 0.55.0

package/coding/security.md

@@ -0,0 +1,158 @@
+<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
+<!-- Purpose: rendered coding rules -->
+<!-- Source of truth: packs/rules/rules-pack-0.1.json -->
+<!-- Regenerate with: task packs:render -->
+<!-- Edit the source, not this file. Slice instead of loading every coding doc: task packs:slice rules by-tier --tier <TIER> (or by-domain, list) -->
+
+# Security Standards
+
+Baseline security requirements that apply to every project Deft creates or maintains. This is a baseline standards file, not a comprehensive security audit guide — see project-specific threat models for deeper coverage.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+## Universal Requirements
+
+- ! Validate all inputs at trust boundaries; reject malformed input, do not silently sanitize
+- ! Treat all data from outside the trust boundary (users, network, files, agents, tools) as adversarial until validated
+- ! Run dependency vulnerability scans on introduction AND on a recurring cadence (weekly minimum)
+- ! Keep secrets out of source, logs, error messages, and build artifacts (see [coding.md `Secrets`](coding.md#code-organization))
+- ⊗ Roll custom cryptography, authentication, or session handling — use vetted libraries
+- ⊗ Disable security checks "temporarily" without an issue tracking re-enablement
+
+## Input Validation & Injection Prevention
+
+- ! Validate type, length, range, and format at every API boundary
+- ! Use parameterized queries / prepared statements for ALL database access
+- ! Apply context-appropriate output encoding (HTML, URL, JSON, shell, SQL) at the point of use, not at storage
+- ! Reject untrusted input outright when it fails validation; do not coerce or "fix" it
+- ! Use safe deserialization (JSON over pickle/yaml-load; allow-lists for polymorphic types)
+- ⊗ String interpolation in SQL, shell, or command construction
+- ⊗ `eval`, `exec`, `subprocess(shell=True)`, or equivalent on untrusted input
+- ⊗ Trust client-side validation as the sole defence — re-validate server-side
+
+## Authentication & Authorization
+
+- ! Use established auth libraries / identity providers (OAuth2/OIDC, Passport, Authlib, etc.)
+- ! Enforce authorization at the API / service layer, never only in the UI
+- ! Use short-lived access tokens; rotate refresh tokens; revoke server-side on logout / compromise
+- ! Hash passwords with a memory-hard algorithm (argon2id, bcrypt, scrypt) — never plain SHA / MD5
+- ! Enforce MFA for administrative / production access paths
+- ⊗ Roll custom session, password, or token handling
+- ⊗ Hard-code credentials, API keys, or tokens in source — see Secrets Management below
+- ⊗ Log credentials, full tokens, or session cookies
+
+## Secrets Management
+
+Extends and reinforces [coding.md Secrets rule](coding.md#code-organization). Projects that include any AI agent process MUST also apply the tightened `## No-Read-Secret Rule for Agent Systems (#587)` section below -- the `.env`-files-as-default pattern that is compliant for traditional services is NOT compliant when an agent can read the filesystem.
+
+- ! Store ALL secrets in `secrets/` as `.env` files (or a dedicated secret manager), gitignored
+- ! Read secrets via environment variables / vault clients at runtime
+- ! Rotate secrets on a documented cadence and on any suspected compromise
+- ! Redact tokens, passwords, and PII before logging or surfacing in error messages
+- ⊗ Secrets in code, config committed to VCS, CI logs, or chat transcripts
+- ⊗ Print, `echo`, or interpolate secrets into shell strings; pass via env or `--*-file` flags instead
+- ⊗ Log full credentials, refresh tokens, or PII
+
+## Dependency Security
+
+- ! Pin direct dependency versions in lock files (`uv.lock`, `package-lock.json`, `go.sum`, `Cargo.lock`)
+- ! Audit dependencies on introduction with the language-native scanner:
+  - Python: `pip-audit` (or `uv pip audit`)
+  - Node: `npm audit` / `pnpm audit`
+  - Go: `govulncheck`
+  - Rust: `cargo audit`
+- ! Enable Dependabot (or equivalent) for weekly version + security PRs
+- ! Resolve CRITICAL / HIGH advisories before merge; document deferral with a tracked issue
+- ~ Run `osv-scanner scan source --recursive .` periodically across mixed-language repos
+- ⊗ Disable lockfile checks to "speed up" CI
+- ⊗ Pin to floating refs (`main`, `latest`, `@v1`) for third-party GitHub Actions — pin to a full SHA
+
+## Agent-Specific Threats
+
+Directive builds AI agent frameworks; agents introduce a distinct threat surface beyond classic web security.
+
+- ! Treat ALL user-provided content (chat, files, tool outputs, web fetches) as potentially adversarial — assume prompt injection
+- ! Isolate tool outputs from the trust boundary: never expose raw internal file contents, environment variables, or system prompts to untrusted input channels
+- ! Gate destructive tool calls (file deletion, repo deletion, force-push, admin merge, billing changes) behind explicit user consent OR a deterministic preflight check
+- ! Bound agent autonomy: declare per-tool allow / deny lists; do not grant blanket shell or network access by default
+- ! Log every tool invocation with arguments redacted for secrets so post-incident review is possible
+- ⊗ Reflect retrieved web content, repo issue bodies, or third-party comments directly back into a privileged tool-call argument without sanitization
+- ⊗ Expose internal system prompts, hidden tool definitions, or other agents' messages to an untrusted input surface
+- ⊗ Run model-suggested shell commands without a deterministic safety classifier (see `scripts/preflight_gh.py` for the canonical pattern)
+
+## Tooling
+
+- ~ Static analysis: language-native linter with security rules enabled (ruff S-rules, golangci-lint gosec, eslint security plugin)
+- ~ Secret scanners: `gitleaks` on pre-commit and CI
+- ~ SAST: CodeQL default setup for hosted repos
+- ~ Container scanning: `trivy fs` or `trivy image` for any Dockerfile / OCI artifact
+- ~ Dependency review: GitHub Dependency Review action on PRs
+
+## Reporting Vulnerabilities
+
+- ! Every project MUST document a vulnerability reporting path (GitHub Security Advisories, `SECURITY.md`, or equivalent)
+- ! Acknowledge reports within a documented SLA; never silently close
+- ⊗ Discuss unfixed vulnerabilities in public issues / PRs
+
+## No-Read-Secret Rule for Agent Systems (#587)
+
+When AI agents are part of the system, every filesystem-accessible secret is one a prompt-injection attack could exfiltrate to an external inference server. The `.env`-on-disk pattern that is fine for traditional services becomes a structural security hole the moment a non-deterministic reader is in the loop -- the standard `dotenv` flow makes secrets part of the agent's context by construction.
+
+- ! When the project includes any AI agent process, store secrets in a dedicated secret manager (cloud KMS / Vault / 1Password / Infisical Agent Vault) -- not in `.env` files on disk
+- ! Inject secrets at process start into the agent's environment (or, preferred, deliver them via a credential proxy so the agent never reads the underlying value); fetch from the secret store at runtime, do not bake into images
+- ! Scope each credential to the agent identity that uses it -- one scoped credential per agent or per deployment, auditable separately
+- ~ For production agent systems, prefer the agent credential proxy pattern: a TLS-intercepting forward proxy (or sidecar) attaches credentials to outbound requests so the agent completes its work without ever reading the plaintext secret
+- ⊗ Commit `.env` files in projects where any agent process can read the filesystem -- the agent's context (and any external inference server it calls) inherits everything the agent can read
+- ⊗ Share one API key across multiple agents -- per-identity scoping is what makes the audit log usable when a key is compromised
+
+Cross-references: [coding.md `Secrets`](coding.md#code-organization) (this rule extends the existing Secrets rule for agent contexts) | `Secrets Management` section above | the in-flight `patterns/executor-layer-credentials.md` credential-proxy pattern (Wave 2, tracked at [#806](https://github.com/deftai/directive/issues/806); not yet on master) | Infisical Agent Vault <https://github.com/Infisical/agent-vault> (reference implementation).
+
+## Tool-Call Safety Is Independent of Text-Level Safety (#686)
+
+Text-level safety alignment does not transfer to the tool-call boundary. An agent whose text outputs satisfy safety constraints can still execute harmful tool calls -- empirically demonstrated in the Agent Behavioral Contracts literature (Cartagena & Teixeira 2026). A safety-aligned model is NOT safe at the tool boundary unless the tool boundary enforces it separately.
+
+- ! Enforce hard constraints on high-impact tools at the call site -- middleware, gateway, or contract layer -- separate from the model's text-level safety training
+- ! Declare an explicit constraint tier for every tool in the tool registry: `read-only`, `reversible`, `irreversible`, or `destructive`. Tools without a declared tier MUST be treated as `destructive` by default
+- ! Audit-log every tool invocation at the tool-call layer (tool name, arguments redacted for secrets, caller identity, outcome). Text-level logs of the model's reasoning are insufficient for post-incident review
+- ! For `irreversible` / `destructive` tools, gate execution with a deterministic preflight (allow-list, environment check, ack token) outside the model -- never let the model decide on its own that an operation is safe
+- ⊗ Rely on model-level safety training as the only barrier between an agent and a destructive tool call -- text alignment provides no guarantee at the tool boundary
+- ⊗ Ship a tool registry where any tool is missing a constraint-tier declaration -- the default-to-`destructive` fallback exists for staging, not production
+
+Cross-references: `Agent-Specific Threats` section above | the in-flight `patterns/executor-layer-credentials.md` tool-call gateway pattern (Wave 2, tracked at [#806](https://github.com/deftai/directive/issues/806); not yet on master) | [`scripts/preflight_gh.py`](../../scripts/preflight_gh.py) (#1019 reference implementation of a per-tool deterministic safety classifier) | Cartagena & Teixeira 2026 <https://arxiv.org/abs/2602.22302>.
+
+## Destructive-Op Guardrails -- Environment Isolation + Irreversibility (#708)
+
+The April 2026 PocketOS / Railway incident -- a Cursor/Claude agent deleted a production database AND its backups in roughly nine seconds after being told to "clean up the staging DB" -- is the canonical recurrence record for two distinct gaps: acting on a prompt-claimed environment instead of a verified one, and treating "destructive" as excluding backups. The two gates below close those gaps; the incident is documented at [`incidents/2026-04-pocketos-railway-prod-db-wipe.md`](../../incidents/2026-04-pocketos-railway-prod-db-wipe.md).
+
+### Environment Isolation Gate
+
+- ! Before any write or destructive operation, the agent MUST positively identify the target environment (prod / staging / dev) from a TRUSTED, NON-PROMPT signal -- env var (e.g. `APP_ENV`), config file, or connection-string introspection. The user's wording is NOT a trusted signal
+- ! Enumerate the prod-detection heuristics explicitly in the project's runbook: hostname or connection-string contains `prod` / `production`, matches the documented prod hostname(s), or resolves into a documented prod-VPC CIDR. A trusted signal that disagrees with the prompt always wins
+- ! If the environment cannot be verified from a trusted signal, the agent MUST refuse the operation and escalate to a human. "Probably staging" is a refusal, not an approval
+- ⊗ Trust the user's wording (e.g. "clean up the staging DB") as environment authorisation -- the prompt is the untrusted input, the env var / connection string is the trusted signal
+- ⊗ Heuristically downgrade an unverified environment to "non-prod" so the operation can proceed -- the gate fails closed
+
+### Irreversibility Gate
+
+- ! Destructive operations -- DB `DROP` / `TRUNCATE` / `DELETE` without `WHERE`, `rm -rf`, force-push to a shared branch, table rename over an existing target, AND any mutation of a backup -- require BOTH a tested rollback path AND an explicit in-session human ack token before execution
+- ! Backups are first-class state. Deleting, overwriting, truncating, or "rotating" a backup is itself a destructive operation and MUST go through this gate
+- ! A verified non-prod environment (Environment Isolation Gate passed with `env != prod`) MAY relax the human-ack requirement but does NOT remove the rollback-path requirement -- a dev DB without a rollback is still a footgun
+- ~ Declare the irreversibility-tier classification for the project's destructive verbs in the in-flight `conventions/verb-classification.json` (tracked at [#1095](https://github.com/deftai/directive/issues/1095) closed-verb scope-expansion gate; not yet on master). Inline declaration in the operation's runbook is acceptable until that file lands
+- ⊗ Execute a destructive operation in a verified prod environment without an in-session human ack token -- "the user authorised the project" is not session-scoped consent
+- ⊗ Treat a backup as out-of-scope for the irreversibility gate -- the PocketOS incident is the recurrence record; backups were destroyed in the same nine-second window as the live database
+
+Cross-references: [`incidents/README.md`](../incidents/README.md) (incidents library format) | [`incidents/2026-04-pocketos-railway-prod-db-wipe.md`](../../incidents/2026-04-pocketos-railway-prod-db-wipe.md) (seed entry) | `Agent-Specific Threats` section above (this section extends it) | [`scripts/preflight_gh.py`](../../scripts/preflight_gh.py) (#1019 deterministic-classifier reference) | #1095 closed-verb scope-expansion gate (consumes the irreversibility-tier classification).
+
+## Anti-Patterns
+
+- ⊗ "We'll add security later" — baseline standards apply from day one
+- ⊗ Silent sanitization that masks malformed input rather than rejecting it
+- ⊗ Disabling lockfile / signature / scanner checks to ship faster
+- ⊗ Trusting agent / model output as if it were validated user input
+- ⊗ Logging entire request bodies or environment dumps in production
+- ⊗ Granting agents blanket network or shell access without per-tool allow-lists
+- ⊗ Reflecting third-party content (issue bodies, web pages, tool outputs) into privileged tool calls unsanitized
+
+---
+
+**See also**: [coding.md](coding.md) (general coding standards, Secrets rule) | [testing.md](testing.md) (Security Tests section) | [hygiene.md](hygiene.md) (error-hiding anti-patterns) | [../scm/github.md](../scm/github.md) (destructive `gh` verbs preflight gate #1019) | [../incidents/README.md](../incidents/README.md) (incidents library, #708)

package/coding/testing.md

@@ -0,0 +1,162 @@
+<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
+<!-- Purpose: rendered coding rules -->
+<!-- Source of truth: packs/rules/rules-pack-0.1.json -->
+<!-- Regenerate with: task packs:render -->
+<!-- Edit the source, not this file. Slice instead of loading every coding doc: task packs:slice rules by-tier --tier <TIER> (or by-domain, list) -->
+
+# Testing Standards
+
+Universal testing requirements across all languages and interfaces.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+## Universal Requirements
+
+- ! Achieve ≥85% coverage (overall + per-module/package/file)
+- ! Include ≥50 fuzzing tests per input point
+- ~ Have integration tests for critical paths/workflows
+- ! Exclude entry points and main functions from coverage
+- ! Test all code paths: normal, edge cases, error conditions
+- ! Run `task check` (or equivalent) before commit
+- ⊗ say a (todo-list|plan|phase|project) is done if relevant tests have not been written, run, and PASSED.
+- ⊗ assume its ok for a test to fail in any situation
+
+## Test-First Development
+
+- ! Implementation is INCOMPLETE until tests written AND `task test:coverage` passes
+- ! New functions/classes MUST have corresponding tests in same commit
+- ! Modified functions MUST update existing tests to maintain coverage
+- ! Run `task test:coverage` after ANY code change to verify ≥85% maintained
+- ! If coverage drops below threshold, implementation is INCOMPLETE
+- ~ Write tests for edge cases, not just happy paths
+- ⊗ Skip test updates when modifying existing functions
+- ⊗ Implement code without tests
+- ⊗ Claim "done" before running test:coverage
+
+## Coverage
+
+**What to count:**
+
+- ! All source code in src/, internal/, pkg/, lib/
+
+**What to exclude:**
+
+- ! Entry points: main(), **main**, index.ts (if trivial)
+- ! Generated code
+- ! Third-party code
+- ! Test files themselves
+
+**Thresholds:**
+
+- ! ≥85% lines
+- ! ≥85% functions/methods
+- ! ≥85% branches
+- ! ≥85% statements
+
+## Test Types
+
+### Unit Tests
+
+- ! Individual functions/methods/components
+- ! Normal cases + edge cases + error conditions
+- ! Fast execution (milliseconds)
+- ! No external dependencies (use mocks/stubs)
+
+### Integration Tests
+
+- ~ Full workflows with real dependencies
+- ~ Realistic scenarios
+- ~ Database, API, file system interactions
+- ~ Slower execution acceptable
+
+### Fuzzing Tests
+
+- ! ≥50 fuzzing tests per input point
+- ! Random/malformed inputs
+- ! Catch unexpected crashes, hangs, exceptions
+
+### Load/Performance Tests
+
+- ~ For performance-critical code
+- ~ Measure response times under load
+- Tools: JMeter, Gatling, k6, Apache Bench
+
+### Security Tests
+
+- ! For code handling untrusted input
+- ! SQL injection, XSS, auth bypass, path traversal
+- Tools: OWASP ZAP, Burp Suite, SQLMap
+
+### Snapshot Tests
+
+- ~ For CLI output, rendered UI, generated files
+- ~ Detect unintended output changes
+
+### Build Output Tests
+
+- ~ Build scripts that produce `dist/` artifacts have a smoke test verifying expected output files exist and contain expected content
+- ! Non-compiled assets (manifests, configs, extension metadata) that bundlers don't track are explicitly verified post-build
+- ~ Verify file presence, non-empty size, and structural validity (e.g. required JSON keys present)
+- ! A build that exits 0 but produces stale or incomplete artifacts is a silent failure — treat it as a build failure (#105)
+
+## Language-Specific Details
+
+**Python**: [../languages/python.md](../languages/python.md#testing) - pytest, pytest-cov, pytest-mock
+**Go**: [../languages/go.md](../languages/go.md#testing) - Testify, table-driven tests
+**C++**: [../languages/cpp.md](../languages/cpp.md#testing) - Catch2/GoogleTest, GoogleMock
+**TypeScript**: [../languages/typescript.md](../languages/typescript.md#testing) - Vitest/Jest, React Testing Library
+**CLI**: [../interfaces/cli.md](../interfaces/cli.md#testing) - CliRunner, format validation
+**REST APIs**: [../interfaces/rest.md](../interfaces/rest.md#testing) - endpoint testing, security testing
+
+## Test Organization
+
+**File naming:**
+
+- Python: `test_*.py` or `*_test.py`
+- Go: `*_test.go`
+- C++: `test_*.cpp` or `*_test.cpp`
+- TypeScript: `*.spec.ts` or `*.test.ts`
+
+**Directory structure:**
+
+```
+project/
+├── src/           # Source code
+├── tests/         # Test files
+│   ├── unit/      # Unit tests
+│   └── integration/  # Integration tests (optional separation)
+```
+
+## Best Practices
+
+- ! Write tests before or alongside code (TDD encouraged)
+- ! One assertion per test (or logically grouped assertions)
+- ~ Use descriptive test names: `test_user_login_with_invalid_password`
+- ! Arrange-Act-Assert (AAA) pattern
+- ! Test behavior, not implementation
+- ≉ Rely on test execution order
+- ! Clean up resources (files, DB, connections) in teardown
+
+## Anti-patterns
+
+- ⊗ Skip tests to meet deadlines
+- ⊗ Test only happy paths (edge cases critical)
+- ⊗ Mock everything (integration tests needed too)
+- ⊗ Ignore flaky tests (fix or remove them)
+- ⊗ Commit failing tests
+- ⊗ Write tests that depend on external state
+- ⊗ Hard-code dates, times, random values
+- ⊗ Implementing code without tests
+- ⊗ Claiming "done" before running test:coverage
+- ⊗ Ignoring coverage drops
+
+## CI/CD Integration
+
+- ! Tests run automatically on every commit/PR
+- ! Block merges if tests fail
+- ! Block merges if coverage drops below threshold
+- ~ Test in multiple environments (OS, versions)
+
+---
+
+**See also**: [main.md](../../main.md) | Language-specific testing in python.md, go.md, cpp.md, typescript.md

package/coding/toolchain.md

@@ -0,0 +1,44 @@
+<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
+<!-- Purpose: rendered coding rules -->
+<!-- Source of truth: packs/rules/rules-pack-0.1.json -->
+<!-- Regenerate with: task packs:render -->
+<!-- Edit the source, not this file. Slice instead of loading every coding doc: task packs:slice rules by-tier --tier <TIER> (or by-domain, list) -->
+
+# Toolchain Validation
+
+Rules for verifying that required tools are installed and functional before beginning implementation.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**:
+- [coding.md](coding.md) — Build Automation section
+- [build-output.md](build-output.md) — post-build artifact validation
+
+## Pre-Implementation Gate
+
+- ! Before beginning implementation, verify all required toolchain components are installed and functional
+- ! Required components vary by project — at minimum verify: task runner, language compiler/runtime, and platform SDK if applicable
+- ! If any required tool is missing or non-functional, stop and report — do not proceed with implementation
+- ⊗ Assume a tool is available because it was present in a previous session or referenced in the spec
+- ⊗ Proceed with implementation when the build or test toolchain is unavailable
+
+## What to Verify
+
+- ! Task runner: `task --version` (required for quality gates)
+- ! Language runtime/compiler: e.g. `go version`, `python --version`, `node --version`, `swift --version`
+- ! Platform SDK (if applicable): e.g. `xcode-select -p` for iOS/macOS, Android SDK path for Android
+- ! Project-specific tools listed in PROJECT.md or SPECIFICATION.md
+
+## On Missing Tools
+
+- ! Report exactly which tools are missing and provide install guidance
+- ! Do not partially implement using available tools while skipping quality gates
+- ~ Offer to help install missing tools if the user consents
+## uv Project Pinning (#1011)
+**Why this rule exists:** without an explicit pin, `uv run` walks upward from cwd looking for the nearest `pyproject.toml` and binds to whatever it finds first. When a deft consumer's repo root has no `pyproject.toml` of its own (the common case for non-Python projects), uv escapes the framework directory and resolves to an ancestor workspace `pyproject.toml`. That ancestor's build backend (frequently unresolvable in the consumer environment) crashes during environment resolution before any framework task body runs. The root-cause analysis lives in `vbrief/active/2026-05-11-1011-*.vbrief.json`.
+The project's two-layer mitigation:
+- ! **Layer 1 (env)** -- the root `Taskfile.yml` `env:` block sets `UV_PROJECT: '{{.TASKFILE_DIR}}'`. This is the safety net for any task that forgets the CLI flag in a future edit.
+- ! **Layer 2 (CLI)** -- every `uv run` invocation in `tasks/*.yml` and the root `Taskfile.yml` uses the explicit `uv --project "<pin>" run ...` form. Subfiles pin against `{{.DEFT_ROOT}}` (defined via `{{joinPath .TASKFILE_DIR ".."}}`); the root `Taskfile.yml` pins against `{{.TASKFILE_DIR}}` directly. CLI beats env beats walk, so the flag is the contract; the env var is defense-in-depth.
+- ⊗ Add a plain `uv run` line to any framework task -- the content guard in `tests/content/test_taskfile_uv_project_pin.py` will fail closed and the consumer-side breakage class returns immediately.
+- ⊗ Rely on cwd or a caller-exported `UV_PROJECT` to pin the project root. Task's `env:` does not override an already-exported `UV_PROJECT` from the caller's shell, and propagation through included subfiles depends on inclusion semantics. The CLI flag is unconditional.
+Cross-references: `Taskfile.yml` (Layer 1 env block), `tasks/*.yml` (Layer 2 call sites), `tests/content/test_taskfile_uv_project_pin.py` (deterministic content + slow behaviour regression).