@thebackstoryis/engineering-with-ai 0.2.9

package/Docs/blast-radius-and-impact-routing-guide.md

@@ -0,0 +1,325 @@
+# Blast Radius and Impact Routing guide
+
+Use Blast Radius before changing an existing capability when you need to understand which repository paths, people, standards, and review responsibilities may be affected.
+
+The assessment is deliberately advisory. It combines bounded repository evidence with clearly labelled inference, then asks a named person to decide which reviews are appropriate. It does not approve Build, security, compliance, release, or Manual QA.
+
+
+<!-- editorial: contents -->
+## On this page
+
+- [What the assessment answers](#what-the-assessment-answers)
+- [When to use it](#when-to-use-it)
+- [Before you begin](#before-you-begin)
+- [Step 1: check the repository map](#step-1-check-the-repository-map)
+- [Step 2: describe the proposed change](#step-2-describe-the-proposed-change)
+- [Step 3: provide files or symbols](#step-3-provide-files-or-symbols)
+- [Step 4: analyse impact](#step-4-analyse-impact)
+- [Understand coverage before deciding](#understand-coverage-before-deciding)
+- [Override a recommendation responsibly](#override-a-recommendation-responsibly)
+- [Record the assessment](#record-the-assessment)
+- [Use the result downstream](#use-the-result-downstream)
+- [Worked examples](#worked-examples)
+- [Troubleshooting](#troubleshooting)
+- [Assessment checklist](#assessment-checklist)
+- [Related guides](#related-guides)
+- [Current contract sources](#current-contract-sources)
+
+## What the assessment answers
+
+Blast Radius helps answer four related questions:
+
+1. **What repository evidence is connected to the proposed change?**
+2. **What consequences might follow from that evidence?**
+3. **Which installed perspectives are useful for challenging the assessment?**
+4. **Which accountable people should review the change?**
+
+It does not prove that every dependency has been found. Dynamic calls, runtime configuration, external systems, generated code, human processes, and undocumented relationships may sit outside the repository map.
+
+## When to use it
+
+Run an assessment:
+
+- while shaping an intent that changes existing behaviour;
+- before Plan when the likely implementation area is known;
+- when a proposed change touches permissions, data, public interfaces, operational behaviour, or a user journey;
+- when new repository evidence materially changes an approved plan;
+- before choosing Manual QA scenarios for a cross-cutting change;
+- after refreshing a stale repository map;
+- when a seemingly small refactor may have several consumers.
+
+Repeat the assessment when the proposed behaviour, selected targets, repository index, or material implementation boundary changes. A previous assessment remains historical evidence; it is not an assurance statement about later code.
+
+## Before you begin
+
+You need:
+
+- an EWAI work item that can be selected in the project dashboard;
+- a concrete description of the proposed behavioural change;
+- at least one repository-relative path or symbol that represents the likely change boundary;
+- a fresh repository map;
+- a person willing to review the result and own the routing decisions.
+
+Open the project dashboard, select the relevant work item, and open its **Impact** tab.
+
+## Step 1: check the repository map
+
+The Impact workspace states whether the Repository Source Map is fresh and reports its explicit outcomes, analysis depths, profile provenance, and a bounded sample of files needing attention.
+
+If the map is stale or unavailable, select **Refresh repository map**. Refresh is an explicit operation because indexing can be expensive. The proposed-change draft is preserved, but any previous preview is cleared because its evidence belonged to the older index run.
+
+A fresh map means the assessment is based on the current indexed project state and effective profile catalogue. It does not mean that every file was deeply analysed or that every runtime dependency or business process is represented. Explicitly partial Power Platform or Salesforce metadata also keeps the assessment partial even when its document parsed successfully. Review the full [Repository Source Map guide](repository-source-map-guide.md) and [platform export analysis guide](platform-export-analysis-guide.md) when coverage is partial.
+
+## Step 2: describe the proposed change
+
+Describe the behaviour and intent, not merely an implementation instruction.
+
+Prefer:
+
+> Allow delegated users to request access through the customer access form, with an auditable permission decision and clear failure guidance.
+
+Avoid:
+
+> Change `if` statement on line 42.
+
+The summary helps EWAI classify possible user, interface, data, security, operational, maintainability, testing, documentation, and training consequences. The current limit is 2,000 characters.
+
+State an explicitly internal change honestly. For example:
+
+> Refactor the internal sorting helper without changing behaviour or public interfaces.
+
+This helps prevent an internal refactor from being treated as a user-facing product change. It is still the assessor's responsibility to verify that the claimed boundary is true.
+
+## Step 3: provide files or symbols
+
+The paths below illustrate the fictional customer-access application. Replace them with paths returned from your own repository search; they aren't files to create and don't refer to EWAI's implementation.
+
+Enter one repository-relative path or symbol per line. Exact repository-relative paths are the clearest starting points:
+
+```text
+src/permissions/access.ts
+confirmImpactAssessment
+public/app.js
+```
+
+The current assessment accepts between one and twelve unique targets. Each target must be no longer than 240 characters. Absolute paths, URLs, traversal such as `../`, and paths beginning with `./` are rejected.
+
+EWAI resolves targets in this order:
+
+1. exact file path;
+2. exact symbol name;
+3. a unique path suffix or partial symbol match.
+
+An unresolved target remains visible as a coverage limitation. An ambiguous target lists bounded candidates. Prefer an exact path or a more specific symbol rather than choosing based on guesswork.
+
+## Step 4: analyse impact
+
+Select **Analyse impact**. Preview is write-free: it does not create assessment evidence or change a delivery approval.
+
+Read the result in three bands.
+
+### Observed: repository evidence
+
+The observed band begins with the resolved targets and follows recognised imports in both directions:
+
+- **downstream dependency** — the current path imports another indexed path;
+- **upstream consumer** — another indexed path imports the current path;
+- **seed** — a path resolved directly from the supplied target.
+
+Traversal is intentionally bounded to two relationship steps and eighty nodes. Each result includes its direction, distance, relationship, and repository-relative path.
+
+The graph is evidence about indexed source relationships. It is not a claim that every shown file must change, and absence from the graph is not proof that a file, service, person, or workflow is unaffected.
+
+### Inferred: possible consequences and active perspectives
+
+EWAI classifies possible impact areas from the proposed-change summary and bounded repository evidence. These consequences are labelled **inferred**. Review them as hypotheses to confirm, correct, or reject.
+
+Attached standards may also appear. Their presence means the standard may be applicable to the affected evidence; it does not establish compliance.
+
+The active persona ensemble can include up to four relevant installed personas from:
+
+- core EWAI personas;
+- the installed premium library;
+- reusable personal personas;
+- local project personas, including approved organisation-specific personas.
+
+For every active persona, the UI shows its name, tier, matched concerns, and engagement reason. Tier communicates provenance, not rank or authority. The assessment exposes safe persona metadata rather than proprietary persona definitions or filesystem paths.
+
+Personas help identify missing questions, failure modes, and stakeholder consequences. They do not provide stakeholder evidence or make the routing decision. If no installed persona matches, involve the relevant real person rather than treating the empty ensemble as proof that no specialist review is needed.
+
+### Decided: human review routes
+
+EWAI recommends one of `required`, `recommended`, or `not indicated` for each route:
+
+| Route | What the reviewer contributes | What the route does not do |
+| --- | --- | --- |
+| Product Owner | Confirms user, outcome, public-interface, acceptance, documentation, or training consequences. | Approve Build. |
+| Security or identity owner | Reviews security, identity, permissions, privacy, or data boundaries. | Certify security or compliance. |
+| Service operator | Reviews runtime, support, recovery, logging, and operational consequences. | Approve release. |
+| Maintainer | Reviews dependencies, tests, implementation quality, and a broad or truncated technical radius. | Replace product or assurance review. |
+| User validation | Tests user-visible consequences with representative people. | Allow persona simulation to replace human evidence. |
+
+Review every route. A recommendation is a prompt for accountable judgement, not an automatic workflow assignment.
+
+## Understand coverage before deciding
+
+Coverage is reported as complete only within the configured bounds when:
+
+- the Source Map contains no inventory-only, shallow, sensitive, oversized, or failed evidence;
+- every supplied target resolved unambiguously;
+- graph traversal did not reach the node limit.
+
+Coverage is partial when any target is unresolved or ambiguous, any evidence is less than deep, an indexed file was deliberately unopened or failed analysis, or traversal was truncated. Treat a narrow result under partial coverage as uncertainty—not proof of low impact.
+
+Before recording a decision, ask:
+
+- Did we choose the correct change boundary?
+- Are generated code, runtime wiring, external services, data migrations, or manual processes missing from the repository graph?
+- Does the summary state the intended behavioural effect clearly?
+- Do the inferred consequences match the evidence?
+- Are the active perspectives relevant, and which real perspectives are missing?
+- Is further archaeology or specialist review needed before planning?
+
+## Override a recommendation responsibly
+
+You may change a route recommendation when project evidence supports a different decision. EWAI requires a rationale for every override.
+
+A useful rationale names the evidence and the boundary:
+
+> Product review is not indicated because this replaces an internal helper behind an unchanged public contract; existing contract and journey tests remain unchanged.
+
+An inadequate rationale merely restates the selection:
+
+> Not needed.
+
+If the evidence is too weak to explain an override, retain the safer route or gather the missing evidence first.
+
+## Record the assessment
+
+To record the result:
+
+1. review the observed evidence, coverage statement, inferred consequences, active personas, and every route;
+2. enter the name of the assessor;
+3. supply a rationale for each changed recommendation;
+4. acknowledge the evidence and coverage limits;
+5. select **Record assessment**.
+
+EWAI recomputes the preview against the current repository map rather than trusting browser-supplied analysis. If the index changed after preview, the confirmation is rejected and the assessment must be run again.
+
+A successful confirmation writes content-addressed JSON and Markdown under:
+
+```text
+SPECS/6.Build/<intent-slug>/impacts/<assessment-id>.json
+SPECS/6.Build/<intent-slug>/impacts/<assessment-id>.md
+```
+
+The record includes the proposal, targets, repository run, coverage, observed paths, inferred areas, applicable standards, active personas, recommendations, human decisions, rationales, assessor, time, and authority boundary.
+
+Evidence is immutable. Repeating the same decision returns the existing assessment; EWAI does not overwrite an incomplete, conflicting, or tampered record.
+
+## Use the result downstream
+
+An impact assessment should inform—not silently mutate—later work:
+
+- update intent journeys or acceptance criteria when a product consequence is confirmed;
+- involve the selected accountable reviewers;
+- add affected standards and constraints to planning evidence;
+- create test obligations for important paths and failure modes;
+- use confirmed user-visible consequences to choose Manual QA scenarios;
+- add documentation, training, migration, support, or recovery work where required;
+- repeat the assessment if implementation crosses the assessed boundary.
+
+Do not treat an assessment ID as approval evidence for another gate. Build approval, specialist assurance, release authorisation, and Manual QA each retain their own owner and evidence.
+
+## Worked examples
+
+### Bounded internal refactor
+
+**Proposal:** Refactor an internal helper without changing behaviour or public interfaces.
+
+**Targets:** the helper path and its exported symbol.
+
+Expected review focus:
+
+- verify consumers and tests in the observed radius;
+- engage a maintainer perspective;
+- confirm that user and public contracts really are unchanged;
+- avoid forcing Product Owner review when no product consequence is evidenced.
+
+### User-facing permission change
+
+**Proposal:** Change which delegated users can submit an access request and how rejection is explained.
+
+**Targets:** the form, permission service, and relevant endpoint or handler.
+
+Expected review focus:
+
+- Product Owner review of journey and acceptance consequences;
+- security or identity review of the permission boundary;
+- representative user validation;
+- negative, cross-boundary, audit, recovery, and accessible-error scenarios;
+- documentation or training changes where the user guidance changes.
+
+### Operational recovery change
+
+**Proposal:** Change retry and logging behaviour when a background operation fails.
+
+**Targets:** the worker, retry policy, and logging adapter.
+
+Expected review focus:
+
+- service-operator review of recovery, observability, and support impact;
+- maintainer review of dependencies and regression coverage;
+- data or security review if payloads or sensitive values could reach logs;
+- a Manual QA or operational exercise that demonstrates recovery rather than only a passing unit test.
+
+## Troubleshooting
+
+| Problem | What to do |
+| --- | --- |
+| Repository map is stale or unavailable | Refresh it explicitly, then analyse again. |
+| Target is unresolved | Check spelling, use an indexed repository-relative path, or refresh after adding the file. |
+| Target is ambiguous | Use an exact path or a more specific exported symbol. |
+| Coverage is partial | Resolve what you can, inspect parser failures or truncation, and record remaining uncertainty. |
+| An expected persona is absent | Check that the persona is installed and relevant to the supplied signals; involve the real stakeholder regardless. Do not download premium content implicitly. |
+| A recommendation appears wrong | Improve the proposal and targets if the evidence is wrong; otherwise override with a specific evidence-based rationale. |
+| The repository map changed before confirmation | Re-run the analysis against the new index run. |
+| Existing evidence is incomplete or conflicting | Preserve it and investigate; the immutable writer will not overwrite it. |
+
+For index or dashboard failures, use [Troubleshooting and recovery](operations/troubleshooting-and-recovery.md).
+
+## Assessment checklist
+
+- [ ] The repository map is fresh.
+- [ ] The proposal describes behaviour and intent.
+- [ ] Targets are exact and cover the likely change boundary.
+- [ ] Unresolved, ambiguous, failed, or truncated coverage is understood.
+- [ ] Observed evidence is distinguished from inferred consequences.
+- [ ] Active persona names, tiers, concerns, and reasons were reviewed.
+- [ ] Missing real stakeholder perspectives were identified.
+- [ ] Every review route has a deliberate decision.
+- [ ] Every override has an evidence-based rationale.
+- [ ] The named assessor reviewed and acknowledged the limits.
+- [ ] The assessment record is used as input, not as another gate's approval.
+- [ ] Material scope changes trigger a fresh assessment.
+
+## Related guides
+
+- [Product Owner guide](product-owner-guide.md)
+- [Developer delivery guide](developer-delivery-guide.md)
+- [Repository Source Map](repository-source-map-guide.md)
+- [Power Platform and Salesforce export analysis](platform-export-analysis-guide.md)
+- [Persona engagement UI](personas/persona-engagement-ui.md)
+- [Manual QA and acceptance](quality/manual-qa-and-acceptance.md)
+- [Existing-project onboarding](existing-project-onboarding-guide.md)
+- [Human approval and assurance](human-approval-and-assurance-guide.md)
+
+## Current contract sources
+
+- `src/runtime/impact-analysis.mjs`
+- `src/runtime/repository-index.mjs`
+- `src/runtime/persona-engagement.mjs`
+- `src/runtime/dashboard-server.mjs`
+- `public/app.js`
+- `tests/impact-analysis.test.mjs`
+- `tests/runtime.test.mjs`

package/Docs/blueprints/internal-blueprint-catalogue.md

@@ -0,0 +1,146 @@
+# Building an internal Blueprint catalogue
+
+Use this guide to make reviewed Organisation Blueprint Packs discoverable across teams without confusing catalogue trust with project approval.
+
+## Current behaviour
+
+EWAI discovers packs from supported local roots. An optional, organisation-operated [Team Hub resource registry](../team-hub-resource-registry-guide.md) can publish, inspect and install reusable resources by exact version and digest. It isn't a vendor-hosted marketplace, and installing a Blueprint doesn't approve it for a project.
+
+The catalogue model below adds ownership, support and adoption guidance around those distribution routes.
+
+## Catalogue responsibilities
+
+An internal catalogue should answer:
+
+- What is this pack for?
+- Who publishes and supports it?
+- Which projects or risk contexts should use it?
+- Which versions are supported?
+- What changed in each release?
+- What compatibility and dependencies apply?
+- Where is the reviewed source?
+- How is provenance verified?
+- How does a project request help or an exception?
+
+It should not imply that listing equals suitability or approval.
+
+## Keep catalogue metadata outside the manifest
+
+The V1 organisation manifest is strict. Maintain catalogue-only information separately, for example:
+
+| Catalogue field | Purpose |
+| --- | --- |
+| Display name and summary | Human discovery |
+| Owner and support contact | Accountability |
+| Status | Draft, pilot, supported, deprecated, or retired |
+| Intended audience | Applicability guidance |
+| Risk classification | Review depth expectation |
+| Source repository and revision | Provenance |
+| Supported versions | Maintenance promise |
+| Release notes | Change interpretation |
+| Adoption guidance | Required project action |
+| Exception route | Governance handoff |
+| Policy contribution summary | Required or optional module, publisher, version, provenance label, rule and role counts, outcomes, unmatched posture, and digest |
+
+Do not add these as undeclared keys to `pack.yaml`.
+
+## Trust levels
+
+Recommended catalogue states:
+
+- **Draft:** author-owned and not for project use.
+- **Pilot:** reviewed for bounded trial projects.
+- **Supported:** approved for the declared audience with named maintenance ownership.
+- **Deprecated:** still interpretable but no longer recommended for new adoption.
+- **Retired:** distribution removed after retention and migration decisions.
+
+State the evidence required to move between levels. Avoid labels such as “certified” unless the organisation has defined exactly what certification means.
+
+## Distribution model
+
+Use an approved internal distribution route to place immutable pack versions into one of the supported local roots. The distribution process should verify:
+
+- source repository and revision;
+- expected publisher and pack identity;
+- version immutability;
+- content digest or release checksum;
+- dependency availability;
+- safe archive extraction and path boundaries;
+- access controls for restricted content;
+- audit record of who published and installed it.
+
+EWAI's resolved digest is useful project evidence, but it is not itself a publisher signature. Use your normal software supply-chain controls for authenticity.
+
+## Help teams choose
+
+Catalogue search and descriptions should lead with context rather than technology names alone:
+
+- user and data sensitivity;
+- external or internal exposure;
+- regulatory and assurance needs;
+- delivery type and operational criticality;
+- supported technology or architecture patterns;
+- required organisational policy.
+
+Guided Setup should still show the exact local pack identity, version, modules, dependencies, digest, and consequences before approval.
+
+## Catalogue policy-bearing Blueprints without activating them
+
+For a Blueprint that contributes Organisation Policy Design Gates, make the design impact visible before installation or selection. Catalogue metadata should identify:
+
+- which required and optional modules contain policy contributions;
+- publisher, version, source label, provenance kind, and immutable digest;
+- policy, rule, control, and review-role counts;
+- possible outcomes and the unmatched outcome;
+- EWAI compatibility, support owner, and exception route;
+- whether a newer policy version may require existing projects to re-review their baseline.
+
+This metadata helps a team choose; it is not the policy source of truth and does not activate a baseline. Guided Setup must still resolve the installed content, show the exact effective digest and consequences, and obtain named project approval. If a project approves no policy contribution, its policy status remains `not-configured` and non-blocking.
+
+Do not expose complete policy source documents, managed premium persona bodies, project-local personas, credentials, or confidential organisation detail in a general catalogue. Use access-controlled source and distribution routes where the contribution itself is restricted.
+
+See [Organisation Policy Design Gates](../policies/organisation-policy-design-gates.md) for project status and workflow, and the [Governance Owner Guide](../policies/governance-owner-guide.md) for baseline and exception accountability.
+
+> 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.
+
+## Prevent cross-project leakage
+
+Keep reusable organisation knowledge separate from client- or project-specific facts. Before publishing, check that the pack contains no:
+
+- client names or confidential requirements;
+- credentials, endpoints, or internal secrets;
+- project-specific user research presented as universal truth;
+- copied managed persona content;
+- machine-specific absolute paths;
+- boilerplate that will be executed implicitly.
+
+## Catalogue review cadence
+
+Review each supported entry when:
+
+- EWAI compatibility changes;
+- a dependency is upgraded or retired;
+- a policy or standard changes;
+- a security issue affects included guidance or references;
+- user feedback reveals ambiguous applicability;
+- the named owner changes;
+- the normal review interval expires.
+
+## Catalogue checklist
+
+- [ ] Pack source and publisher are verified.
+- [ ] Catalogue metadata is separate from the strict manifest.
+- [ ] Status and support promise are defined.
+- [ ] Versioned releases are immutable and traceable.
+- [ ] Distribution preserves local trust and path safety.
+- [ ] Project choice still requires Review and named approval.
+- [ ] Deprecation and exception routes are visible.
+- [ ] No project or managed-library content leaked into the pack.
+
+## Related guides
+
+- [Designing Organisation Blueprint Packs](../designing-organisation-blueprint-packs.md)
+- [Maintaining Organisation Blueprints](maintaining-organisation-blueprints.md)
+- [Organisation Policy Design Gates](../policies/organisation-policy-design-gates.md)
+- [Governance Owner Guide to Policy Design Gates](../policies/governance-owner-guide.md)
+- [Consultancy and multi-project rollout](../adoption/consultancy-and-multi-project-rollout.md)

package/Docs/blueprints/maintaining-organisation-blueprints.md

@@ -0,0 +1,154 @@
+# Maintaining Organisation Blueprints
+
+Use this guide after an Organisation Blueprint Pack is in use by one or more projects.
+
+## The maintenance contract
+
+A Blueprint is a versioned input to project decisions. Its owner may publish improvements, but each project retains its accepted materialised files, receipt, pin, and adoption authority.
+
+Upstream maintenance must never silently rewrite project truth.
+
+## Assign ownership
+
+Recommended practice is to name:
+
+- a publisher owner accountable for the pack;
+- subject-matter owners for each standard and persona template;
+- a technical maintainer for schema, compatibility, dependencies, and tests;
+- a governance approver for breaking or policy-significant changes;
+- a communication owner for release notes and deprecation.
+
+Record ownership in the catalogue or repository documentation. Do not add undeclared governance fields to the strict V1 manifest.
+
+## Version deliberately
+
+Use semantic-versioning intent:
+
+| Change | Suggested version effect |
+| --- | --- |
+| Clarification with no changed obligation | Patch |
+| New optional module or backward-compatible guidance | Minor |
+| Changed mandatory standard or policy outcome, removed module, renamed identity, or incompatible structure | Major |
+
+The schema accepts a version string, but EWAI cannot decide the organisational significance of the change. The publisher owns that judgement.
+
+## Keep identity stable
+
+Avoid changing the publisher-scoped pack ID. Consumers and dependency declarations use it as the stable identity. A rename should normally be treated as a new pack with an explicit migration and deprecation notice.
+
+Keep module IDs stable as well. If a module's purpose changes materially, introduce a new module rather than preserving an ID that now means something different.
+
+## Review changes by consequence
+
+For every release, compare:
+
+- required and optional module membership;
+- standard wording and obligation strength;
+- persona mission, metadata, questions, and authority boundary;
+- policy provenance, rule match conditions, outcomes, controls, review roles, exception posture, and unmatched outcome;
+- boilerplate metadata and integrity value;
+- required pack IDs and the installed dependency versions;
+- EWAI compatibility;
+- resolved digest for representative selections;
+- generated project destinations and collision risk.
+
+Review the resolved pack, not only the manifest diff. A dependency change can alter outcomes without a large root-manifest edit.
+
+## Maintain policy contributions as governed inputs
+
+Treat Organisation Policy Design Gates as versioned design inputs, not as mutable organisation-wide switches. For every policy contribution change:
+
+- retain an accountable policy owner and recognisable source provenance;
+- validate the strict, closed rule vocabulary and data-only boundary;
+- review changed rule precedence, outcomes, controls, review roles, exception permissions, and unmatched posture;
+- publish a new immutable pack version and explain which project designs may be affected;
+- test representative facts against both the previous and proposed policy versions;
+- preserve the previous source long enough to interpret accepted project evidence.
+
+Changing an upstream policy or Blueprint may mark an accepted project baseline stale, but it must never rewrite that baseline. Each project reopens the preview and a named person approves a new exact effective digest. A project with no approved contribution remains explicitly `not-configured` and non-blocking; maintenance does not create a hidden default.
+
+Policy maintenance also does not install or update premium personas. Installed premium personas can deepen the questions asked during policy analysis, while core and project personas remain a complete baseline; neither persona type changes deterministic rule outcomes or human approval authority.
+
+Use the [Policy Pack Authoring Guide](../policies/policy-pack-authoring-guide.md) to validate contribution structure and the [Governance Owner Guide](../policies/governance-owner-guide.md) to review baseline, review-role, and exception decisions.
+
+> 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.
+
+## Test representative combinations
+
+Maintain fixtures for:
+
+- required modules only;
+- each optional module individually;
+- supported combinations of optional modules;
+- dependency chains;
+- the oldest and newest supported EWAI versions where practical;
+- collision and unsafe-path rejection;
+- total-size and recursion boundaries;
+- expected materialised standards, personas, receipts, and pins.
+
+Use a temporary project for approval-flow tests. Do not apply a maintenance candidate directly to a live project merely to see what happens.
+
+## Publish useful release notes
+
+Include:
+
+- pack ID and version;
+- release date and owner;
+- change classification;
+- affected modules and dependencies;
+- changed obligations or persona perspectives;
+- expected digest changes;
+- compatibility changes;
+- required consumer action;
+- migration and rollback guidance;
+- deprecation dates.
+
+The manifest remains strict, so keep this information in adjacent repository or catalogue records.
+
+## Deprecate safely
+
+Recommended practice:
+
+1. stop recommending the deprecated version to new projects;
+2. publish the supported replacement and migration difference;
+3. retain the old source long enough to interpret existing receipts and pins;
+4. notify known project owners;
+5. allow projects to review and schedule adoption;
+6. record exceptions for projects that must remain pinned;
+7. remove distribution only after the retention decision is explicit.
+
+Deprecation is not permission to delete project-owned materialised standards or personas.
+
+## Respond to a security or policy correction
+
+For an urgent correction:
+
+- publish a new immutable version;
+- identify affected versions and modules;
+- describe impact and required action without exposing exploit details unnecessarily;
+- provide a bounded comparison and recovery route;
+- notify project owners through the organisation's approved channel;
+- require each affected project to record its adoption or risk decision;
+- retain evidence of the response.
+
+Do not overwrite a previously published version in place. Existing digests and approval evidence must remain interpretable.
+
+## Maintenance checklist
+
+- [ ] Ownership and subject-matter review are current.
+- [ ] Identity and module semantics remain stable.
+- [ ] Version reflects consequence, not file count.
+- [ ] Required and optional combinations were tested.
+- [ ] Dependencies and compatibility were resolved.
+- [ ] Release notes explain project action.
+- [ ] Previous receipts and pins remain interpretable.
+- [ ] No project is silently upgraded.
+
+## Related guides
+
+- [Blueprint validation and troubleshooting](validation-and-troubleshooting.md)
+- [Internal Blueprint catalogue](internal-blueprint-catalogue.md)
+- [Policy Pack Authoring Guide](../policies/policy-pack-authoring-guide.md)
+- [Governance Owner Guide to Policy Design Gates](../policies/governance-owner-guide.md)
+- [Organisation rollout](../organisation-rollout-guide.md)
+- [Human approval and assurance](../human-approval-and-assurance-guide.md)