@thebackstoryis/engineering-with-ai 0.2.9

package/Docs/platform-export-analysis-guide.md

@@ -0,0 +1,336 @@
+# Power Platform and Salesforce export analysis
+
+EWAI can add bounded platform semantics to already-extracted Microsoft Power
+Platform and Salesforce source folders. The capability extends the existing
+Repository Source Map: it does not create a second index, connect to a tenant or
+org, extract archives, invoke vendor tools, deploy content, or certify that an
+application is safe or complete.
+
+Use this guide when a project contains solution source, canvas-app source,
+Salesforce Metadata API files, or a Salesforce DX project and you want those
+components and declared relationships to participate in repository search,
+graphs, Archaeology and Blast Radius.
+
+> Platform analysis is advisory evidence. It is not security certification,
+> deployment validation, product acceptance, import assurance, or proof that
+> runtime dependencies and business behaviour are complete. A qualified person
+> must review the export, coverage limits, findings and residual risk.
+
+## The operating boundary
+
+The workflow has three deliberately separate steps:
+
+1. A person uses Microsoft- or Salesforce-supported tooling to obtain and
+   extract source into a local folder.
+2. EWAI Discovery may suggest an installed technology pack from bounded path
+   markers.
+3. A person selects the pack in `SPECS/pipeline.yaml`, then explicitly refreshes
+   the Source Map.
+
+Detection does not select a pack. Selecting a pack does not run `pac`, `sf`,
+SolutionPackager, PowerShell, an archive utility, a connector, a network request,
+an import, or a deployment.
+
+The original ZIP or `.msapp` may remain in the repository, but it is inventory
+evidence only. EWAI analyses supported source files after they have been
+extracted. Microsoft documents its solution source formats and canvas-app
+extraction options in the [solution YAML reference](https://learn.microsoft.com/en-us/power-platform/alm/solution-source-control-yaml-format),
+[SolutionPackager guidance](https://learn.microsoft.com/en-us/power-platform/alm/solution-packager-tool),
+and [canvas-app source guide](https://learn.microsoft.com/en-us/power-apps/maker/canvas-apps/power-apps-yaml).
+Salesforce documents project source structure in its
+[source-format guide](https://developer.salesforce.com/docs/platform/code-builder/guide/codebuilder-source-format.html)
+and metadata families in the
+[Metadata Coverage Report](https://developer.salesforce.com/docs/success/metadata-coverage-report/references/metadata-types/v66.0/metadata-types.html).
+
+## Try a small extracted source tree
+
+A minimal recognisable Salesforce source layout looks like this:
+
+```text
+crm-source/
+├── sfdx-project.json
+└── force-app/main/default/
+    └── objects/Case/
+        └── Case.object-meta.xml
+```
+
+Use files actually exported from the intended project, not empty files created to trigger detection. For a Power Platform solution, `Other/Solution.xml` and supported extracted component files serve the equivalent role. The supported-evidence tables below explain what each analyser can read.
+
+Configure the containing repository, select the appropriate pack, refresh the Source Map and inspect coverage. The first useful result is an inventory with explicit analysed/partial outcomes and searchable technical identifiers. It isn't confirmation of a live tenant's deployment or runtime relationships.
+
+## Enable the packs
+
+The installed pack IDs are:
+
+- `ewai.technology.power-platform`;
+- `ewai.technology.salesforce`.
+
+Discovery can suggest them from these markers:
+
+| Pack | Suggestion markers |
+| --- | --- |
+| Power Platform | `Other/Solution.xml` or `solutions/*/solution.yml` beneath a walked project folder |
+| Salesforce | `sfdx-project.json`, root `package.xml`, `manifest/package.xml`, or `unpackaged/package.xml` |
+
+An archive by itself is not a marker. Suggestions remain proposals until a
+person confirms selection.
+
+Enable one or both packs under the canonical project configuration:
+
+```yaml
+packs:
+  - ewai.core
+  - ewai.technology.power-platform
+  - ewai.technology.salesforce
+```
+
+After changing pack selection, refresh the Source Map because the effective
+profile catalogue and its digest have changed:
+
+```bash
+ewai index freshness --project . --json
+ewai index refresh --project . --json
+ewai index coverage --project . --json
+```
+
+## Supported Power Platform evidence
+
+The V1 Power Platform analyser recognises:
+
+| Extracted evidence | Semantic facts |
+| --- | --- |
+| `Other/Solution.xml` | Solution unique name, allowlisted root-component technical identifiers and containment |
+| `Other/Customizations.xml` or `Other/Customisations.xml` | Recognisable entity and attribute technical identifiers and containment |
+| `solutions/<name>/solution.yml` | Solution identity from the documented solution folder |
+| `solutioncomponents.yml` | Allowlisted `Path` component identifiers and solution containment |
+| `rootcomponents.yml` | Allowlisted component schema/unique identifiers, type qualifier and containment |
+| `missingdependencies.yml` | Path-shaped missing component identifiers and declared requirements when present |
+| extracted `Src/*.pa.yaml` and `Src/Component/*.pa.yaml` | App, screen, named-component and control mapping keys plus containment |
+
+The analyser does not persist Power Fx, control property values, display labels,
+descriptions, connection-reference values, environment-variable values, or
+arbitrary XML/YAML scalar values. A `.msapp` must be extracted outside EWAI
+before its supported `Src` files can be analysed.
+
+The newer solution YAML schema and canvas source schema can evolve. Unknown
+component structures therefore produce partial evidence rather than a claim of
+complete understanding.
+
+## Supported Salesforce evidence
+
+The V1 Salesforce analyser recognises:
+
+| Extracted evidence | Semantic facts |
+| --- | --- |
+| root, `manifest/`, or `unpackaged/package.xml` | Package, allowlisted metadata type/member identities, containment and API version |
+| `sfdx-project.json` | Project and bounded package-directory identifiers |
+| decomposed `*.object-meta.xml` | Custom-object identity from its source path |
+| decomposed `*.field-meta.xml` | Qualified object/field identity and containment |
+| `*.permissionset-meta.xml` and `*.profile-meta.xml` | Object, field, Apex-class, application and tab access with paired boolean or visibility meaning |
+| `*.flow-meta.xml` | Flow identity and allowlisted record create/read/update/delete object references |
+| `*.cls-meta.xml`, LWC and Aura companion metadata | Component identity from the safe repository-relative path |
+
+The analyser does not persist labels, descriptions, formulas, conditions,
+endpoints, tokens, certificates, named-credential values, namespaces, login
+URLs, or arbitrary XML/JSON scalar values. Apex and Lightning source code remains
+the responsibility of the existing Tree-sitter or generic Source Map profile;
+the Salesforce analyser handles only its allowlisted metadata companion facts.
+
+## Repository topologies
+
+Patterns are evaluated relative to each configured repository root. The built-in
+profiles contain root and recursive variants so all three common arrangements
+are supported.
+
+### Single repository
+
+```yaml
+repositories:
+  - name: application
+    path: .
+    role: application
+packs:
+  - ewai.core
+  - ewai.technology.power-platform
+  - ewai.technology.salesforce
+```
+
+Place extracted folders below this root, for example `solutions/Contoso` and
+`force-app/main/default`.
+
+### Monorepo
+
+```yaml
+repositories:
+  - name: product
+    path: .
+    role: workspace
+packs:
+  - ewai.core
+  - ewai.technology.power-platform
+  - ewai.technology.salesforce
+```
+
+Exports may be nested, for example `apps/power/solutions/Contoso` and
+`apps/crm/force-app/main/default`. The stored Source Map path remains qualified
+by the configured repository name.
+
+### Folder containing repository subfolders
+
+```yaml
+repositories:
+  - name: power-apps
+    path: products/power
+    role: low-code
+  - name: salesforce-crm
+    path: products/salesforce
+    role: crm
+packs:
+  - ewai.core
+  - ewai.technology.power-platform
+  - ewai.technology.salesforce
+```
+
+Here `solutions/Contoso/solution.yml` is relative to `power-apps`, while
+`force-app/main/default/...` is relative to `salesforce-crm`. Repository roots
+remain configured project-local authority; analyzers cannot escape them.
+
+## Inspect evidence
+
+Inspect the effective profiles and their match counts:
+
+```bash
+ewai index profiles --source technology --project . --json
+ewai index profiles --analyser power-platform-metadata --project . --json
+ewai index profiles --analyser salesforce-metadata --project . --json
+```
+
+Inspect files without exposing their content or stored metadata:
+
+```bash
+ewai index files --classification power-platform-metadata --project . --json
+ewai index files --classification power-platform-canvas --project . --json
+ewai index files --classification salesforce-metadata --project . --json
+ewai index files --outcome analysis_failed --project . --json
+```
+
+Search technical identities and inspect declared graph relationships:
+
+```bash
+ewai index search Invoice__c --project . --json
+ewai index graph Invoice__c --project . --json
+ewai index search ContosoCore --project . --json
+ewai index graph ContosoCore --project . --json
+```
+
+The same evidence reaches Archaeology and Blast Radius through the canonical
+Source Map. Refresh before relying on it. A fresh index means it matches the
+current files and profile catalogue; it does not mean coverage is complete.
+
+## Understand partial and failed coverage
+
+Coverage includes a separate `partial` file count. A platform file can be:
+
+- `analysed` and complete within the finite V1 allowlist;
+- `analysed` but partial because an unknown family or omitted identifier was
+  observed;
+- `analysis_failed` with a stable failure code;
+- generic, shallow or inventory-only because no selected platform profile
+  matched;
+- `skipped_sensitive` or `skipped_oversized` under the normal Source Map rules.
+
+Platform analysis is bounded to 240 characters per technical identifier, 1,000
+symbols and 2,000 relationships per file, 20,000 visited structural nodes and 96
+levels of nesting. Reaching a limit produces partial or failed evidence with a
+visible warning. It never silently claims completeness.
+
+Stable platform failure codes are:
+
+- `invalid-platform-document`;
+- `unsafe-xml-declaration`;
+- `platform-analysis-limit`;
+- `unsupported-platform-layout`.
+
+Raw parser errors and source excerpts are not persisted. XML DTD and entity
+declarations are rejected; YAML aliases are disabled.
+
+## Troubleshoot safely
+
+### A pack was suggested but is not active
+
+This is expected. Review the detected technology and add the pack explicitly to
+`SPECS/pipeline.yaml` if it is appropriate. Then refresh the Source Map.
+
+### A supported file used the generic analyser
+
+Check pack selection, `ewai index profiles` match counts, the configured
+repository root and the repository-relative path. Monorepo folders should match
+the recursive built-in patterns without a custom profile.
+
+### An archive is inventory-only
+
+This is intentional. Preserve the original export if it is useful evidence, but
+extract a working copy with vendor-supported tooling outside EWAI. Do not add a
+command-bearing Source Map profile or rename the archive to force parsing.
+
+### Coverage is partial after a successful parse
+
+Review the file family and current allowlist. Partiality may reflect an evolving
+vendor schema, an unsupported component family, an invalid technical identifier,
+or a graph bound. Treat the missing semantics as an explicit uncertainty in
+Blast Radius, planning and testing.
+
+## Extend safely
+
+Technology, stack, organisation and project packs may select only registered
+analyzers. A pack can add narrower profiles for known paths, classifications and
+repository roles, but it cannot add executable parsing code.
+
+A genuinely new provider family requires an EWAI implementation change with:
+
+- a finite allowlist of persisted facts;
+- hostile-document and redaction tests;
+- bounded traversal, symbol and relationship behaviour;
+- stable failure codes and partial semantics;
+- topology and consumer regression tests;
+- updated public schemas and this documentation.
+
+Do not broaden a provider parser to retain arbitrary values merely because a
+value might sometimes be useful. Promote only stable technical identifiers and
+minimum relationship qualifiers required for honest graph meaning.
+
+## Operational checklist
+
+- [ ] The export was obtained and extracted through an accountable vendor-supported process.
+- [ ] The original archive is not being treated as semantic source.
+- [ ] Pack suggestion was reviewed and selection is explicit.
+- [ ] Repository roots and topology are correct.
+- [ ] Source Map was refreshed after extraction or pack changes.
+- [ ] Profile match counts show the expected provider analyzers.
+- [ ] Partial, failed, shallow, sensitive, oversized and inventory evidence was reviewed.
+- [ ] Search and graph results contain no prohibited source values.
+- [ ] Blast Radius conclusions state the remaining evidence limits.
+- [ ] A qualified human reviews security, deployment, product and release decisions.
+
+## Related guides
+
+- [Repository Source Map](repository-source-map-guide.md)
+- [Blast Radius and Impact Routing](blast-radius-and-impact-routing-guide.md)
+- [Existing-project onboarding](existing-project-onboarding-guide.md)
+- [Designing Organisation Blueprint Packs](designing-organisation-blueprint-packs.md)
+- [CLI and configuration reference](reference/cli-and-configuration.md)
+- [Human approval and assurance](human-approval-and-assurance-guide.md)
+
+## Current contract sources
+
+- `src/platform-metadata-analysis.mjs`
+- `src/power-platform-source-map.mjs`
+- `src/salesforce-source-map.mjs`
+- `src/repository-source-map.mjs`
+- `src/runtime/repository-index.mjs`
+- `packs/technologies/power-platform/pack.yaml`
+- `packs/technologies/salesforce/pack.yaml`
+- `tests/platform-metadata-analysis.test.mjs`
+- `tests/power-platform-source-map.test.mjs`
+- `tests/salesforce-source-map.test.mjs`
+- `tests/platform-export-integration.test.mjs`

package/Docs/policies/governance-owner-guide.md

@@ -0,0 +1,36 @@
+# Governance Owner Guide to Policy Design Gates
+
+Use this guide when a proposed design needs your policy decision. Check which rule applies, which facts support the result and whether the required controls or an explicitly permitted exception address it. You own that decision; a persona can expose gaps but can't approve the policy review.
+
+> Organisation Policy Design Gates are design-time evidence only. They do not enforce production traffic, execute production code, certify compliance, approve Build or Manual QA, authorise release, or accept residual risk.
+
+## Find the policy review
+
+Open your project's dashboard, choose **Configuration**, enable **Policy Gates** and save. Open **Policy Gates** in the sidebar and select the relevant intent. The project must have adopted an approved policy baseline before it can assess that intent. If it reports `not-configured`, agree the baseline through [policy setup](organisation-policy-design-gates.md); turning the view on isn't approval or evidence that the design meets policy.
+
+## Own the agreed rules
+
+Review the source provenance, policy scope, unmatched outcome, rule precedence, review roles, controls, exception permissions, pack pins, and effective digest before approving a baseline. Approval accepts that exact project design baseline; it does not accept every future design.
+
+Maintain source policy and Blueprint versions deliberately. When upstream material changes, EWAI reports drift and requires project review rather than silently updating accepted evidence.
+
+## Perform a review
+
+For `review-required`, inspect the matched facts, exact rule, evaluation digest, proposed design, control evidence, and limitations. Record your name, required role, decision, rationale, evidence, and any additional controls. A persona or model can prepare questions but cannot perform the review.
+
+## Approve an exception
+
+An exception exists only where the matched rule says it is permitted. Require:
+
+- a named approver and accountable owner;
+- a scope bounded by the rule and confirmed facts;
+- a clear rationale;
+- compensating controls;
+- evidence references;
+- a future expiry.
+
+Do not use an exception to override a prohibited rule. Expired or stale exceptions do not pass the gate. A new decision requires a new evaluation rather than changing an immutable record.
+
+## Assurance boundary
+
+Treat the output as design evidence for governance review. Verify that source policy was interpreted correctly and that controls are proportionate. Certification, legal conclusions, residual-risk acceptance, business acceptance, Manual QA, deployment, and release remain separate named decisions.

package/Docs/policies/implementation-guide.md

@@ -0,0 +1,42 @@
+# Organisation Policy Design Gates Implementation Guide
+
+This guide is for maintainers integrating or extending the capability without creating a second policy engine.
+
+> Organisation Policy Design Gates are design-time evidence only. They do not enforce production traffic, execute production code, certify compliance, approve Build or Manual QA, authorise release, or accept residual risk.
+
+## Architecture
+
+The policy pack and approved baseline live in `src/organisation-policies.mjs`. Confirmed facts, deterministic evaluation, reviews, exceptions, and current status live in `src/policy-design-gates.mjs`. Conditional Intent and Plan gates and control traces live in `src/policy-gate-integration.mjs`.
+
+`src/runtime/policy-workspace.mjs` is the only adapter-facing service. The CLI, MCP, HTTP, and UI call it; they never match rules, choose precedence, or derive authority themselves.
+
+## Interface map
+
+| Interface | Read | Mutations |
+| --- | --- | --- |
+| CLI | `ewai policy status` | `confirm-facts`, `evaluate`, `review`, `exception` with project-relative JSON |
+| MCP | `ewai_policy_status` | `ewai_policy_confirm_facts`, `ewai_policy_evaluate`, `ewai_policy_record_review`, `ewai_policy_record_exception` |
+| HTTP | `GET /api/policies` | strict `POST /api/policies/...` routes |
+| UI | Policy gates business/technical workspace | current evaluation and named-review actions |
+
+All roots come from server or process configuration. Reject request fields that attempt to supply a project, organisation, policy, or production root. Escape every browser field and expose only safe persona metadata, bounded categorical facts, rule details, controls, evidence references, and digests.
+
+## Lifecycle hooks
+
+Publish policy events only after verifying the exact durable record. Use a stable source key and record digest so repeat publication is idempotent. Events may include status, intent reference, evidence digest, and rule ID only. Do not include raw policy bodies, persona definitions, credentials, prompts, local absolute paths, or production targets.
+
+Handlers run after persistence. Their failure cannot roll back or veto the EWAI decision, and EWAI does not use them as runtime enforcement.
+
+## Extension rules
+
+- Add a condition dimension only through schema, domain, fact, evaluator, Impact, docs, and migration tests together.
+- Keep rules closed and deterministic; do not add narrative expressions or model calls to gate time.
+- Keep `not-configured` explicitly non-blocking.
+- Keep standard-model behaviour complete; premium personas are metadata-selected optional enrichment.
+- Preserve named-human authority and immutable digest binding.
+- Ensure any new adapter calls the shared workspace/domain contract.
+- Include the permanent disclaimer on success, empty, error, CLI, MCP description, HTTP, UI, report, and guide paths.
+
+## Verification
+
+Run the focused policy tests, `npm run check`, the full `npm test`, `npm pack --dry-run --json`, a fresh Repository Source Map, and the mandatory standards sweep. Static UI contracts do not replace representative desktop and 390 px browser Manual QA.

package/Docs/policies/organisation-policy-design-gates.md

@@ -0,0 +1,58 @@
+# Organisation Policy Design Gates
+
+Organisation Policy Design Gates let a team test a proposed system design against its approved organisational rules before Build. They are optional: a project with no approved baseline reports `not-configured` and gains no policy blocker.
+
+> Organisation Policy Design Gates are design-time evidence only. They do not enforce production traffic, execute production code, certify compliance, approve Build or Manual QA, authorise release, or accept residual risk.
+
+## Start with the project's accepted rules
+
+If the project already has an approved baseline, follow [the everyday workflow](#everyday-workflow): prepare facts, confirm them, evaluate and route the result. Ask the baseline owner to resolve a stale or missing selection rather than inventing rules in a feature review.
+
+If you're creating policy material for reuse, start with [policy pack authoring](policy-pack-authoring-guide.md). Installing a pack and approving it for this project are separate steps.
+
+## What the capability does
+
+1. An Organisation Blueprint contributes one or more strict, data-only policy packs.
+2. Guided Setup resolves those contributions and shows their exact effective digest.
+3. A named owner can approve that digest as the project baseline.
+4. Intent work proposes facts about actors, operations, data, environments, destinations, models, AI use, retention, and resources.
+5. A named person confirms or rejects every fact.
+6. EWAI deterministically matches the confirmed facts against every policy rule.
+7. The result is `allow`, `allow-with-controls`, `review-required`, `deny`, or `unassessed`.
+8. Plan traces required controls to claims, tasks, automated tests, named-human evidence, or specialist review.
+
+The browser’s **Policy gates** area offers a plain-language business view and an evidence-oriented technical view. Both use the same intent, facts, baseline and evaluation. The active persona rail shows which core, project, personal, and installed premium lenses are currently engaged and why.
+
+## Standard and premium personas
+
+Standard model reasoning with core and project personas is a complete baseline. Installed premium personas can add specialist depth for areas such as privacy, security, risk, accessibility, data, operations, or regulation. Premium access never changes the rule engine and is never required for an outcome.
+
+Personas propose questions and possible facts. They do not confirm facts, perform reviews, approve exceptions, accept risk, or certify compliance.
+
+## Everyday workflow
+
+- In **Guided Setup**, inspect and approve an optional policy baseline with the Organisation Blueprint.
+- In **Intent**, identify policy-material design facts and preserve their provenance.
+- Enable **Policy Gates** in **Configuration** and save, then open it to inspect the current result and active personas. See [dashboard configuration](../operations/dashboard-configuration.md). Hiding this view doesn't disable an applicable policy requirement.
+- Use the business view for consequence and next action; use the technical view for exact digests, matched rules, and control traces.
+- Ask the named review role to resolve `review-required` rules.
+- Use an exception only where the matched rule permits one, and always record owner, scope, controls, evidence, and expiry.
+- Re-evaluate after relevant Impact, architecture, fact, Blueprint, task, claim, or test changes.
+
+For role-specific help, continue with the [Product Owner guide](product-owner-guide.md), [Technical Owner guide](technical-owner-guide.md), [Governance Owner guide](governance-owner-guide.md), or [Implementation guide](implementation-guide.md).
+
+## Status meanings
+
+| Status | Meaning | Action |
+| --- | --- | --- |
+| `not-configured` | No approved policy baseline exists. | Continue normally or adopt one deliberately. |
+| `not-evaluated` | A baseline exists but this intent has no current evaluation. | Confirm facts and evaluate. |
+| `unassessed` | The evaluation hasn't established an allowed outcome. | Supply or review the missing facts and applicable rules, then evaluate again; don't treat this as a pass. |
+| `allow` | The current evidence has no policy blocker. | Continue through the ordinary EWAI gates. |
+| `allow-with-controls` | The design can continue only with visible controls. | Trace every control into Plan evidence. |
+| `review-required` | A matched rule needs its configured human role. | Obtain and record the named review. |
+| `deny` | The current design conflicts with policy. | Redesign, or follow a permitted exception route. |
+| `stale` | A relevant revision changed. | Reconfirm or re-evaluate; do not reuse the old pass. |
+| `invalid` | Evidence or its digest cannot be trusted. | Preserve it and investigate the integrity failure. |
+
+Passing this gate does not replace security validation, Solution Readiness, Manual QA, specialist review, representative-user evidence, deployment approval, or release acceptance.

package/Docs/policies/policy-pack-authoring-guide.md

@@ -0,0 +1,108 @@
+# Policy Pack Authoring Guide
+
+Use this guide to add a reusable policy contribution to an Organisation Blueprint Pack.
+
+> Organisation Policy Design Gates are design-time evidence only. They do not enforce production traffic, execute production code, certify compliance, approve Build or Manual QA, authorise release, or accept residual risk.
+
+## Start from accountable policy, not a prompt
+
+Name the policy owner and record whether the source is owner-declared, regulatory, contractual, or adapted. List bounded source labels that an owner can recognise. If the source is ambiguous, resolve it before encoding rules.
+
+The policy is data-only. Never add scripts, commands, prompts, templates, expressions, executables, remote references, URLs, endpoints, credentials, handlers, or hooks.
+
+## Closed vocabulary and data-only policy content
+
+Rules can match only these dimensions: `resource`, `operation`, `data_entity`, `data_classification`, `actor`, `environment`, `destination`, `model`, `ai_use`, and `retention`.
+
+Use bounded lower-case identifiers for values. Outcomes are `allow`, `deny`, `review-required`, `allow-with-controls`, and `unassessed`. Choose an explicit unmatched outcome; never let “nothing matched” become a hidden allow.
+
+## Minimal example
+
+```yaml
+schema: ewai.organisation-policy/v1
+id: design-assurance
+title: Design assurance
+version: 1.0.0
+publisher:
+  id: example
+  name: Example Organisation
+provenance:
+  kind: owner-declared
+  summary: Rules approved by the Example governance group.
+  sources:
+    - id: ai-policy
+      label: AI Policy, approved 2026-08-01
+review_roles:
+  - id: security-owner
+    name: Security Owner
+unmatched_outcome: unassessed
+rules:
+  - id: sensitive-external-ai
+    title: Sensitive data sent to external AI
+    description: A security decision is required for this design.
+    when:
+      data_classification: [sensitive]
+      destination: [external-ai]
+    outcome: review-required
+    review_role: security-owner
+    controls:
+      - id: data-flow-review
+        title: Review the data flow
+        description: Record the proposed flow and specialist decision.
+        evidence: [claim, specialist-review]
+    exceptions:
+      permitted: false
+```
+
+## Add it to a Blueprint
+
+Save the complete policy above as `example-blueprint/policies/design-assurance.yaml`. Create `example-blueprint/pack.yaml` beside the `policies` folder:
+
+<!-- example: policy-blueprint -->
+```yaml
+schema: ewai.pack/v1
+id: org.example.engineering
+name: Example Engineering
+description: A fictional policy-only Blueprint for the authoring exercise.
+version: 1.0.0
+type: organisation
+requires: []
+blueprint:
+  publisher:
+    id: example
+    name: Example Organisation
+  compatibility:
+    ewai: 0.x
+  modules:
+    - id: design-assurance
+      name: Design assurance
+      description: Review sensitive external AI data flows.
+      required: true
+      standards: []
+      personas: []
+      policies:
+        - id: design-assurance
+          title: Design assurance
+          source: policies/design-assurance.yaml
+      starter_packs: []
+```
+
+The module's policy ID matches the document's `id`; the publisher matches too. The source path is relative to `pack.yaml`, not the working directory. Follow the [Blueprint installation and discovery route](../designing-organisation-blueprint-packs.md) to make this pack available before selecting it. A required module always contributes its policy; an optional module contributes only when selected. Policy ID and publisher must agree with the module and pack metadata.
+
+Use Guided Setup to resolve the full Blueprint. Review the policy count, rule count, outcomes, roles, contribution provenance, pack pins, and effective digest. A named approver then accepts the project-local baseline. Changing the pack later marks that baseline stale; it does not rewrite project evidence.
+
+## Authoring review
+
+Before publishing a pack, verify:
+
+- every source and review role is named;
+- every rule uses the closed vocabulary;
+- every control names a real evidence route;
+- review-required rules name a valid role;
+- allow-with-controls rules define at least one control;
+- permitted exceptions name a role, while prohibited exceptions do not;
+- the unmatched outcome is intentionally restrictive;
+- no production connector or executable instruction is present;
+- example designs produce the intended precedence when several rules match.
+
+See [Designing Organisation Blueprint Packs](../designing-organisation-blueprint-packs.md) for the wider pack structure.

package/Docs/policies/product-owner-guide.md

@@ -0,0 +1,43 @@
+# Product Owner Guide to Policy Design Gates
+
+Use the Policy gates workspace to understand how an intended feature relates to organisational policy before engineering begins.
+
+> Organisation Policy Design Gates are design-time evidence only. They do not enforce production traffic, execute production code, certify compliance, approve Build or Manual QA, authorise release, or accept residual risk.
+
+## Before you open the view
+
+Use an initialised EWAI project with the intent you want to review. In the dashboard, open **Configuration**, enable **Policy Gates**, choose **Save changes**, then open **Policy Gates** in the sidebar. See [dashboard configuration](../operations/dashboard-configuration.md) if you need help finding it.
+
+Your project also needs an approved policy baseline: the rules contributed by an Organisation Blueprint and accepted in Guided Setup. If the view says `not-configured`, ask your technical or governance owner whether a baseline should be adopted. Showing the view doesn't create one, and no baseline means no policy assessment—not a compliance pass. You can continue ordinary EWAI work without this optional capability. [How policy setup works](organisation-policy-design-gates.md).
+
+## Your part in the review
+
+Describe the intended user outcome and the material facts honestly. Do not try to select values that produce a preferred result. A useful evaluation depends on knowing who acts, what they do, what data is involved, where it goes, whether AI participates, where the system is hosted, and which integrations or retention choices matter.
+
+Open **Policy gates**, select the intent, and begin with the **Business** view. It shows the current outcome, whether design action is needed, and the next accountable route. The active personas panel shows which lenses are engaged, their tier, and engagement reason. Treat their questions as prompts for better discovery, not evidence from real users.
+
+## Confirm design facts
+
+Review every proposed fact and its provenance. Confirm or reject the whole set as a named person. If a model or persona proposed a fact, check it against an accepted intent, architecture record, data decision, policy source, or knowledgeable owner before confirmation.
+
+Unknown is better than invented certainty. If an answer would materially change the design, keep it open and assign an owner.
+
+## Read the result
+
+- `allow` means the current design evidence has no policy blocker; it is not approval to Build or release.
+- `allow-with-controls` means Plan must carry explicit safeguards and evidence routes.
+- `review-required` means a specific named role must decide.
+- `deny` means redesign unless that exact rule permits a bounded exception.
+- `unassessed`, `stale`, or `invalid` means the evidence cannot support a passing decision.
+
+Stay involved when a control affects the user journey, communications, consent, operating process, training, or acceptance criteria. Use the technical view with an engineer when you need to inspect the exact evidence binding.
+
+## Example: the proposed AI destination changes
+
+Suppose a feature was planned to process internal information within an approved environment, then the proposal changes to send it to an external AI service. Confirm the changed destination and data classification as new facts; don't keep using the earlier assessment.
+
+Evaluate against the current baseline. Depending on those rules, the result may require a specialist review or controls, or deny the design. Ask the named owner to resolve that result before passing the proposal to Plan. An AI suggestion that the service is “safe” isn't that decision.
+
+## Before handing to Plan
+
+Check that the user journey still achieves its outcome, every visible control has an owner, human reviews are recorded, unresolved questions are not disguised as facts, and relevant personas have challenged the design. Policy passage remains separate from Build approval, Manual QA, specialist assurance, and release acceptance.

package/Docs/policies/technical-owner-guide.md

@@ -0,0 +1,37 @@
+# Technical Owner Guide to Policy Design Gates
+
+Check which version of your organisation's rules the design was assessed against, which controls are needed, and where the delivery plan addresses them. Use the technical policy view to inspect those links and resolve gaps before Build.
+
+> Organisation Policy Design Gates are design-time evidence only. They do not enforce production traffic, execute production code, certify compliance, approve Build or Manual QA, authorise release, or accept residual risk.
+
+## Before you start
+
+In an initialised project's dashboard, open **Configuration**, enable **Policy Gates** and choose **Save changes**. An existing intent and an approved policy baseline are needed for an assessment. If the view reports `not-configured`, use [policy setup](organisation-policy-design-gates.md) to review and adopt an applicable baseline with the owner; the visibility setting doesn't install policy or waive any requirements. [Dashboard configuration](../operations/dashboard-configuration.md) explains the navigation controls.
+
+## Inspect the current assessment
+
+Open **Policy gates**, choose the intent, and switch to the **Technical** view. Check the policy digest, facts digest, evaluation digest, matched rules, required reviews, and controls. The business and technical views must reference the same intent and outcome.
+
+Use `ewai policy status <domain/slug> --mode technical --project . --json` or `ewai_policy_status` when working through a terminal or agent host.
+
+## Inspect the control trace into delivery
+
+Every control must resolve through an allowed route:
+
+- a Claim Ledger claim with implementation evidence;
+- a task that owns the change;
+- an automated test with a stable oracle;
+- a named-human check;
+- a specialist review.
+
+Plan should record the transitive evidence, not merely repeat the control text. Changing a cited claim, task, test, or evidence file invalidates the gate. Relevant Impact dimensions include actors, AI use, data, destinations, hosting, and integrations.
+
+## Handle drift
+
+Re-evaluate after a material intent revision, changed confirmed fact, new effective Blueprint digest, policy-relevant Impact change, or changed control evidence. Never edit an old evaluation or decision to make it current. Reviews and exceptions are immutable and bound to their original evaluation digest.
+
+## Keep the runtime boundary clear
+
+Application authentication, authorisation, data-loss prevention, API gateways, database permissions, model routing, monitoring, and runtime policy enforcement remain application and infrastructure responsibilities. EWAI can require evidence that these controls are designed and tested; it does not operate them.
+
+Policy passage does not replace threat modelling, security scanners, performance evidence, operational readiness, Manual QA, deployment controls, or release approval.