Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Docs: add specs/ — golden specs for current functional and non-functional behavior#227

Merged
twschiller merged 4 commits into
mainfrom
add-specs-directory
Jun 9, 2026
Merged

Docs: add specs/ — golden specs for current functional and non-functional behavior#227
twschiller merged 4 commits into
mainfrom
add-specs-directory

Conversation

@twschiller

@twschiller twschiller commented Jun 9, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Backfill 14 golden specs (plus README.md and _template.md) under a new top-level specs/ directory describing what the system does today. Paired with the existing decisions/ ADRs that explain why we chose a particular implementation path.
  • Each spec follows a fixed shape: Purpose, Problem (the product why — what would go wrong without this capability), User stories (human + AI agent), numbered Functional requirements (FR-N), Non-functional requirements (NFR-P/S/O/U/M-N), Current implementation with file pointers into the repo, Future work tied to a tracking issue or ADR, and Related cross-links.
  • Citation discipline mirrors the ADR backfill: every FR is grounded in code, tests, or user-facing docs; future-work bullets either link to a GitHub issue or cite an ADR's scope-cut.

Specs added

# Title
0001 Extension distribution
0002 Rule engine
0003 Prompt-injection defense
0004 Sensitive-data masking
0005 Dark-pattern defense
0006 Context-pollution reduction
0007 Visual identity and trust verification
0008 Cross-origin and shadow-DOM coverage
0009 Agent shortcuts
0010 Extension UI and controls
0011 Build-time customization
0012 Debug trace
0013 Privacy and network egress
0014 Non-functional requirements

Notes for review

  • Both kinds of doc carry a "why" — specs name the product why (the problem each capability exists to solve), ADRs name the implementation why (the path chosen over alternatives). specs/README.md documents the split.
  • Specs are forward-pointing: future-work calls out gaps and points at tracking issues or ADR scope-cuts. ADRs remain immutable historical records.
  • The agent-side user stories are intentionally distinct from the human-side ones: they name what an agent reading the page or accessibility tree gets, not a polite copy of the human story.
  • No docs/, extension/, decisions/, or skills/ files are touched — this PR is doc-only and adds one new top-level directory.

Test plan

  • Skim specs/README.md to confirm the index, status legend, spec-vs-ADR table, and citation rules read cleanly.
  • Spot-check 2–3 specs against the cited code (e.g. 0002 FR-1 ↔ `extension/src/rules/types.ts`; 0011 FR-3 ↔ `extension/data/defaults-overrides.example.json`; 0013 FR-2 ↔ `extension/src/lib/llm-client.ts` / `extension/src/lib/api-key-storage.ts`) to confirm grounding holds.
  • Read 2–3 Problem sections (e.g. 0003 prompt-injection, 0006 context pollution, 0013 privacy) to confirm they capture the user/agent harm the capability is solving, distinct from architecture choices.
  • Verify `pre-commit run --files specs/*.md specs/README.md` is clean locally (it was at commit time — mdformat reflowed paragraph wrap widths only).
  • CI Pre-commit hooks job passes on the PR.

🤖 Generated with Claude Code

…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]>
@vercel

vercel Bot commented Jun 9, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
agent-browser-shield-demo-site Ready Ready Preview, Comment Jun 9, 2026 1:38pm

Request Review

…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]>
@twschiller twschiller merged commit 6800f5b into main Jun 9, 2026
7 checks passed
@twschiller twschiller deleted the add-specs-directory branch June 9, 2026 13:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant