feat: publish vssa-clients skill

2026-08-14 12:10:47 +00:00
parent f0d4f416ce
commit fd33a2144a
9 changed files with 711 additions and 1 deletions
@@ -0,0 +1,46 @@
+# Derived contractor registry method
+
+Use this when canonical client-system observations contain contractor/provider text and the documentation needs a cross-client contractor view.
+
+## Evidence model
+
+Treat the contractor registry as a **derived view**, never as a second editable evidence store. Every relationship must retain:
+
+- exact canonical client and system identity;
+- explicitly named contractor/provider entity;
+- bounded role as stated by the source (developer, implementer, service provider, licensor, host, support supplier, consortium member, public-sector operator, etc.);
+- direct evidence URL and confidence;
+- historical/current/planned context where known.
+
+Do not turn `Not publicly identified`, “suppliers not named”, descriptive prose, or an ambiguous composite phrase into entities. Do not silently upgrade one role into another: development does not prove hosting or current support.
+
+## Identity and stable routes
+
+Normalize only safe textual differences for matching. Preserve the displayed source name and keep ambiguous composites separate until evidence supports a split or merge. Generate stable `CTR-*` IDs and slugs from a durable normalized identity key rather than sequence position. Sequence numbers may order generated files but must not define identity.
+
+Before adding or changing a contractor label in a canonical observation, inspect the current derived registry and all existing near-name observations. Reuse the established exact label only when it denotes the same evidenced entity. Treat a standalone company and a composite such as `„Company“ su konsorciumo partneriais` as separate identities unless reviewed evidence supports a merge. Legal-designator changes (`UAB`, `AB`, quotation style) can create a new deterministic identity; do not introduce them casually. After regeneration, compare the entity count and inspect near-name groups. An unexpected increase is an identity-collision warning, not evidence that a new contractor was discovered.
+
+A contractor dossier should list exact system/client relationships, bounded roles, confidence, and direct sources. A system dossier should expose its evidenced contractors, but the underlying client observation remains canonical.
+
+## Implementation sequence
+
+1. Write focused failing tests for named-entity extraction, unknown-placeholder exclusion, multi-contractor splitting, stable IDs/slugs, relationship aggregation, and one representative evidence-backed system.
+2. Implement extraction and aggregation without editing generated pages directly.
+3. Generate contractor overview/registry, individual dossiers, and machine-readable JSON.
+4. Add a separate documentation collection with first-level **Overview** and expanded **Registry**, plus navbar/footer/search integration.
+5. Add build invariants: JSON exists, IDs/slugs are unique, route count matches entity count, every relationship resolves to valid client/system IDs, and representative evidence is present.
+6. Run focused tests, registry validation, type checking, full production build, and rendered browser checks for both a system page and contractor page.
+7. After publishing, verify local/remote ref equality, exact CI run success, authenticated source readback, and deployed route behavior. An expected authentication redirect proves the access boundary is active, not page content; use successful CI publication and an authorized/backend content check when available before claiming deployed content.
+
+## Lifecycle evidence interaction
+
+A dated official announcement whose title/body explicitly says a named system started operating, launched, or went live can establish a production-release date at the source’s stated precision. This is different from generic page publication/update metadata. Quote the operational statement, cite corroborating announcements, and use the earliest date that explicitly establishes operation when official announcements differ. Do not infer delivery kickoff from go-live; kickoff needs separate evidence.
+
+## Common pitfalls
+
+- Parsing every capitalized phrase or semicolon clause as a company.
+- Merging legal-name variants or consortium descriptions without reviewed identity evidence.
+- Showing a contractor on a system page without retaining the source relationship.
+- Presenting a historical creation supplier as the current maintainer.
+- Claiming deployment verification solely from an unauthenticated redirect to an identity provider.
+- Adding navigation without search indexing, generated-route validation, or machine-readable output.