Docs: add specs/ — golden specs for current functional and non-functional behavior#227
Merged
Conversation
…onal behavior Backfill 14 golden specs (plus README + template) describing what the system does today, paired with the existing decisions/ ADRs that explain why. Each spec follows: Purpose, user stories (human + AI agent), numbered functional requirements, non-functional requirements, current-implementation file pointers, future work tied to a tracking issue or ADR. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
…sion Naming a specific Chrome version (148+) freezes the spec to the build at authoring time; the actual intent is "latest stable Chromium release," with the manifest's minimum_chrome_version tracking that baseline. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
- 0013 FR-4: storage key is `agent-browser-shield.openai-api-key`, not `agent-browser-shield.api-key`. - 0009 FR-2: drop the stale 15-host enumeration (the directory ships 80 YAMLs); defer to `extension/data/sites/*.yaml` as authoritative and add a category sketch. - 0005 FR-3 / FR-4: quote the full cart-addon and hidden-fee chip templates including the parenthetical match info and the verify-before -completing directive — the actual chip is materially longer than the short `[abs: …]` prefix the spec was showing. - 0004 FR-3 (and the matching user story): show the real label format (`[card hidden]`, `[secret hidden]`, …) rather than the stylized `credit card` / `secret` examples that don't appear anywhere in the rendered placeholders. - 0008 FR-5: replace the paraphrased "may contain content ABS cannot see" quote — which matches an in-code comment but not the actual landmark — with a direct quote of the user-visible `LANDMARK_TEXT`. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Each spec now carries a Problem section between Purpose and User stories, naming the harm, friction, or risk the capability exists to address. The Problem answers "what would go wrong without this?" — the *product* why — in contrast to ADRs, which carry the *implementation* why (path chosen over alternatives). - specs/_template.md: new Problem section in the template with guidance on scope (product why, not implementation why). - specs/README.md: spec-vs-ADR distinction rewritten to acknowledge both kinds of doc carry a "why" — specs the product why, ADRs the implementation why; section-order list updated to include Problem. - specs/0001..0014: each spec gains a Problem paragraph derived from the capability's reason-to-exist: e.g. 0003 names indirect prompt injection bypassing prompt-layer filtering; 0004 names PII/credentials silently shipped into model context; 0006 names token-budget burn from page chrome; 0008 names invisible coverage gaps being worse than no coverage; 0013 names the inverted trust model if a defense extension itself leaks data. No FR/NFR changes; existing citations remain backed by the same code. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
README.mdand_template.md) under a new top-levelspecs/directory describing what the system does today. Paired with the existingdecisions/ADRs that explain why we chose a particular implementation path.Specs added
Notes for review
specs/README.mddocuments the split.docs/,extension/,decisions/, orskills/files are touched — this PR is doc-only and adds one new top-level directory.Test plan
specs/README.mdto confirm the index, status legend, spec-vs-ADR table, and citation rules read cleanly.🤖 Generated with Claude Code