docs(capabilities): add stable capability IDs (CAP-<CLUSTER>-NN) + per-cluster TOC - #618
Merged
Merged
Conversation
…r-cluster TOC Every capability now has a stable ID for referencing in issues/PRs/skills, and each cluster file opens with a "Capabilities in this cluster" table listing the IDs + titles (IDs link to their heading). ID scheme: CAP-<CLUSTER>-NN, zero-padded, assigned in document order: CAP-MODEL (6), CAP-PLUGIN (7), CAP-IDENTITY (9), CAP-DASHBOARD (6), CAP-PROTO (8), CAP-VAPI (7), CAP-RUNTIME (6), CAP-ASSET (7), CAP-CONFIG (9), CAP-INTEG (15) — 80 capabilities total. Each capability heading becomes `## CAP-<CODE>-NN — <title>`. README index gains an "ID prefix" column documenting the codes. Verified: 80 IDs across 10 clusters; every cluster has a TOC; TOC anchor links match heading slugs (github-slugger-compatible); no stray headings; drift check (42 files) + license-headers check pass. Technical claims (endpoint/status/flag) unchanged — heading text + a TOC block only. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: NhanLuongBGSV <nhan.luongnguyen@vn.bosch.com>
…+ Test coverage per CAP For all 80 capabilities across 10 clusters, add: 1. A **Coverage:** checklist (Auth, Authorization, Input validation, Rate limiting, Secrets) to every ### Security section — each topic answered explicitly with the real value, or N/A / not implemented / not applied. 2. A **Coverage:** checklist (Stored data, PII, Retention, Encryption, Logging) to every ### Data protection section — same explicit-no-absence rule. 3. A new ### Test coverage section reporting the E2E (Playwright) test-case count + spec file + SITEMAP status (✅/⚠️ /❌), plus Unit (Jest) count. Absence is now unambiguous: every required topic gets an explicit answer. README updated to document the topic checklists + Test coverage (7th section). Values are code-grounded (read routes/controllers/services/models/middlewares/ validations per CAP) and E2E counts derive from .agents/tests/*.spec.ts + .agents/SITEMAP.md. Notable gaps surfaced explicitly: authLimiter defined in rateLimiter.js but never applied; Token collection has no TTL index; hard delete (no soft-delete) across models/apis; GenAI proxy uses JWT auth only (no server-side USE_GEN_AI check); GitHub tokens stored client-side in githubAuthStore; CSP wildcard-open (only objectSrc 'none'); 14/15 INTEG CAPs and all 6 DASHBOARD CAPs have 0 E2E coverage. Verified: 80 CAPs; every cluster secCov=dpCov=testCov=caps count; every Coverage block has all 5 topics (none absent); drift check (42 files) + license-headers check pass; spot-checked CAP-MODEL-01 (grounded). IDs, TOC, Risks bullets, and mermaid diagrams preserved. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: NhanLuongBGSV <nhan.luongnguyen@vn.bosch.com>
Rewrite every capability from the perspective of the user/admin/operator/API
caller who consumes the system — not the developer who builds it.
- Description now leads "As a <role>, I can <do X> so that <value>."
- Acceptance criteria framed as the contract the caller relies on ("When I
<action>, the system <responds>"); every endpoint path / HTTP status / flag
kept verbatim; internal mechanics (function names like queryModels/
seedPrototypeFiles/checkPermission, layering, file refs) removed from prose.
- Quality control restated as consumer/operator verification steps.
- Coverage checklists reworded to consumer-facing access rules (e.g. "I only
see models that are public or that I own/contribute to (owner bypass)"),
keeping gating facts (permissions/flags) and not-applied/N/A where true.
- Cluster intros: consumer-oriented lead sentence + trailing
**Implementation:** note for code-grounding (file paths no longer in prose).
- Risks, Test coverage, mermaid diagrams, IDs, TOC preserved unchanged.
README updated with the perspective rule (write for the consumer, not the
builder; file refs go in an Implementation note, not the lead).
Verified: 0 developer-perspective internals remain in prose (outside mermaid,
Risks, Test coverage, and Implementation notes); all 10 clusters structurally
OK (Coverage 5+5 topics, Test coverage, TOC, Implementation note); drift check
(42 files) + license-headers check pass; spot-checked CAP-MODEL-01 (consumer
voice, contract facts intact).
Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: NhanLuongBGSV <nhan.luongnguyen@vn.bosch.com>
…risk mitigations + coverage %
Per the consumer-perspective catalog, three refinements across all 80 CAPs:
1. Split ### Data protection into two sections:
- ### Personal data processing — explicitly states Yes/No whether the
capability processes personal data, and if yes how it's handled
(collected from, stored in, retention, encryption, who can access).
Every CAP answers Yes or No (no absence). Personal-data Risks here.
- ### AutoWRX data — the operational/business data, with the Coverage
checklist (Stored data / Retention / Encryption / Logging) + Risks.
The old PII Coverage line became the Personal-data-processing Yes/No lead.
2. Security Risks mitigations — every ### Security Risks bullet now ends with
a *Mitigation:* (what the system does, or "none currently — <recommendation>"
for known gaps: authLimiter not wired, Token no TTL, CSP wildcard-open,
GitHub tokens in localStorage, GenAI SSRF, capped audit collection,
unsandboxed plugins, asset credentials unencrypted at rest, etc.).
3. Test coverage estimated % — every ### Test coverage section now includes an
**Estimated coverage:** ≈N% (est.) — <basis> line (E2E cases vs acceptance
paths, modulated by SITEMAP status); 0 E2E → ≈0%.
README updated to document the two data sections (now 8 sections), Security
risk mitigations, and the estimated-coverage line.
Verified: 80 CAPs; every cluster pdp=awr=secCov=awrCov=testCov=est%=caps; no
leftover ### Data protection; every Personal-data-processing block has an
explicit Yes/No; every Security Risk has a *Mitigation:*; drift check
(42 files) + license-headers check pass; spot-checked CAP-IDENTITY-01.
IDs, TOC, Security Coverage, mermaid, and contract facts preserved.
Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: NhanLuongBGSV <nhan.luongnguyen@vn.bosch.com>
…ontract section The audience is the user (not the developer or even the API caller). Deep- rewrote every CAP so Description and Acceptance criteria describe what the user/admin/operator DOES IN THE UI and WHAT THEY SEE/GET — not "I call an API and get a status". - Description → "As a <role>, I can <do X in the UI> so that <value>." - Acceptance criteria → "When I <UI action>, I <see / get / am prevented from…>" covering success + error + edge cases the user experiences. No endpoint paths, HTTP statuses, or flag names in AC. - New ### API contract section (after AC, before Quality control) holds the technical contract for implementers/QA: every endpoint path, method, status, body shape, auth gating, and flag — relocated verbatim (code-grounded, none dropped). Transparent/infra CAPs (CORS/Helmet, static serving, Socket.IO, log/cache, plugin loader, runtime config) state "No HTTP surface" with config keys/env there, and lead Description with what the user observes. README updated: perspective is now "write for the user, not the builder"; API contract is a distinct section. Verified: 80 CAPs; every cluster ac=api contract=caps; no /v2/ endpoint paths or status arrows in any AC; contract facts preserved (relocated — e.g. identity-access 68 /v2/ refs, integrations 58); structure intact (Security, Personal data, AutoWRX data, Test coverage + Estimated coverage all = caps); drift check (42 files) + license-headers check pass; spot-checked CAP-MODEL-01 (user-UI AC + verbatim API contract) and CAP-INTEG-13 (infra, user-observed effect + middleware API contract). IDs, TOC, mermaid, mitigations preserved. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: NhanLuongBGSV <nhan.luongnguyen@vn.bosch.com>
…or/where AC, emoji Define a canonical CAP template in README and apply it to all 80 CAPs for an elegant, scannable, consistent format. - README: added a "Capability template" section with the exact skeleton + conventions (actors, where, emojis). - Every CAP now has a quick-facts table directly under its heading: | Actor | Where | Personal data | E2E coverage | — Actor (guest/user/owner/admin/operator/integrator), Where (page + URL, or "Global middleware (no page)" / "Operator config" for infra), Personal data (✅ Yes — <kind> / ❌ No), E2E (✅/⚠️ /❌ <N> cases, ≈<N>% est.). - Acceptance criteria reworded: every bullet is "When a **<actor>** <action> at **<Page (URL)>**, <they see/get/are prevented from…>" — names the actor and the location on every bullet; no first-person "I". - Personal data processing lead prefixed with ✅ Yes / ❌ No emoji. Verified: 80 CAPs; every cluster quickFacts=caps; 0 "When I" in any AC; every personal-data lead has ✅/❌; structure intact (Description/AC/API contract/ Security/Personal data/AutoWRX data/Test coverage all = caps); drift check (42 files) + license-headers check pass; spot-checked CAP-MODEL-01 (user UI) and CAP-INTEG-13 (infra). IDs, TOC, mermaid, mitigations, contract facts preserved. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: NhanLuongBGSV <nhan.luongnguyen@vn.bosch.com>
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
1 participant
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.
What
Give every capability a stable ID (
CAP-<CLUSTER>-NN) so capabilities can be referenced unambiguously in issues, PRs, and skills, and add a per-cluster table of contents listing the IDs + titles.Changes
## CAP-<CLUSTER>-NN — <title>(zero-padded, assigned in document order).## Capabilities in this clustertable:| ID | Capability |, IDs link to their heading.README.mdcluster index gains an ID prefix column documenting the codes.ID scheme
80 capabilities total.
How verified
scripts/check-agent-map.sh→agent-map OK(42 files);scripts/check-license-headers.sh→ OK.🤖 Generated with Claude Code