diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index a69f6cc..76b974a 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -37,32 +37,32 @@ ## Security & API Stability -**Security Impact:** +**Security Impact** - [ ] No impact on security (no changes to forbidden keys, prototype safety) - [ ] Reviewed against security rules in AGENTS.md - [ ] If security-related: Explain impact and mitigation -**API Contract:** +**API Contract** - [ ] No changes to public API (`parse` function signature, type definitions) - [ ] No breaking changes to `ParseResult`, `ParseIssue`, or `IssueCode` - [ ] If API change: Is this a breaking change? (Yes/No + explanation) -**Versioning:** +**Versioning** - [ ] Change is compatible with current v0.x versioning policy - [ ] If breaking change proposed: Justification for major version bump ## Testing -**Automated Checks:** +**Automated Checks** - [ ] TypeScript type checking passes (`bun run check:type:source`) - [ ] All tests pass (`bun run test`) - [ ] Build succeeds (`bun run build`) -**Additional Verification** (describe any manual testing, edge case verification, or integration testing): +**Additional Verification** (describe any manual testing, edge case verification, or integration testing) diff --git a/AGENTS.md b/AGENTS.md index d06b66c..ab122f3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -217,3 +217,15 @@ If a change makes the parser: it likely violates the boundary. When in doubt, reject the change. + +--- + +## Agent Skills + +The `boundary-validator` skill in `skills/boundary-validator/` provides structured +validation guidance based on the rules in this document. + +- **Claude Code**: Activates automatically during PR creation and code review. + Invoke with `Review this code against boundary-validator rules`. +- **Other agents**: Apply the validation patterns in `skills/boundary-validator/SKILL.md` + when creating PRs, reviewing code, or implementing features. diff --git a/CLAUDE.md b/CLAUDE.md index 6e04f35..ce160f5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,9 +13,7 @@ When implementing features or reviewing code: ## Agent Skills The `boundary-validator` skill (`skills/boundary-validator/`) validates code changes against AGENTS.md design rules. - -- **Triggers**: Automatically activates when creating PRs or requesting code reviews -- **Coverage**: See AGENTS.md "Design rules" and "Security rules" sections +See AGENTS.md for trigger conditions and usage across agents. **Usage in Claude Code**: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2fd283a..30ae2bd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,7 +8,7 @@ This document provides guidelines for contributing to this boundary-focused Form ## Before You Start -**Please read these documents carefully:** +**Please read these documents carefully.** 1. **README.md**: Understand the design principles and what safe-formdata is (and isn't) 2. **AGENTS.md**: Review the non-negotiable implementation rules @@ -110,7 +110,7 @@ bun run test:coverage # View coverage report ### 4. Security Considerations -**Mandatory security rules** (AGENTS.md): +**Mandatory security rules** (AGENTS.md) - Use `Object.create(null)` for parsed data (no prototype) - Reject forbidden keys: `__proto__`, `constructor`, `prototype` @@ -135,7 +135,7 @@ Before submitting a PR: ### PR Description -Include: +Include the following. 1. **Problem**: What issue does this solve? 2. **Solution**: How does this maintain the boundary? @@ -144,7 +144,7 @@ Include: ### Review Process -PRs will be evaluated against: +PRs will be evaluated against the following. 1. **Alignment with design principles** (README.md) 2. **Compliance with technical rules** (AGENTS.md) diff --git a/README.md b/README.md index 858fc1e..0fbfa2c 100644 --- a/README.md +++ b/README.md @@ -197,7 +197,7 @@ if (result.data !== null) { } ``` -**Key points**: +**Key points** - All values are `string | File` - no automatic type conversion - Use `data !== null` to check for success and narrow the type diff --git a/SECURITY.md b/SECURITY.md index 156c68c..f79b6e4 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -30,7 +30,7 @@ and **public security discussion**. ### Private (Security Advisory) -Use **GitHub Security Advisories** for: +Use **GitHub Security Advisories** for the following. - Reproducible vulnerabilities - Exploit techniques or payloads @@ -42,7 +42,7 @@ Use **GitHub Security Advisories** for: ### Public Issue -Public issues are appropriate only for: +Public issues are appropriate only for the following. - **Design-level security questions** - **Non-sensitive security concerns** @@ -149,7 +149,7 @@ safe-formdata **assumes**: ## Disclosure Policy -Security reports are handled as follows: +Security reports are handled as follows. 1. **Review** - Issues are evaluated against the security scope defined above diff --git a/docs/PUBLISHING.md b/docs/PUBLISHING.md index 98b5082..3d3a4ee 100644 --- a/docs/PUBLISHING.md +++ b/docs/PUBLISHING.md @@ -20,7 +20,7 @@ Before creating a release PR, validate locally: bun run prepare:publish ``` -This runs: +This runs the following steps. 1. TypeScript type checking (`check:type:source`) 2. Test suite with coverage (`test:coverage`) diff --git a/examples/03-error-handling.ts b/examples/03-error-handling.ts index 664f185..bf72e7c 100644 --- a/examples/03-error-handling.ts +++ b/examples/03-error-handling.ts @@ -35,7 +35,7 @@ for (const issue of result.issues) { }); } -// Typical handling pattern: +// Typical handling pattern is as follows. // - log issues // - return HTTP 400 // - show a validation error to the user diff --git a/skills/README.md b/skills/README.md index 13d35cd..f8bc3f9 100644 --- a/skills/README.md +++ b/skills/README.md @@ -4,7 +4,7 @@ This directory contains **Agent Skills** specific to the safe-formdata project. ## What are Agent Skills? -Agent Skills are structured knowledge packages that agents like Claude Code can efficiently reference. Based on the implementation rules in AGENTS.md, they provide: +Agent Skills are structured knowledge packages that agents like Claude Code can efficiently reference. Based on the implementation rules in AGENTS.md, they provide the following. - **Automatic triggering**: Activates automatically during PR creation and code review - **Progressive disclosure**: Loads only necessary information incrementally @@ -18,7 +18,7 @@ Performs code review based on boundary principles. - **Purpose**: Automatically detect violations of safe-formdata's design principles - **Triggers**: PR creation, code review, post-implementation -- **Validation items**: +- **Validation items** - Key opacity (no array notation parsing, etc.) - No silent behavior (no merging, overwriting, etc.) - No inference or convenience features diff --git a/skills/boundary-validator/SKILL.md b/skills/boundary-validator/SKILL.md index 2df4535..8741a1e 100644 --- a/skills/boundary-validator/SKILL.md +++ b/skills/boundary-validator/SKILL.md @@ -55,7 +55,7 @@ Review this code against boundary-validator rules ### Review Process -The skill will: +The skill will do the following. 1. **Read the changed files** using the Read and Grep tools 2. **Check for violations** against the four design rules @@ -234,12 +234,12 @@ const data = Object.create(null); // Not {} ### API Contract -**IssueCode stability**: +**IssueCode stability** - No new IssueCode values without major version bump - Existing codes: `invalid_key`, `forbidden_key`, `duplicate_key` -**ParseResult type**: +**ParseResult type** - Must be a discriminated union - `data !== null` for type narrowing diff --git a/skills/boundary-validator/references/security-rules.md b/skills/boundary-validator/references/security-rules.md index 0c9dad2..557a84b 100644 --- a/skills/boundary-validator/references/security-rules.md +++ b/skills/boundary-validator/references/security-rules.md @@ -10,7 +10,7 @@ These rules are non-negotiable and must be enforced in all implementations. ### Forbidden Keys -Explicitly forbid the following keys: +Explicitly forbid the following keys. - `__proto__` - `constructor` diff --git a/skills/boundary-validator/references/validation-patterns.md b/skills/boundary-validator/references/validation-patterns.md index 57b5823..6347ad8 100644 --- a/skills/boundary-validator/references/validation-patterns.md +++ b/skills/boundary-validator/references/validation-patterns.md @@ -8,7 +8,7 @@ Use these patterns when reviewing code changes to safe-formdata. ## Detection Strategy -When reviewing code, search for these anti-patterns: +When reviewing code, search for these anti-patterns. 1. **Keyword search**: Look for suspicious method calls and operators 2. **Control flow analysis**: Examine conditional logic related to keys diff --git a/src/issues/forbiddenKeys.ts b/src/issues/forbiddenKeys.ts index 69b7eee..c2b1467 100644 --- a/src/issues/forbiddenKeys.ts +++ b/src/issues/forbiddenKeys.ts @@ -4,7 +4,7 @@ * These keys are reserved properties on `Object.prototype` and must never * be allowed in parsed FormData, regardless of their values or context. * - * The forbidden keys are: + * The forbidden keys are the following. * - `__proto__`: Legacy prototype accessor * - `prototype`: Function prototype property * - `constructor`: Object constructor reference