security-hygiene

name	security-hygiene
description	Security hygiene for GSD's self-modifying skill and agent system. Use this skill whenever: creating, editing, or deleting skill files (.claude/skills/, .claude/commands/), modifying agent definitions (.claude/agents/), working with YAML configuration or chipset files, handling JSONL observation data (.planning/patterns/), processing community-contributed skills or chipsets, any file path operations that could involve user input, or when installing/updating project-claude configuration. Also activates for discussions about skill-creator security, trust models, or content hygiene.
user-invocable	true
version	1.0.0
format	"2025-10-02T00:00:00.000Z"
triggers	["for discussions about skill-creator security, trust models, or content hygiene"]
updated	"2026-04-25T00:00:00.000Z"
status	ACTIVE

Security Hygiene

Security Philosophy

This is a self-modifying system. Security should work like a helpful companion, not an adversarial checkpoint — zen and the art of programming. Tools protect by default, guide by suggestion, block only when there is a real reason.

Threat Surface

Vector	Risk	Check
Path traversal	Skill names used in file paths could escape directory	Sanitize all skill names: alphanumeric, hyphens, underscores only. Reject .., /, \.
YAML deserialization	Unsafe YAML loading executes arbitrary code	Use safe parsing only (yaml.safe_load or equivalent). Never yaml.load with untrusted input.
Data poisoning	Append-only JSONL could contain injected entries	Validate entries on read: check schema, reject oversized entries, verify timestamps are monotonic.
Permission bypass	Automated workflows might skip user confirmation	Never bypass user confirmation for skill application, even in YOLO mode. YOLO applies to GSD workflow commands, not skill modifications.
Cross-project leakage	User-level skills might expose project-specific patterns	User-level skills must be generic. Project-specific patterns stay in project-level skills.
Observation privacy	Pattern data could leak into shared repos	.planning/patterns/ must be in .gitignore. Verify on any git operation.

Content Hygiene Rules

When processing community-contributed content (skills, chipsets, LoRA adapters):

• Check for embedded commands or script execution
• Verify YAML does not contain unsafe tags (!!python/object, etc.)
• Validate that skill descriptions match their actual content
• Quarantine new community content for review before activation

Privacy Tier Taxonomy (4-tier, OOPS-08-P03)

All telemetry, observation data, and skill artefacts are classified into one of four privacy tiers. Telemetry writers MUST stamp every record with its tier and MUST NOT mix tiers in a single sink.

Tier	Name	Description	Examples
A	Public	No PII, no proprietary content; safe to publish externally.	Open-source skill descriptions, public release notes, anonymised aggregate metrics.
B	Internal	Non-PII operational data; safe to share within the project team.	Phase activity counts, commit-type distributions, hook firing rates, build-time profiles.
C	Sensitive	PII, credentials, authentication tokens, individual session transcripts.	.env contents, OAuth tokens, individual user prompts, raw conversation logs.
D	Restricted	Regulated data, proprietary IP, Fox Companies content.	.planning/fox-companies/ artefacts, wasteland/ content, customer-identifiable records, anything subject to legal hold.

Defaults and enforcement:

• New telemetry writers default to Tier B unless an explicit tier label is supplied at construction.
• Tier C data MUST be encrypted at rest and MUST be excluded from any artefact published outside the local repository (no git push of files containing Tier C content; no FTP sync; no inclusion in release notes).
• Tier D data MUST never leave the .planning/ tree or wasteland/ branch. Surface alignments in conversation only; never commit Tier D content to a public-facing path.
• Mixed-tier sinks are FORBIDDEN — a writer that mixes Tier A and Tier C records loses the ability to safely publish the Tier A subset.

Referenced by C5 W3.P6 tool-tracker (telemetry writer wiring) and the post-tool-use observation hook.

Authoring around the leak-scanner — don't re-trip the control (Lesson #10462)

The release-history publisher (tools/release-history/publish.mjs, leakScan) runs a hard leak-scan gate over every published chapter. Its effective patterns combine committed base patterns with operator-private patterns loaded from the gitignored release-history.local.json, so the scan is operator-machine-specific: a fresh CI checkout sees only the base patterns and never the local ones.

Two failure modes recur whenever you DOCUMENT leak-scan or security-hardening work:

1. The control's own documentation re-trips it. A retrospective that quotes a leak pattern verbatim (e.g. v1.49.588 quoting the narrowed private-path regex it was describing) matches that pattern and is HARD-BLOCKED — even though it contains no real secret.
2. The recursion trap. Documenting the fix for #1 by enumerating the private literals the control guards (company / email / credential-var) embeds those values into published content — a genuine leak the scanner correctly blocks. The v1.49.916 retrospective re-tripped exactly this way while documenting the v916 AC7 allowlist fix.

Authoring rule: describe the pattern, never quote the literal. In release notes, retrospectives, or docs that touch leak-scan work, refer to a pattern by name or shape ("the company-name local pattern", "the credential-var form") — never paste the regex source and never paste the private value.

Allowlist-vs-scrub decision rule:

• The doc legitimately quotes a leak PATTERN (a regex, for self-referential documentation) → add a narrow leak_scan_allowlist entry in the committed release-history.config.json, keyed on the EXACT version + file + pattern source, with a reason. Never widen to a global pattern exemption.
• The content embeds a genuinely-private VALUE → SCRUB the value from the content. Never allowlist a private value into published output — the allowlist is for pattern-quoting docs only, never for secrets.

This pairs the loud surface (the leak-scan gate) with the authoring discipline that keeps it from firing on its own documentation. See docs/failure-mode-contracts.md (#10427 silent-vs-loud surfaces) and docs/known-unwired-ledger-discipline.md (#10461 gate-enforce-every-runnable-surface + drift-guard).

The Staging Layer Principle

"The user's ability to work should be reasonable. Security should also be reasonable. We strive for the clean intersection." Do not over-alert. Do not create friction for normal operations. Surface findings only when something genuinely warrants attention.