Add portal card data model, AI generator prompt token schema, and product documentation

[Copilot]

PR^3-1 — PRE-RELEASE (Nomenclature v6.0 R1.0 FINAL LOCK — Spec + Config + Automation in WARN mode)

Summary

• Purpose: Define the portal card-based UI data model and AI Generator tab specification. Each portal card maps 1:1 to an AoR entry and contains an AI Generator tab storing tokenized prompts bound to audience/role, template ID, and metadata schema.
• Enforcement: CI runs validator in WARN/REPORT (not PR-blocking yet).
• Governance owner (AoR): AI / CM

v6.0 Canonical Filename Format (Reference)

[ATA_ROOT]_[PROJECT]_[PROGRAM]_[FAMILY]_[VARIANT]_[VERSION]_[MODEL]_[BLOCK]_[PHASE]_[KNOT_TASK]_[AoR]__[SUBJECT]_[TYPE]_[ISSUE-REVISION]_[STATUS].[EXT]

---

Scope (what this PR changes)

• Two JSON Schemas (K11_AI, SB90) defining portal card data model and AI generator prompt tokens
• One STD document in AMPEL360-SPACE-T-PORTAL describing card UI, data model, generator output spec
• Updated AI automation architecture IDX with cross-references to new artifacts

New Files

File	TYPE	Purpose
portal-card-data-model_SCH	SCH	Card ↔ AoR 1:1 mapping, AI Generator tab, generator_output with content_body + metadata_values + schema_validation + trace
ai-generator-prompt-token-schema_SCH	SCH	Shared token library (TKN-*), prompt definitions (PROMPT-*) with three-axis binding (audience, template, metadata schema), output_spec with writeback target
portal-card-ui-data-model_STD	STD	Product documentation: card grid layout, tab structure, tokenized prompt composition, generator output requirements, write-back lifecycle, enforcement rules

Key Data Model Concepts

Portal Card (CARD-{AOR}-NNN)
  └─ AI Generator Tab
       └─ Prompt Library
            └─ Tokenized Prompt (PROMPT-{AOR}-NNNN)
                 ├── audience_binding  → role_code, clearance_level
                 ├── template_binding  → template_id (TYPE), template_path
                 ├── metadata_schema_binding → schema_ref (ATA 91), required_fields
                 └── token_sequence[] → TKN-* (instruction|context|constraint|format|...)
                      │
                      ▼ activates
                 Generator Output
                      ├── content_body       (fills template)
                      ├── metadata_values    (satisfies schema)
                      ├── schema_validation  (conformance gate)
                      ├── trace              (prompt_id + version + generation_id)
                      └── → writes back to AoR record

Generator outputs are schema-conformant (validated before write-back), traceable (prompt ID/version in every output), and written back to the originating AoR record.

Modified Files

• ai-automation-architecture_IDX: Added 3 entries to Related Documents table referencing the new schemas and STD.

---

Change Checklist (must be fully satisfied)

A) Spec & Governance (v6.0 tokens explicitly defined + R1.0 FINAL LOCK)

• FAMILY defined as quantum-inspired + pax payload numbering (e.g., Q10, Q100) with pattern + allowlist rules.
• VARIANT defined as governance lane token with controlled list (e.g., GEN, BASELINE, FLIGHTTEST, CERT, MSN, HOV, CUST) and normalization rules (no spaces).
• VERSION defined as branding reinforcer with controlled list (e.g., PLUS, PLUSULTRA) plus optional 2-digit iteration (e.g., PLUS01, PLUSULTRA02).
• MODEL defined as artifact domain with controlled list (BB, HW, SW, PR).
• R1.0 FINAL LOCK: Conditional SUBJECT prefix rules documented:
  • VARIANT=CUST requires SUBJECT to start with cust-<custcode>- (custcode: 2-12 alphanumeric)
  • VARIANT=MSN requires SUBJECT to start with msn-<serial>- (serial: 3-6 digits)
• R1.0 FINAL LOCK: Normative length limits documented:
  • Max filename length: 180 characters
  • Max BLOCK: 12 chars
  • Max SUBJECT: 60 chars
  • Max TYPE: 8 chars
  • Max AoR: 10 chars
• AoR allowlist published (portal entry points) and referenced by spec.
• KNOT governance published (K01..K14 only; optional -T### only).
• __ double underscore rule published.
• ISSUE-REVISION rule published (e.g., I##-R##).
• Extension allowlist published (GitHub-first).
• Exemptions policy is explicit and versioned (no implicit exemptions).

B) Config Packaging (versioned, CI-consumed, R1.0 FINAL LOCK)

• config/nomenclature/v6_0.yaml committed with status "FINAL LOCK".
• Allowlist entries present for: FAMILY, VARIANT, VERSION (brand roots), MODEL, AoR, TYPE, STATUS, EXT.
• patterns section includes:
  • version: ^(PLUS|PLUSULTRA)([0-9]{2})?$
  • subject_prefix_for_variant.CUST: ^cust-[a-z0-9]{2,12}-
  • subject_prefix_for_variant.MSN: ^msn-[0-9]{3,6}-
• limits section includes:
  • filename_max_len: 180
  • token_max_len: block (12), subject (60), type (8), aor (10)
• Bucket/phase mapping rules included (LC01..LC14 vs SBxx ranges).
• Explicit exemptions list included (empty is acceptable, implicit is not).

C) Automation & CI (WARN mode + R1.0 FINAL LOCK enforcement)

• validate_nomenclature.py updated to v6.0 R1.0:
  • Parses all tokens including FAMILY/VARIANT/VERSION/MODEL
  • Enforces allowlists for FAMILY/VARIANT/MODEL
  • R1.0: Validates VERSION pattern (brand + optional 2-digit iteration)
  • R1.0: Validates conditional SUBJECT prefixes for CUST and MSN variants
  • R1.0: Enforces normative length limits (filename, BLOCK, SUBJECT, TYPE, AoR)
  • Enforces K01..K14 only (+ optional -T###)
  • Enforces AoR allowlist
  • Enforces mandatory __
  • Enforces ISSUE-REVISION format
  • Enforces extension allowlist
  • Enforces phase/bucket compatibility rules
• CI workflow runs validator in WARN/REPORT mode and publishes summary.
• scripts/scaffold.py generates v6.0 filenames with required tokens and allowlist validation.
• Pre-commit hook updated to run validator on changed files.

D) Repository Inventory (Required)

• Inventory report generated and committed: counts of violations by category, including:
  • invalid_family
  • invalid_variant
  • invalid_version (including iteration pattern)
  • invalid_model
  • invalid_knot
  • invalid_aor
  • missing_double_underscore
  • invalid_issue_revision
  • invalid_subject (including prefix violations)
  • invalid_type
  • invalid_status
  • invalid_ext
  • phase_bucket_mismatch
  • R1.0: length_limit_exceeded (filename, tokens)
  • R1.0: conditional_prefix_missing (CUST/MSN)

---

Required Evidence (paste outputs below)

1) Validator Output (WARN/REPORT)

COMMAND:
  python validate_nomenclature.py --standard v6.0 --mode warn --check-all

SUMMARY:
  Total files scanned:
  Violations (by category):
    invalid_family:
    invalid_variant:
    invalid_version:
    invalid_model:
    invalid_knot:
    invalid_aor:
    missing_double_underscore:
    invalid_issue_revision:
    invalid_subject:
    conditional_prefix_missing:
    length_limit_exceeded:
    invalid_type:
    invalid_status:
    invalid_ext:
    phase_bucket_mismatch:
  Exemptions applied:
  Exit code:

2) Inventory Report Reference

Inventory report:
  Path:
  Generated at (UTC):
  Top offending directories:
  Estimated rename volume:

3) Exception Register Diff (if present)

COMMAND:
  git diff -- path/to/exception_register.*

DIFF (excerpt):
  (paste excerpt here, or state "No changes")

4) R1.0 FINAL LOCK Validation Examples

# All 3 new files pass v6.0 nomenclature validation
python validate_nomenclature.py --standard v6.0 \
  "00_AMPEL360_SPACET_Q10_GEN_PLUS_BB_GEN_SB90_K11_AI__portal-card-data-model_SCH_I01-R01_ACTIVE.json"
Result: PASS

python validate_nomenclature.py --standard v6.0 \
  "00_AMPEL360_SPACET_Q10_GEN_PLUS_BB_GEN_SB90_K11_AI__ai-generator-prompt-token-schema_SCH_I01-R01_ACTIVE.json"
Result: PASS

python validate_nomenclature.py --standard v6.0 \
  "00_AMPEL360_SPACET_Q10_GEN_PLUS_PR_GEN_LC01_K11_AI__portal-card-ui-data-model_STD_I01-R01_ACTIVE.md"
Result: PASS

# Both JSON schemas validate as well-formed JSON
python -c "import json; json.load(open('portal-card-data-model_SCH...'))"
Result: PASS

---

Risk / Rollback

• No mass-renames performed in PR^3-1.
• Tooling/config changes are revertible and isolated.
• R1.0 FINAL LOCK semantics are immutable and documented.
• New schemas and STD are additive — no existing files modified except cross-reference addition to AI automation architecture IDX.

Approvals

• CM review completed (mandatory)
• AI WG review completed (prompt/generator schema governance)
• CERT review completed (only if TEKNIA credential schema/policy changes)

Notes / Follow-ups

• Next: PR^3-2 Retrofit (rename_map.csv + mass rename + cross-ref rewrite, CI becomes PR-blocking).
• R1.0 FINAL LOCK ensures future evolution is strictly additive (allowlist expansion only).
• Portal card runtime implementation (UI rendering, generator activation, write-back pipeline) is out of scope for this PR — schemas define the contract.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.