@aifabrix/builder 2.54.1 → 2.55.0

package/templates/agent-kit/parity-inventory.yaml

@@ -0,0 +1,188 @@
+# Frozen v1 → kit owner map. Not installed into customer repos.
+schemaVersion: "1"
+v1Files:
+  - source: commands/cust-0-plan.md
+    installedPath: .cursor/commands/cust-0-plan.md
+    sha256: a72c24163cafff97decd8382fdce1127e32ce416e05839128048b122de22b409
+    owner: aifabrix-plan
+    disposition: shim
+  - source: commands/cust-1-validate.md
+    installedPath: .cursor/commands/cust-1-validate.md
+    sha256: 8b84a1ba015516141959c311ac34ed9dd6b6dd66f286e8efc47bf34f5b2bb091
+    owner: aifabrix-connected-system
+    disposition: shim
+  - source: commands/cust-2-build.md
+    installedPath: .cursor/commands/cust-2-build.md
+    sha256: 7da4843cde98428b8f1c2ac991149d5ece8beccbfe7de7e99ef2cb80c98a42f5
+    owner: aifabrix-connected-system
+    disposition: shim
+  - source: commands/cust-3-push.md
+    installedPath: .cursor/commands/cust-3-push.md
+    sha256: f6ded45baa8517cb3280d58b92a3fd620707e2fe282726cd1087640ae92ebe30
+    owner: aifabrix-connected-system
+    disposition: shim
+  - source: commands/cust-biz-1-validate.md
+    installedPath: .cursor/commands/cust-biz-1-validate.md
+    sha256: 16ada9069f2a06d54ff63f52422283060c14de9c5bbb7b9abc6616d4451b1bee
+    owner: aifabrix-prove
+    disposition: shim
+  - source: commands/cust-biz-2-build.md
+    installedPath: .cursor/commands/cust-biz-2-build.md
+    sha256: 8b32f9b71261791d27ff0d3ae7b054334fc94ecaeb6389a1e2f50956a07b05b7
+    owner: aifabrix-prove
+    disposition: shim
+  - source: commands/cust-biz-3-prove.md
+    installedPath: .cursor/commands/cust-biz-3-prove.md
+    sha256: 7b7d6b69a74a6292cb2a581ebb68caee8d06c4ccf431ad79c044710ed167a58c
+    owner: aifabrix-prove
+    disposition: shim
+  - source: rules/README.md
+    installedPath: .cursor/rules/README.md
+    sha256: 17e691f791a5cfd686b89bf3298e55fe3fe1a933dc7f99b95ae6d08f294700d7
+    owner: package-manifest
+    disposition: obsolete
+  - source: rules/aifabrix-builder.mdc
+    installedPath: .cursor/rules/aifabrix-builder.mdc
+    sha256: 6bb6c2174c44c2489287765a8cc20121d46d8b0e7f7ab96571e2c666f710bf21
+    owner: integration/AGENTS.md
+    disposition: obsolete
+  - source: rules/builder-first-integration-generation.mdc
+    installedPath: .cursor/rules/builder-first-integration-generation.mdc
+    sha256: e52d3d15ee641affa979430b2cec5284508f4cecaf29e2a011280b95325114d1
+    owner: integration/AGENTS.md
+    disposition: obsolete
+  - source: rules/cip-field-mapping-rules.mdc
+    installedPath: .cursor/rules/cip-field-mapping-rules.mdc
+    sha256: 2f0039e8518a86902497e20e67d8fc288412105917b3c2f150f513a213180545
+    owner: contract-checklist.md
+    disposition: obsolete
+  - source: rules/credential-security-rules.mdc
+    installedPath: .cursor/rules/credential-security-rules.mdc
+    sha256: bf8089e23a65a05faf751d00178fb2d0b39308518bb7bea3f97bc8228154f076
+    owner: AGENTS.md
+    disposition: obsolete
+  - source: rules/cust-commands.mdc
+    installedPath: .cursor/rules/cust-commands.mdc
+    sha256: 7e48f104dd990a7e51d79e1a17463c0b40e98bf29f9ac4de85b49b600a03c693
+    owner: aifabrix-connected-system
+    disposition: obsolete
+  - source: rules/datasource-schema-validation.mdc
+    installedPath: .cursor/rules/datasource-schema-validation.mdc
+    sha256: eec532089e8416cbfce5859bfbf6eed187c8e6144ead2b0cd17aa36d1bdddd2f
+    owner: contract-checklist.md
+    disposition: obsolete
+  - source: rules/exposed-interface.mdc
+    installedPath: .cursor/rules/exposed-interface.mdc
+    sha256: 7fd19b564f9f31ab2d6c71b9f2d9f5f327a907909a1149861ccfa0e1cab088a9
+    owner: contract-checklist.md
+    disposition: obsolete
+  - source: rules/foreign-keys-challenge.mdc
+    installedPath: .cursor/rules/foreign-keys-challenge.mdc
+    sha256: 321ee8c2ebbecaef1132e95a27839978cfb705567a93576780c441f4d7865872
+    owner: contract-checklist.md
+    disposition: obsolete
+  - source: rules/integration-change-documentation.mdc
+    installedPath: .cursor/rules/integration-change-documentation.mdc
+    sha256: 6864f2aa7e57e4751ea75b4025ff084a6585ae4e7b679b58e5f8ed845bfe2ee3
+    owner: integration/AGENTS.md
+    disposition: obsolete
+  - source: rules/integration-test-lifecycle.mdc
+    installedPath: .cursor/rules/integration-test-lifecycle.mdc
+    sha256: ea884b9945f9effe8f026c8d713cd365aa6f94265cf8fa1ce5a0a3deff462d35
+    owner: delivery-gates.md
+    disposition: obsolete
+  - source: rules/production-system-safety.mdc
+    installedPath: .cursor/rules/production-system-safety.mdc
+    sha256: 80fc24104326aa5b0d01556a607b15cd7dac4e59248491ca11dc204b8e6db20e
+    owner: production-safety.md
+    disposition: obsolete
+  - source: rules/project.mdc
+    installedPath: .cursor/rules/project.mdc
+    sha256: 3f5692a2bd626d68e4b5c05939ee60c2d9e46d9f3dc257b2e042d65e46b22e75
+    owner: AGENTS.md
+    disposition: obsolete
+  - source: rules/rbac-abac-integration-rules.mdc
+    installedPath: .cursor/rules/rbac-abac-integration-rules.mdc
+    sha256: 2953c47dd148df8d2738e229dbe2784871ff3fabce6d64d08943de73a151177a
+    owner: contract-checklist.md
+    disposition: obsolete
+  - source: rules/role-assistant.mdc
+    installedPath: .cursor/rules/role-assistant.mdc
+    sha256: cc62ae840cbed94b7b9f50ccd52d94ab290f5c262e5e8158abfbf60db21b4f3f
+    owner: role-assistant/AGENTS.md
+    disposition: obsolete
+  - source: rules/viewpoint-fk-dimensions.mdc
+    installedPath: .cursor/rules/viewpoint-fk-dimensions.mdc
+    sha256: 76df5f2f29c15faafaed8c7c89f7d407eb2281c57c16b47bf149703a688b1736
+    owner: contract-checklist.md
+    disposition: obsolete
+  - source: skills/aifabrix-business-spec-to-plan/SKILL.md
+    installedPath: .cursor/skills/aifabrix-business-spec-to-plan/SKILL.md
+    sha256: 0b83e81d0852962dc4802a57857dfe02914165be6ab03c36c3f58f5a47e3ae33
+    owner: aifabrix-plan
+    disposition: obsolete
+  - source: skills/aifabrix-business-spec-to-plan/challenge-checklist.md
+    installedPath: .cursor/skills/aifabrix-business-spec-to-plan/challenge-checklist.md
+    sha256: 6e6d5b7340bddd9dba63626c718906420186ee490094a2db6681ea82541f9357
+    owner: aifabrix-plan/references/challenge-checklist.md
+    disposition: moved
+  - source: skills/aifabrix-business-spec-to-plan/plan-template.md
+    installedPath: .cursor/skills/aifabrix-business-spec-to-plan/plan-template.md
+    sha256: 06b46d9d45c0eb297b6e6deeb5b8803a7d79a12b8b77491dc3537e950dd6081c
+    owner: aifabrix-plan/references/plan-template.md
+    disposition: moved
+  - source: skills/aifabrix-foreign-keys-challenge/SKILL.md
+    installedPath: .cursor/skills/aifabrix-foreign-keys-challenge/SKILL.md
+    sha256: 28c9e2b41a3c89d66bb005e803b3c0655203a8e8a5ccbfe9b19eaaace46ae1a0
+    owner: contract-checklist.md
+    disposition: obsolete
+  - source: skills/aifabrix-identity-rbac/SKILL.md
+    installedPath: .cursor/skills/aifabrix-identity-rbac/SKILL.md
+    sha256: 2bc31b1a96c3a0a2cf6a9220b07c330e08b4dc0ddc6487eb4bd7c3fffdeabe63
+    owner: contract-checklist.md
+    disposition: obsolete
+  - source: skills/aifabrix-integration-e2e-tester/SKILL.md
+    installedPath: .cursor/skills/aifabrix-integration-e2e-tester/SKILL.md
+    sha256: 2dcad14746a03a88de869d8856584d8daa799312475467fd2a85ceb3ebd4b0e5
+    owner: delivery-gates.md
+    disposition: obsolete
+  - source: skills/aifabrix-integration-lifecycle/SKILL.md
+    installedPath: .cursor/skills/aifabrix-integration-lifecycle/SKILL.md
+    sha256: 6d67bdc9bee11d8e9a72b62de2133f9dc0fac80964d98f905d6a189e59bd2d76
+    owner: aifabrix-connected-system
+    disposition: obsolete
+  - source: skills/aifabrix-manifest-validator/SKILL.md
+    installedPath: .cursor/skills/aifabrix-manifest-validator/SKILL.md
+    sha256: 1dc366fb0efeafa87f643fcb6341021c42a6ce4b5a65ce9ccb4b24bb8f720c91
+    owner: aifabrix-connected-system
+    disposition: obsolete
+  - source: skills/aifabrix-package-format/SKILL.md
+    installedPath: .cursor/skills/aifabrix-package-format/SKILL.md
+    sha256: 51db0c52ff271cbe9c3f02582a1d629aab10d74a6bf0cc7b0837a936e8399fe2
+    owner: aifabrix-connected-system
+    disposition: obsolete
+  - source: skills/aifabrix-poc-business-case/SKILL.md
+    installedPath: .cursor/skills/aifabrix-poc-business-case/SKILL.md
+    sha256: b6e949292f6b9d2f1a87560594d23161a734d9cadb09b29efdf56f589ba9ac00
+    owner: aifabrix-prove
+    disposition: obsolete
+  - source: skills/aifabrix-poc-business-case/reference-demo-md.md
+    installedPath: .cursor/skills/aifabrix-poc-business-case/reference-demo-md.md
+    sha256: 3505779196339a63d4e0813de10695a59c887684e0cf1c14512f1c743c846592
+    owner: aifabrix-prove/references/demo-template.md
+    disposition: moved
+  - source: skills/aifabrix-poc-business-case/reference-evidence-lifecycle.md
+    installedPath: .cursor/skills/aifabrix-poc-business-case/reference-evidence-lifecycle.md
+    sha256: cfdeadb7417ea307028791c0a126b5ac5d6a7f1a456e05871b8d0d389c0c85a8
+    owner: aifabrix-prove/references/evidence-lifecycle.md
+    disposition: moved
+  - source: skills/aifabrix-poc-business-case/reference-learning-md.md
+    installedPath: .cursor/skills/aifabrix-poc-business-case/reference-learning-md.md
+    sha256: f89817be3dfcf5c821d565b022a8b8ead7d77b594f2561196f3b52c25999ade6
+    owner: aifabrix-prove/references/learning-template.md
+    disposition: moved
+  - source: skills/aifabrix-role-assistant-lifecycle/SKILL.md
+    installedPath: .cursor/skills/aifabrix-role-assistant-lifecycle/SKILL.md
+    sha256: 27781f1a5c5d4bb7b2e9551a063e66fceaf8f99a38dc2e6efe20048754a1de3f
+    owner: aifabrix-role-assistant
+    disposition: obsolete

package/templates/agent-kit/skills/aifabrix-connected-system/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: aifabrix-connected-system
+description: >
+  Plan, validate, build, or publish a customer Connected System with Builder.
+  Preserves READY, BUILT, PASS, and PASS_WITH_SKIPS gates. Use for integration
+  packages under integration/. Do not use to change Builder product source or
+  to author Role Assistant sidecars.
+---
+
+# aifabrix-connected-system
+
+Phases: `plan` | `validate` | `build` | `publish`.
+Resolve phase: explicit argument → plan/package state → safe next → ask once.
+
+Stop at the phase gate. Do not run the next phase without `next-yes`
+([interaction.md](../aifabrix-plan/references/interaction.md)).
+
+| Phase | Entry | Success |
+| --- | --- | --- |
+| plan | business specification exists | PLAN_READY via `aifabrix-plan` |
+| validate | plan decisions locked | READY |
+| build | READY | BUILT |
+| publish | package exists and local validate passes | PASS or PASS_WITH_SKIPS |
+
+Read current CLI help before composing commands. You own orchestration, not CLI implementation.
+Host runtimes (local vs SSH): [hosts.md](../shared/hosts.md).
+
+## Always
+
+```bash
+aifabrix auth status
+```
+
+Refresh first. User runs `aifabrix login` only if still unauthenticated. Re-run on 401, then retry once.
+
+System key: argument → active plan → sole `integration/` folder → ask once. Never invent. Reject `ra-` / `ek-` ([scripts/reserved-system-key.js](scripts/reserved-system-key.js)).
+
+## References
+
+- [delivery-gates.md](references/delivery-gates.md) — BID/wizard/repair, upload vs deploy, tests, identity, protection
+- [contract-checklist.md](references/contract-checklist.md) — exposed, FK, viewpoints, RBAC/ABAC
+- [production-safety.md](references/production-safety.md) — designated subject, credential-deferred E2E
+
+## Hard gates
+
+- Builder/BID/wizard/repair owns generated package shape
+- Manual EDS delta requires changelog
+- Schema-only `exposed` is not BUILT
+- Unexplained empty FK on business storage is not READY/BUILT
+- Non-catalog role fails
+- Upload without deploy is not published and not PASS
+- No system-level sync of views
+- No publish continuation after an unresolved hard failure
+
+## Trigger examples
+
+- Validate and build the Person system integration
+- Publish and certify this Connected System

package/templates/agent-kit/skills/aifabrix-connected-system/references/contract-checklist.md

@@ -0,0 +1,40 @@
+# Connected System contract checklist
+
+Use after BID apply / repair and before READY or BUILT.
+
+## Exposed
+
+`exposed` must include `filterable`, `readonly`, `required`, `profiles` (`default` plus capability keys), and `schema`.
+Every `filterable` field needs `metadataSchema.properties.<field>.filter: true` (usually `index: true`).
+Schema-only stubs are not BUILT. `labelKey` prefers login identity before display name.
+
+## Foreign keys
+
+Challenge every storage and view DS. Empty `foreignKeys` on business facts/children is a defect.
+FK lives on the child only: `fields` = carrier on this DS, `targetDatasource` = parent storage, `targetFields: ["externalId"]`.
+Do not add reverse FKs on the parent. Same-DS `parentId` is a field, not a self-FK.
+Allowed omit (changelog): config, logs, documented in-system root, self-tree.
+Revalidate after BID apply: `relationships` must land on the `from` EDS.
+
+## Viewpoints
+
+Partitioned aggregates and current-state person composition (person + current manager + current location/org when those storage DS exist) need FK + `dimensions` (`type: fk`) + usually `abac.applicability: required`.
+SQL must alias the grant column to the catalog dimension key before `GROUP BY`.
+Protection SSOT stays on the storage DS; views inherit. Never bulk-sync a view as storage.
+Do not flatten person+employment+org into one storage DS to avoid a current-state view.
+
+## RBAC / ABAC
+
+`roles[].value` = active COM catalog key from `aifabrix role list`. Map groups with `identity role set-groups`.
+Local ABAC filters the physical column named after the dimension key.
+Do not invent dimensions on `entityType: none` orchestration datasources.
+
+## CIP mappings
+
+Prefer `fieldMappings`, FK, and composite `primaryKey` for reshape. Minimal prep only for broken export JSON.
+CIP executes certified capability surfaces; it does not decide continuation. COM does not own continuation.
+Capabilities execute; they do not decide.
+
+## Format and changelog
+
+`aifabrix convert` is for `integration/` and `builder/` only. Manual EDS edits need `INTEGRATION_CHANGELOG.md`. File generic CLI gaps in `BUILDER_IMPROVEMENT_FINDINGS.md`.

package/templates/agent-kit/skills/aifabrix-connected-system/references/delivery-gates.md

@@ -0,0 +1,54 @@
+# Delivery gates
+
+Public docs: https://docs.aifabrix.ai/docs/build-ai-ready-systems-validate-test-cli-workflow
+
+## Create
+
+BID preferred:
+
+```bash
+aifabrix integration-definition validate ./integration/<systemKey>/bid.json
+aifabrix integration-definition apply ./integration/<systemKey>/bid.json --dry-run
+aifabrix integration-definition apply ./integration/<systemKey>/bid.json
+```
+
+Live OpenAPI: `aifabrix wizard --config integration/wizard-configs/<system>.yaml`
+
+Then `aifabrix repair <systemKey> --rbac --expose` (add `--auth` when credentials exist).
+Match workspace format with `aifabrix convert` on `integration/` only.
+
+If `integration/<systemKey>/deploy.js` exists, you may run it as the publish ladder.
+
+## Validate vs publish
+
+| Command | Meaning |
+| --- | --- |
+| `aifabrix validate <systemKey>` | Local package |
+| `aifabrix upload <systemKey>` | Draft application. CLI “Published” is not CS publish |
+| `aifabrix deploy <systemKey>` | Controller deploy = publish. Always run after upload |
+| `aifabrix show <systemKey> --online` | Dataplane **published** is truth |
+
+## Tests (separate results)
+
+| Layer | Command |
+| --- | --- |
+| Structure | `aifabrix datasource test <datasourceKey>` |
+| Pipeline | `aifabrix datasource test-integration <datasourceKey>` |
+| Live | `aifabrix datasource test-e2e <datasourceKey> --app <systemKey>` |
+| Static seed | `aifabrix datasource load <datasourceKey> --app <systemKey>` |
+
+Never mark live E2E pass when it did not run.
+
+## Identity and protection order
+
+1. `aifabrix auth status`
+2. Catalog roles + fixtures + `identity apply` / `identity sync` / `role set-groups`
+3. Load partitioned fixtures
+4. `aifabrix protection upload <sourceStorageDs> --sync` (storage DS, not the view)
+5. `aifabrix verify-governance --pack ./scenarios/….yaml` with `defaults.limit` ≤ 1000
+
+`builder/dataplane/rbac.yaml` is dataplane **app** RBAC, not customer CS roles.
+
+## Missing vendor `kv://`
+
+Do not AskQuestion for secrets. Resolve, empty generated Key Vault placeholders, **upload**, print `{dataplaneUrl}/connected-systems/{systemKey}?tab=authentication`, stop.

package/templates/agent-kit/skills/aifabrix-connected-system/references/production-safety.md

@@ -0,0 +1,35 @@
+# Production safety
+
+Many organizations have only a production vendor system. Assume that by default for live OpenAPI.
+
+System-specific limits (subject, partition, credential status, PII) live only in `integration/<systemKey>/README.md`.
+
+## Credential-deferred certify
+
+When the vendor secret is not yet in `kv://`:
+
+| Layer | Required |
+| --- | --- |
+| Package validate | Yes |
+| Structure test | Yes |
+| Integration / pipeline test | Yes when entityType supports it |
+| AI / Trust / ops | Yes where runnable without vendor secret |
+| Governance packs | Yes when subjects + fixtures exist offline; else skip-with-reason |
+| Live E2E / vendor-auth probe | Skip with reason |
+
+Publish may be **PASS_WITH_SKIPS** only for those allowed live/static skips. Never fake an E2E pass.
+Secret present and storage sync fails → FAIL / NEEDS_FIXES, never skipped.
+
+## Mutation blast radius
+
+1. README names exactly one approved test subject (stable identity keys).
+2. Create / update / delete may target only that subject.
+3. Never mutate “first list row” or a broader population.
+4. Prefer read-only E2E until writes and the subject are confirmed.
+5. Mutating E2E without a designated subject → BLOCKED before the call.
+
+## Agent
+
+Read the integration README before live or mutating tests.
+Do not invent a second safe subject without customer approval recorded in that README.
+Missing `kv://`: upload draft first, print the Authentication tab URL, stop.

package/templates/agent-kit/skills/aifabrix-connected-system/scripts/reserved-system-key.js

@@ -0,0 +1,19 @@
+/**
+ * Reserved Connected System key prefixes.
+ * @fileoverview Deterministic reserved-key check for customer delivery skills
+ */
+
+'use strict';
+
+/**
+ * @param {string} key Connected System key
+ * @returns {boolean} True when the key uses a reserved ra- or ek- prefix
+ */
+function isReservedSystemKey(key) {
+  const value = String(key || '')
+    .trim()
+    .toLowerCase();
+  return value.startsWith('ra-') || value.startsWith('ek-');
+}
+
+module.exports = { isReservedSystemKey };

package/templates/agent-kit/skills/aifabrix-plan/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: aifabrix-plan
+description: >
+  Turn a customer business specification into a delivery plan with a fixed
+  section order. Challenges missing facts; does not invent entities, roles,
+  or authority. Use before Connected System validate/build. Do not use for
+  Builder product source changes or COM architecture explanations.
+---
+
+# aifabrix-plan
+
+Input: business specification and optional `systemKey`.
+Output: one delivery plan from [plan-template.md](references/plan-template.md).
+
+Score completeness with [challenge-checklist.md](references/challenge-checklist.md).
+Next-step interaction: [interaction.md](references/interaction.md).
+Host runtimes (local vs SSH): [hosts.md](../shared/hosts.md).
+
+## Sequence
+
+```text
+specification → aifabrix-plan → PLAN_READY | NEEDS_DECISIONS | BLOCKED
+```
+
+Do not start Connected System validate until **PLAN_READY** and the user picks `next-yes`.
+
+## Workflow
+
+1. Collect the spec the user named. Do not mine platform repos as the spec.
+2. Inventory without adding: purpose, sources, entities, relationships, role labels, operations, Viewpoints, Evidence, identity join. Missing sections → `TBD` plus an Open question.
+3. Challenge required rows. AskQuestion every MISSING required row. Authority and identity cannot be guessed.
+4. Write or update `.cursor/plans/{major}.0-{slug}.plan.md` using the template H2 order. Same capability updates in place.
+5. Report status and path. On PLAN_READY, offer validate — do not run it without `next-yes`.
+
+## Hard stops
+
+- Empty spec, reserved `ra-` / `ek-` key, or contradictory identity → **BLOCKED** (no challenge prompts).
+- Unmapped catalog roles → NEEDS_DECISIONS; never invent `*-reader`.
+- “Already connected” is FACT only if `integration/<key>/` exists in this workspace.
+- No implementation before the project plan gate.
+
+```bash
+aifabrix auth status
+aifabrix role list --page-size 1000
+```
+
+If still unauthenticated after refresh, draft the plan; catalog-role rows stay MISSING until the user runs `aifabrix login`.
+
+## Trigger examples
+
+- Turn this customer specification into an implementation plan

package/templates/agent-kit/skills/aifabrix-plan/references/challenge-checklist.md

@@ -0,0 +1,108 @@
+# Challenge checklist (business spec → plan)
+
+Mark every row **FACT** | **ASSUMPTION** | **MISSING**.  
+Do **not** invent FACT. ASSUMPTION is allowed only when the spec implies it and you name the risk.
+
+`PLAN_READY` requires every **Required** row FACT or a **locked decision** in the plan (not a silent guess).
+
+## AskQuestion (mandatory when a row is MISSING)
+
+Do **not** only list gaps in chat. For every **Required** row marked MISSING, and every **Challenge if missing** row that says Ask (C1, C2, D-edit, C4), call the **AskQuestion** tool in the same turn as the `/cust-0-plan` report. Batch into **one** AskQuestion (multiple `questions[]`). Do not invent FACT from a skipped prompt.
+
+Shared option ids: `challenge-fact` (user will supply via Other), `challenge-assumption` (lock ASSUMPTION + who must confirm), `challenge-open` (leave NEEDS_DECISIONS).
+
+```json
+{
+  "title": "Plan challenges",
+  "questions": [{
+    "id": "challenge-B4",
+    "prompt": "B4 Process owner is MISSING.\n\nPLAN_READY needs a named owner or a locked ASSUMPTION with who must confirm.",
+    "options": [
+      { "id": "challenge-fact", "label": "I will provide the FACT (use Other)" },
+      { "id": "challenge-assumption", "label": "Lock as ASSUMPTION (name who must confirm in Other)" },
+      { "id": "challenge-open", "label": "Leave open — NEEDS_DECISIONS" }
+    ]
+  }]
+}
+```
+
+Substitute `challenge-{rowId}` and the row’s **PLAN_READY when** / **If missing** text. For **C1**, options are 2–3 impact models (prefer hours saved) plus `challenge-open` — do not invent a FACT measure. For **C2** / **D-edit**, ask once with the same three shared ids (D-edit default if they pick assumption: enabled while Open).
+
+Do **not** AskQuestion challenges on **BLOCKED** (empty spec / reserved key / contradictory identity). Skip rows already FACT or locked.
+
+## Business case (Required)
+
+| # | Item | PLAN_READY when |
+| --- | --- | --- |
+| B1 | Purpose | One paragraph: what improves and for whom |
+| B2 | Expected outcome | What “done” looks like (experience + proof), not only “system exists” |
+| B3 | In / out of scope | Explicit out-of-scope (do not grow the spec) |
+| B4 | Process owner | Named owner **or** ASSUMPTION with “who must confirm” |
+| B5 | Business roles | ≥1 role with **can** and **cannot** (authority, not prompts) |
+| B6 | Prove story | How we will show authority change and refusals (demo / VAL / ATTACK) |
+
+## Delivery (Required)
+
+| # | Item | PLAN_READY when |
+| --- | --- | --- |
+| D1 | Connected System key(s) | kebab-case; not `ra-` / `ek-`; existing package vs **new** stated |
+| D2 | Authoritative source(s) | Each source: already connected in **this** workspace, to-be-connected, or internal-only |
+| D3 | Entities + identity | Every entity has a stable id; **no name-string PK**; identity join named if “current user → entity” |
+| D4 | Foreign keys | Every business fact/child has joins **on the child (`from`) only**; do **not** add reverse FKs on the parent; self-`parentId` is a field, not a same-DS FK; config/logs/root/self-tree omit only with rationale (skill `aifabrix-foreign-keys-challenge`) |
+| D5 | Catalog roles | Spec role **labels** mapped to COM keys from `aifabrix role list` — never invent `*-reader` |
+| D6 | Operations | List/submit/view/admin from the spec only; no extra authority |
+| D7 | Viewpoints vs raw | Aggregates/results use named Viewpoints; raw rows not exposed through result assistants. Person+employment+org packages include a **current-state person view** (person + current manager + current location/org) unless explicitly out of scope (`viewpoint-fk-dimensions.mdc`) |
+| D8 | Validations | Happy path **and** refusal/attack cases (VAL-* / ATTACK-* or equivalent) |
+| D9 | Evidence | What Evidence must prove (actor, role, rule, success/refusal) |
+| D10 | Historical vs current | Current eligibility from source of record; historical Evidence is **not** cascade-deleted |
+
+## Challenge if missing (may stay ASSUMPTION)
+
+| # | Item | If missing |
+| --- | --- | --- |
+| C1 | Success measures | Offer 2–3 models (prefer hours saved / participation); do not invent FACT |
+| C2 | Audience / personas | Ask once |
+| C3 | Language handling | Original = Evidence; derived translation/normalization = Knowledge; never overwrite original |
+| D-edit | Optional update-while-open | Ask; default **ASSUMPTION: enabled while Open** if spec says “if editing is enabled” |
+| C4 | Admin operators | Who Open / Close / Validate / Release — named role, not “the AI” |
+| C5 | Catalog `resourceType` | Confirm at BID apply; do not guess silently |
+| C6 | Designated test subject | Required before mutating live E2E (`production-system-safety.mdc`) — README later |
+| C7 | Credential posture | Secret present vs deferred — README later; do not block plan draft |
+| C8 | Role Assistant packages | `ra-<catalogRole>` only after D5; one RA per catalog role that performs work |
+| C9 | Supported languages | Spec may say “any supported”; list known ones as ASSUMPTION |
+| C10 | Taxonomy predefined vs discovered | Spec default: discovered unless owners lock a list |
+| C11 | Identity uniqueness | Email (or equivalent login identity) is **unique in business fact** — `index` + `filter` + identity join. EDS schema has no `unique` flag; prove uniqueness after **sync** (duplicates = data-quality fail). Do not invent a schema property. |
+| C12 | Live pull / sync | Live OpenAPI with secret stored: E2E **sync** (or `datasource load` for static) must pass. Sync fail with secret present is **FAIL**, not PASS_WITH_SKIPS. |
+| C13 | Governance packs | People/HR CS or any DS with dimensions: `scenarios/` + fixtures **before** claiming push ready. Missing packs = **FAIL** unless README says governance N/A. |
+
+## Must not invent
+
+- Extra Business Roles, operations, or “admin backdoors”
+- Extra entities or fields not in the spec
+- Vendor/source fields beyond the **approved** source scope
+- COM catalog role keys that are not on `aifabrix role list`
+- Treating display names as foreign keys
+- Adding FKs on **both** sides of a relationship (parent and child)
+- Enforcing BR-* only in UI or prompt text
+- Publishing results automatically when a process **closes** if the spec requires explicit release
+- Cascade-delete of historical Evidence when source records become inactive
+- Putting tenant ids, secrets, or designated subjects into `.cursor/rules` / skills / commands
+
+## Classification hints
+
+| Spec language | Classify as |
+| --- | --- |
+| “already connected” | FACT only if the package exists under `integration/` **in this workspace**; else MISSING (to-be-connected) |
+| Role names like “Employee”, “HR Manager” | Labels — **must** map to catalog keys (D5) |
+| “AI-derived” / themes | Knowledge, versioned, not authoritative fact |
+| Original free text | Evidence — immutable |
+| Aggregate leaderboards / maps | Viewpoints — not storage dumps |
+| Self-nomination / unique / window | Governed business rules (BR-*) |
+
+## Status
+
+| Status | Meaning |
+| --- | --- |
+| **PLAN_READY** | Required rows FACT or locked; remaining opens have owner; safe to `/cust-1-validate` |
+| **NEEDS_DECISIONS** | Required MISSING; **still write** the draft plan; do **not** start `/cust-1-validate` |
+| **BLOCKED** | Empty spec, reserved `system-key`, contradictory identity (name as PK with no join), or “invent authority” requested |

package/templates/agent-kit/skills/aifabrix-plan/references/interaction.md

@@ -0,0 +1,34 @@
+# Phase and result interaction
+
+Use structured questions. Do not start the next phase from chat prose alone.
+
+## After success
+
+Offer the next eligible phase. Proceed only on `next-yes`.
+
+Shared option ids: `next-yes` · `next-no` · `next-stop`.
+
+| Completed | Next offer |
+| --- | --- |
+| aifabrix-plan PLAN_READY | connected-system validate |
+| connected-system READY | connected-system build |
+| connected-system BUILT | connected-system publish |
+| connected-system PASS or PASS_WITH_SKIPS | archive (separate) and/or prove validate |
+| prove READY / BUILT / UPDATED | prove next phase |
+| prove PASS or PASS_WITH_SKIPS | iterate validate/build |
+
+Archive is a distinct user decision (`archive-yes` / `archive-no`). Never archive as a side effect of PASS.
+
+## On gaps
+
+- NEEDS_DECISIONS: AskQuestion challenge rows. No `cust-next`.
+- BLOCKED / FAIL / NEEDS_FIXES / ABORTED: do not offer the next phase as if success.
+
+## Phase detection (connected-system and prove)
+
+1. Explicit phase from the user
+2. Active plan and package state
+3. Safe next eligible phase
+4. Ask once if ambiguous
+
+Never silently run the following phase after success.