Add golden paths based on policy

golden paths/01-start-a-new-repository.md

@@ -0,0 +1,58 @@
+# Golden Path: Start a New Repository
+
+Use this when a team is creating a new service or standing up a new codebase.
+
+## Outcome
+
+You finish with a repository that is ready for collaborative delivery, review,
+automation, and secure change control.
+
+## Steps
+
+1. Create the repository in an approved source control platform.
+   Use GitHub under the official UKHO organisation where possible. Set the
+   default branch to `main`.
+2. Add the baseline repository files.
+   Include `README.md`, `CONTRIBUTING.md`, `LICENSE`, `SECURITY.md`, and
+   `CODEOWNERS`.
+3. Set repository access through teams, not individuals.
+   Avoid creating a single point of failure in repository ownership and access.
+4. Enable branch protection on `main`.
+   Require pull requests, approvals, conversation resolution, required status
+   checks, and up-to-date branches before merge.
+5. Decide the merge strategy.
+   Prefer `Squash and merge` so the main branch stays clean and pull requests
+   remain the primary review record.
+6. Enable code security automation.
+   Turn on dependency alerts and automated dependency updates where supported.
+7. Add build and release definitions as code.
+   Store pipeline YAML in source control from the start.
+8. Define working conventions.
+   Use GitHub Flow, branch names of the form
+   `{ticket_number}/{type}-{description}`, and concise commit messages that
+   answer `Applying this change will...`.
+9. Confirm the team definition of done.
+   Include code review, unit testing, documentation, and security checks.
+
+## Exit Criteria
+
+- The repository lives in an approved source control platform.
+- `main` is protected.
+- Pull requests are the only route into `main`.
+- Ownership and access are team-based.
+- Required repository files exist.
+- Pipeline YAML is versioned with the code.
+
+## Policy Basis
+
+- [Source Control Policy](../software-engineering-policies/SourceControl/SourceControlPolicy.md)
+- [Repository Setup Policy](../software-engineering-policies/SourceControl/RepositorySetupPolicy.md)
+- [Branch Protection Policy](../software-engineering-policies/SourceControl/GitBranchProtectionPolicy.md)
+- [Code Review Policy](../software-engineering-policies/CodeReview/CodeReviewPolicy.md)
+
+## Anti-Patterns
+
+- Committing directly to `main`
+- Granting permanent write access to named individuals instead of teams
+- Creating a repository without baseline documentation
+- Keeping pipelines outside source control

golden paths/02-deliver-a-code-change.md

@@ -0,0 +1,62 @@
+# Golden Path: Deliver a Code Change
+
+Use this for routine feature, enhancement, and bug-fix delivery.
+
+## Outcome
+
+You move a change from idea to merge with review, traceability, tests, and
+security controls intact.
+
+## Steps
+
+1. Start from a tracked work item.
+   Every change should link back to a ticket or equivalent work item.
+2. Decide whether to pair.
+   Prefer paired working when it is practical, especially for implementation,
+   troubleshooting, and release activities.
+3. Create a short-lived branch from `main`.
+   Follow the pattern `{ticket_number}/{type}-{description}`.
+4. Keep commits small and clear.
+   Each commit message should answer `Applying this change will...`.
+5. Add or update automated tests with the code.
+   New non-trivial code must be covered by unit tests, and tests must be checked
+   in with the subject code.
+6. Keep test coverage healthy.
+   Any reduction in coverage should be justified.
+7. Update documentation as part of the same change.
+   If the change affects architecture, build, deployment, configuration, or
+   supportability, update the relevant system documentation.
+8. Open a pull request before merge.
+   Use a title based on the work item, describe what changed, why it changed,
+   how it was tested, and any important reviewer context.
+9. Complete peer review from source control.
+   All changes must be reviewed before merge, and review evidence must be kept
+   in the tooling.
+10. Resolve review feedback before merge.
+    Do not treat the work item as done until the review is complete and any
+    follow-up changes are finished.
+
+## Exit Criteria
+
+- The change is linked to a work item.
+- The branch follows the agreed naming convention.
+- Tests were added or updated with the code.
+- Documentation changed where needed.
+- The pull request was reviewed and approved.
+- The code merged through the protected mainline path.
+
+## Policy Basis
+
+- [Code Review Policy](../software-engineering-policies/CodeReview/CodeReviewPolicy.md)
+- [Pair Programming Policy](../software-engineering-policies/PairProgramming/PairProgrammingPolicy.md)
+- [Source Control Policy](../software-engineering-policies/SourceControl/SourceControlPolicy.md)
+- [Unit Testing Policy](../software-engineering-policies/UnitTesting/UnitTestingPolicy.md)
+- [System Documentation Policy](../software-engineering-policies/SystemDocumentation/SystemDocumentationPolicy.md)
+- [Test Strategy](../quality-assurance/test-strategy.md)
+
+## Anti-Patterns
+
+- Large pull requests with unrelated changes
+- Review outside source control
+- Merging before review completes
+- Adding functional code without automated tests

golden paths/03-release-through-a-pipeline.md

@@ -0,0 +1,63 @@
+# Golden Path: Release Through a Pipeline
+
+Use this when defining or evolving a build and release pipeline for a UKHO
+digital product.
+
+## Outcome
+
+You operate a pipeline that is automated, repeatable, secure, and controlled.
+
+## Steps
+
+1. Store the pipeline as code.
+   Use YAML compatible with Azure Pipelines or GitHub workflows.
+2. Model the minimum environment path.
+   Plan for at least development or engineering, formal test, and live.
+3. Keep environments aligned.
+   Treat the three-environment model as the minimum expected baseline for current
+   and future products unless a justified exception exists.
+4. Use approved secret handling.
+   Store non-secret values in a standard variable library and back secrets with
+   Azure Key Vault or the equivalent approved secret store.
+5. Automate quality gates in build.
+   Include dependency checks, SAST verification, container scanning where
+   relevant, and unit tests.
+6. Automate functional verification in non-live environments.
+   Run functional tests in development environments and broader integration or
+   end-to-end coverage in formal test environments.
+7. Protect the release path to production.
+   Production deployments should only come from `main`, and `main` must be
+   protected by pull request review and required checks.
+8. Set approval controls deliberately.
+   Prefer approvals on service connections and variable libraries instead of
+   relying only on environment approvals in YAML.
+9. Design for idempotency and loose coupling.
+   The pipeline should be repeatable and each service should be deployable in
+   isolation.
+10. Threat model the pipeline.
+    Treat the pipeline itself as an attack surface and review threats as the
+    design evolves.
+
+## Exit Criteria
+
+- Pipeline YAML is in source control.
+- The minimum environment flow exists.
+- Secrets are not stored directly in the pipeline.
+- Build and release checks are automated.
+- Production deploys only from `main`.
+- Threat modelling has been considered for the pipeline design.
+
+## Policy Basis
+
+- [Baseline Pipeline Policy](../software-engineering-policies/Pipelines/Baseline_Policy.md)
+- [Source Control Policy](../software-engineering-policies/SourceControl/SourceControlPolicy.md)
+- [Branch Protection Policy](../software-engineering-policies/SourceControl/GitBranchProtectionPolicy.md)
+- [Secure Development Policy](../software-engineering-policies/SecureDevelopment/SecureDevelopmentPolicy.md)
+- [Test Strategy](../quality-assurance/test-strategy.md)
+
+## Anti-Patterns
+
+- Manual release steps that could be automated
+- Secret values embedded in YAML
+- Deploying to production from feature branches
+- Pipelines that depend on another product pipeline to succeed

golden paths/04-adopt-or-update-a-dependency.md

@@ -0,0 +1,79 @@
+# Golden Path: Adopt or Update a Dependency
+
+Use this when introducing a new third-party package, upgrading an existing one,
+or deciding whether an open-source component is acceptable.
+
+## Outcome
+
+You can adopt or update a dependency with licensing, maintenance, and security
+checks completed before release, with remediation and exceptions tracked in an
+auditable way.
+
+## Steps
+
+1. Confirm the dependency is necessary.
+   Reuse is encouraged, but the package should solve a real problem better than
+   building and maintaining custom code.
+2. Validate the package source.
+   Use an approved package management tool or repository.
+3. Check the license.
+   The license must be on the approved list or formally escalated for review.
+4. Review open-source suitability.
+   Consider governance, maintenance activity, contribution model, maturity, and
+   whether the package is effectively open-core.
+5. Assess security exposure.
+   Cross-reference known vulnerabilities and ensure the designated dependency
+   scanning tool runs before production release.
+6. Ensure active dependency management tooling is enabled.
+   Use Snyk, Dependabot, or both, and confirm dependency checks are active for
+   the repository. Enable Dependabot alerts, security updates, and version
+   updates where applicable.
+7. Set or confirm the failure threshold.
+   The team should agree what vulnerability level prevents release and must be
+   able to prove the pipeline blocks release when that threshold is breached.
+8. Prioritise remediation by severity and business impact.
+   Assess and remediate dependency vulnerabilities in line with internal
+   vulnerability management policy timescales (POL218).
+9. Track remediation in the team backlog.
+   Link remediation work items to pull requests so there is a clear audit trail
+   from issue discovery to fix.
+10. Record exceptions explicitly.
+   If a vulnerability is suppressed or release proceeds with known risk, record
+   the reason, reviewer context, and next review date where appropriate.
+11. Escalate when timelines cannot be met.
+    If remediation cannot be delivered in policy timescales, define interim
+    mitigations, assign an owner, and escalate through the Security Champion
+    and/or Lead Technical Security Engineer (Security).
+12. Put the change through normal review.
+   Third-party component changes must be reviewed by the Lead Engineer.
+13. Keep dependency evidence buildable and reportable.
+   It must be possible to report on included licenses at build time.
+
+## Exit Criteria
+
+- The package comes from an approved source.
+- The license is approved or formally excepted.
+- Dependency and vulnerability checks are active in the repository.
+- Snyk, Dependabot, or both are configured and operating.
+- The release gate for vulnerable dependencies is defined.
+- Remediation is tracked in backlog items linked to pull requests.
+- Exceptions include justification, owner, and review date.
+- Lead Engineer review has happened for the dependency change.
+
+## Policy Basis
+
+- [Open Source Use Policy](../software-engineering-policies/OpenSourceUse/OpenSourceUsePolicy.md)
+- [Third-Party Licensing Policy](../software-engineering-policies/ThirdPartyLicensing/ThirdPartyLicensingPolicy.md)
+- [Secure Development Policy](../software-engineering-policies/SecureDevelopment/SecureDevelopmentPolicy.md)
+- [Baseline Pipeline Policy](../software-engineering-policies/Pipelines/Baseline_Policy.md)
+- [Managing Dependencies](../security/DependencyManagement/ManagingDependencies.md)
+- [Managing Security Concerns](../security/ManagingSecurityConcerns/ManagingSecurityConcerns.md)
+
+## Anti-Patterns
+
+- Pulling packages directly from unapproved sources
+- Adding packages without checking licenses
+- Running with dependency tooling disabled on active repositories
+- Ignoring vulnerability scan failures near release
+- Deferring remediation without tracked rationale and mitigations
+- Suppressing vulnerabilities without an auditable rationale

golden paths/05-document-and-hand-over-a-service.md

@@ -0,0 +1,52 @@
+# Golden Path: Document and Hand Over a Service
+
+Use this when a service is new, significantly changed, or being handed over to a
+support team.
+
+## Outcome
+
+You leave behind enough accurate documentation and non-functional evidence for a
+delivery or support team to run and change the service safely.
+
+## Steps
+
+1. Capture the essential system view.
+   Document the high-level architecture, build process, deployment approach,
+   configuration model, and any practical guidance needed to get productive.
+2. Keep the documentation with the audience.
+   Store it where the delivery and support teams will naturally find and review
+   it.
+3. Treat documentation like code.
+   Raise documentation changes through peer review with the implementation work.
+4. Confirm non-functional requirements early.
+   Make sure NFRs exist at the start of the work. If they do not, involve the
+   solution architect.
+5. Revisit NFRs during delivery.
+   If they evolve, update the solution and evidence rather than deprioritising
+   them.
+6. Align with the intended support team.
+   Validate any support-owned operational requirements before handover.
+7. Demonstrate sign-off evidence.
+   Handover should include proof that the relevant NFRs have been met.
+8. Update the team definition of done.
+   Ensure documentation and NFR evidence remain part of normal delivery, not a
+   one-off exercise.
+
+## Exit Criteria
+
+- System documentation exists and is current.
+- Documentation changes were peer reviewed.
+- NFRs are identified and evidenced.
+- The support team can accept the handover without missing prerequisite detail.
+
+## Policy Basis
+
+- [System Documentation Policy](../software-engineering-policies/SystemDocumentation/SystemDocumentationPolicy.md)
+- [NFR Policy](../software-engineering-policies/NFRs/NFRPolicy.md)
+- [Code Review Policy](../software-engineering-policies/CodeReview/CodeReviewPolicy.md)
+
+## Anti-Patterns
+
+- Treating handover documentation as an afterthought
+- Keeping key run or deployment knowledge only in people’s heads
+- Deferring NFR evidence until the end of delivery

golden paths/06-handle-defects-security-and-technical-debt.md

@@ -0,0 +1,65 @@
+# Golden Path: Handle Defects, Security Concerns and Technical Debt
+
+Use this when a problem is discovered in delivery or support and the team needs a
+consistent route to record, prioritise, fix, or consciously carry the risk.
+
+## Outcome
+
+You create traceable records for defects, security concerns, and technical debt,
+and you manage each through the correct workflow.
+
+## Steps
+
+1. Classify the issue correctly.
+   Decide whether it is a standard defect, a security concern, technical debt,
+   or a combination.
+2. Log it in the team’s tracking system.
+   Every team must have an effective defect management workflow, and security
+   concerns should live in the same work tracking system.
+3. Use the correct ticket shape.
+   Security concerns should be raised as a `Risk` with category `Security`.
+   Technical debt not being resolved in the current sprint should be raised as a
+   `Technical debt` work item.
+4. Record minimum useful detail.
+   Include affected service, a clear description, reproduction details where
+   possible, stakeholders, and supporting evidence.
+5. Assess and prioritise quickly.
+   Security concerns require an initial assessment within two working days and
+   should be reviewed on the team’s normal delivery cadence.
+6. Fix through the normal engineering path.
+   Apply code review, automated testing, and pipeline checks to the remediation.
+7. Retest after remediation.
+   If tooling or testing exposed the issue, rerun the same checks to confirm it
+   is resolved and nothing new has been introduced.
+8. Update the record with evidence.
+   Add links to pull requests, test results, pipeline runs, or decisions to
+   accept risk.
+9. Escalate when the risk is higher than routine delivery can absorb.
+   Work with the Security Champion, IT Security Team, and risk owner where
+   required.
+10. Keep unresolved debt visible.
+    If a defect or risk is knowingly left in place, record it as technical debt
+    where the policy requires and keep it in the register.
+
+## Exit Criteria
+
+- The issue is logged in the correct workflow.
+- Security items have an assessment and owner.
+- Fixes are evidenced by normal engineering controls.
+- Unresolved debt or accepted risk is explicitly recorded.
+
+## Policy Basis
+
+- [Defect Management Policy](../software-engineering-policies/DefectManagement/DefectManagementPolicy.md)
+- [Managing Security Concerns](../security/ManagingSecurityConcerns/ManagingSecurityConcerns.md)
+- [Secure Development Policy](../software-engineering-policies/SecureDevelopment/SecureDevelopmentPolicy.md)
+- [Technical Debt Policy](../software-engineering-policies/TechnicalDebt/TechnicalDebtPolicy.md)
+- [Code Review Policy](../software-engineering-policies/CodeReview/CodeReviewPolicy.md)
+- [Unit Testing Policy](../software-engineering-policies/UnitTesting/UnitTestingPolicy.md)
+
+## Anti-Patterns
+
+- Fixing production issues without creating a traceable record
+- Treating security concerns as ordinary bugs with no risk assessment
+- Leaving accepted debt undocumented
+- Closing an issue without rerunning the check that found it