Enable lychee link checking and fix outdated documentation links

.cspell.json

@@ -172,6 +172,7 @@
     "gqlgen",
     "gradlew",
     "Grafana",
+    "gescazz",
     "gremcos",
     "gremgo",
     "Gruber",
@@ -263,6 +264,9 @@
     "mkdir",
     "mkdocs",
     "mlops",
+    "msal",
+    "MSAL",
+    "microsoftonline",
     "msrc",
     "MSRC",
     "MTBF",
@@ -334,6 +338,7 @@
     "pwsh",
     "pycodestyle",
     "pydocstyle",
+    "pygments",
     "Pyflakes",
     "pylint",
     "Pylint",

.gitattributes

@@ -16,4 +16,6 @@
 *.{md,[mM][dD]} text eol=lf
 *.{markdown,[mM][aA][rR][kK][dD][oO][wW][nN]} text eol=lf
 *.{markdn,[mM][aA][rR][kK][dD][nN]} text eol=lf
-*.{mdown,[mM][dD][oO][wW][nN]} text eol=lf
+*.{mdown,[mM][dD][oO][wW][nN]} text eol=lf
+
+.github/workflows/*.lock.yml linguist-generated=true merge=ours

.github/workflows/mkdocs.yml

@@ -15,12 +15,12 @@ jobs:
       pages: write
       pull-requests: write
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           submodules: "recursive"
           fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
       - name: Setup Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "3.13"
           architecture: "x64"
@@ -32,7 +32,7 @@ jobs:
       - name: Build site
         run: mkdocs build
       - name: Deploy
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./site

.gitignore

@@ -345,3 +345,6 @@ _site
 site/
 mkdocs/
 megalinter-reports/
+
+# Copilot agent tracking artifacts
+.copilot-tracking/

.mega-linter.yml

@@ -10,11 +10,16 @@ ENABLE_LINTERS:
   - MARKDOWN_MARKDOWNLINT
   - MARKDOWN_MARKDOWN_TABLE_FORMATTER
   - SPELL_CSPELL
+  - SPELL_LYCHEE
   - YAML_PRETTIER
   - YAML_YAMLLINT
-  - SPELL_LYCHEE
 
 SPELL_CSPELL_DISABLE_ERRORS: true
+# Lychee reports broken/blocked links but does not block CI: many external links
+# are valid in a browser yet rejected by, or flaky from, CI runner IPs (bot
+# protection, throttling, transient network errors). This matches the repo's PR
+# template guidance that link-check errors are expected and reviewed manually.
+SPELL_LYCHEE_DISABLE_ERRORS: true
 SHOW_ELAPSED_TIME: true
 FILEIO_REPORTER: false
 PARALLEL: true

.projector/workItemTemplates/engineering-fundamentals.yml

@@ -53,7 +53,7 @@ items:
               The process for design reviews should be documented and available
               to the whole team from the outset of the project. This story is to
               explicitly document that process in the team's [working
-              agreement](https://microsoft.github.io/code-with-engineering-playbook/agile-development/team-agreements/working-agreements/readme/)
+              agreement](https://microsoft.github.io/code-with-engineering-playbook/agile-development/team-agreements/working-agreement/)
             acceptanceCriteria:
               - Design review process is well-documented within the working
                 agreement

.projector/workItemTemplates/kubernetes-at-the-edge.yml

@@ -55,7 +55,7 @@ items:
                 description: Some container networking interfaces are only supported on certain OSes. There may also be special networking requirements
               - name: Evaluate CNI options
                 type: task
-                description: Calico provides a full networking stack but support on Windows has some limitations (https://docs.projectcalico.org/getting-started/windows-calico/limitations)
+                description: Calico provides a full networking stack but support on Windows has some limitations (https://docs.tigera.io/calico/latest/getting-started/kubernetes/windows-calico/limitations)
           - name: As a cluster operator, I want to ensure the network design does not interfere with application networking requirements so that applications can function properly on the cluster
             type: story
             acceptanceCriteria:

CONTRIBUTING.md

@@ -18,7 +18,7 @@ If you are unsure if your content will match this playbook, you are welcome to c
 ## General guidance
 
 - Quality is more important than quantity
-- Write in a way that you would want someone else to explain something to you. Use [`plain english`](http://www.plainenglish.co.uk/how-to-write-in-plain-english.html)
+- Write in a way that you would want someone else to explain something to you. Use [`plain language`](https://www.plainlanguage.gov/)
 - Be friendly, technical, professional and concise
 - Communicate as engineers, not marketing; we want to share what we learned, not "sell" our ideas
 - Don't recreate introductory content, link to it

README.md

@@ -23,7 +23,7 @@ If you do nothing else follow the [Engineering Fundamentals Checklist](docs/engi
 
 ## Structure of a Sprint
 
-A [breakdown of sections](docs/the-first-week-of-an-ise-project.md) according to the structure of an Agile sprint.
+A [project kickoff checklist](docs/start-here/project-kickoff-checklist.md) breaks down the playbook according to the structure of an Agile sprint.
 
 ## General Guidance
 
@@ -40,18 +40,21 @@ A [breakdown of sections](docs/the-first-week-of-an-ise-project.md) according to
 
 ## Resources
 
+* [Start Here](docs/start-here/README.md)
+* [AI-Assisted Engineering](docs/ai-assisted-engineering/README.md)
 * [Engineering Fundamentals Checklist](docs/engineering-fundamentals-checklist.md)
-* [The first week of an ISE project](docs/the-first-week-of-an-ise-project.md)
+* [Project Kickoff Checklist](docs/start-here/project-kickoff-checklist.md)
 
 ## Engineering Fundamentals
 
 * [Accessibility](docs/non-functional-requirements/accessibility.md)
+* [AI-Assisted Engineering](docs/ai-assisted-engineering/README.md)
 * [Agile Development](docs/agile-development/README.md)
 * [Automated Testing](docs/automated-testing/README.md)
 * [Code Reviews](docs/code-reviews/README.md)
 * [Continuous Delivery (CD)](docs/CI-CD/continuous-delivery.md)
 * [Continuous Integration (CI)](docs/CI-CD/continuous-integration.md)
-* [Design](docs/design/readme.md)
+* [Design](docs/design/README.md)
 * [Developer Experience](docs/developer-experience/README.md)
 * [Documentation](docs/documentation/README.md)
 * [Engineering Feedback](docs/engineering-feedback/README.md)

docs/.pages

@@ -1,10 +1,19 @@
 nav:
   - ISE Engineering Fundamentals Playbook: README.md
-  - Engineering Fundamentals Checklist: engineering-fundamentals-checklist.md
-  - The First Week of an ISE Project: the-first-week-of-an-ise-project.md
+  - Start Here: start-here
   - Who is ISE?: ISE.md
-  - Agile Development: agile-development
+  - Source Control: source-control
+  - Code Reviews: code-reviews
   - Automated Testing: automated-testing
   - CI/CD: CI-CD
-  - ...
+  - AI-Assisted Engineering: ai-assisted-engineering
+  - Security: security
+  - Observability: observability
+  - Agile Development: agile-development
+  - Design: design
+  - Developer Experience: developer-experience
+  - Documentation: documentation
+  - Engineering Feedback: engineering-feedback
+  - Non-Functional Requirements: non-functional-requirements
+  - ML & AI Projects: ml-and-ai-projects
   - UI/UX: UI-UX

docs/CI-CD/README.md

@@ -62,10 +62,19 @@ AppVeyor is another free CI service for open source projects which also supports
 
 AI tools can accelerate writing CI/CD pipeline YAML, jobs, and scripting snippets, but they must be used with explicit guardrails.
 
+For AI-powered applications, CI/CD also needs to validate the release artifacts that shape model behavior. We treat those artifacts as deployable units with owners, review history, rollback paths, and release gates, rather than as loose configuration. The artifacts we version this way include:
+
+- Prompts and safety policies
+- Model configuration and grounding indexes
+- Evaluation datasets and tool permission manifests
+
+Use the [AI-Assisted Engineering](../ai-assisted-engineering/README.md) guide for shared review, security, and traceability expectations when AI assistance is used to draft pipeline or release automation changes.
+
 Suggested workflow:
 - Use AI to draft CI/CD pipeline templates or job steps as a starting point (for example, generating a minimal GitHub Actions workflow).
 - Run the draft pipeline in a safe non-production environment or CI sandbox to validate syntax and basic behavior.
 - Require a human reviewer to validate generated steps for correctness, idempotence, and security implications (especially around secrets, permissions, and external actions).
+- For generative AI or agentic features, add automated evaluation, safety, grounding, and tool-permission checks before deployment to shared environments.
 - Add tests or smoke checks to the pipeline so changes can be validated automatically when the pipeline runs.
 - Promote approved templates into a central location (for example, `.github/workflows/` or a shared pipeline template repository) so teams reuse vetted, audited pipelines.
 
@@ -74,9 +83,12 @@ Guardrails and checklist (before merging AI-generated pipeline changes):
 - [ ] No secrets or credentials are hard-coded
 - [ ] Required linting and syntax checks pass locally and in CI
 - [ ] Security and license scans run and report no critical issues
+- [ ] Prompt, model, retrieval, safety, and tool-permission changes have evaluation evidence in the PR or release record
+- [ ] AI-enabled systems include evaluation gates for prompt, model, retrieval, and agent behavior, plus safety and regression checks, where applicable
 - [ ] Pipeline steps are idempotent and have clear rollback strategies where applicable
 - [ ] Generated content is annotated in the PR description (e.g., "AI-assisted draft") so reviewers know to apply extra scrutiny
 
 Notes:
 - AI-generated pipelines are excellent for reducing boilerplate and accelerating iteration, but they do not replace domain knowledge and security review.
 - Maintain a small set of vetted pipeline templates to reduce risk and improve reproducibility.
+- Use the [generative AI and agentic systems](../ml-and-ai-projects/generative-ai-and-agentic-systems.md#review-the-system-across-disciplines) guidance when a delivery pipeline changes prompts, grounding data, model settings, safety controls, or agent tools.

docs/CI-CD/continuous-integration.md

@@ -28,6 +28,10 @@ A robust build automation pipeline will:
 ### Code / Manifest Artifacts Required to Build Your Project Should be Maintained Within Your Projects Git Repository
 
 - CI provider-specific build pipeline definition(s) should reside within your project(s) git repository(s).
+- For generative AI and agentic applications, prompts, evaluation datasets, model configuration, grounding index definitions, safety policies, orchestration settings, and tool permission manifests should be maintained as versioned artifacts when they affect product behavior.
+- AI application artifacts should have the same review, test, rollback, and promotion expectations as application code and infrastructure templates.
+- Build validation should fail when prompt, model, retrieval, safety, or tool-permission changes are missing required evaluation evidence or schema checks.
+- Generated indexes, embeddings, and caches do not always belong in git, but the source data selection, transformation logic, index configuration, and release record should be traceable.
 
 ## Build Automation
 
@@ -82,6 +86,7 @@ Manage as much of the following as possible, as code:
 - Configuration Files
 - Configuration Management(ie environment variable automation via [terraform](https://github.com/microsoft/cobalt/blob/master/infra/modules/providers/azure/app-service/main.tf#L49))
 - Secret Management(ie creating Azure secrets via [terraform](https://github.com/microsoft/cobalt/blob/master/infra/templates/az-isolated-service-single-region/app.tf#L84))
+- AI application release artifacts, including prompt templates, eval suites, model settings, grounding index definitions, safety policies, and tool permission manifests
 - Cloud Resource Provisioning
 - Role Assignments
 - Load Test Scenarios
@@ -180,7 +185,7 @@ The schema has 30+ [validators](https://json-schema.org/tools?query=#validator)
 
 ## Integration Validation
 
-An effective way to identify bugs in your build at a rapid pace is to invest early into a reliable suite of automated tests that validate the baseline functionality of the system:
+An effective way to identify bugs in your build at a rapid pace is to invest early into a reliable suite of automated tests that validate the baseline functionality of the system. For the unit, integration, and end-to-end testing taxonomy and when to apply each, see the [automated testing fundamentals](../automated-testing/README.md#the-fundamentals) and the [end-to-end testing guide](../automated-testing/e2e-testing/README.md); the points below focus on wiring those tests into CI.
 
 ### End-to-End Integration Tests
 
@@ -216,6 +221,8 @@ An effective way to identify bugs in your build at a rapid pace is to invest ear
 
 ### Branch Policy Enforcement
 
+The canonical branch and pull request workflow lives in [source control](../source-control/README.md#creating-a-new-repository) and the [pull request guidance](../code-reviews/pull-requests.md). The CI-specific enforcement below ensures builds gate reviews and merges:
+
 - Protected [branch policies](https://help.github.com/en/github/administering-a-repository/about-protected-branches) should be setup on the main branch to ensure that CI stage(s) have passed prior to starting a code review. Code review approvers will only start reviewing a pull request once the CI pipeline run passes for the latest pushed git commit.
 - Broken builds should block pull request reviews.
 - Prevent commits directly into main branch.
@@ -233,7 +240,7 @@ In the spirit of transparency and embracing frequent communication across a dev
 ### Everyone Commits to the Git Repository Each Day
 
 - End of day checked-in code should contain unit tests at the minimum.
-- Run the build locally before checking in to avoid CI pipeline failure saturation. You should verify what caused the error, and try to solve it as soon as possible instead of committing your code. We encourage developers to follow a [lean SDLC principles](https://leankit.com/learn/lean/principles-of-lean-development/).
+- Run the build locally before checking in to avoid CI pipeline failure saturation. You should verify what caused the error, and try to solve it as soon as possible instead of committing your code. We encourage developers to follow a [lean SDLC principles](https://www.planview.com/resources/guide/lean-principles-101/).
 - Isolate work into small chunks which ties directly to business value and refactor incrementally.
 
 ## Isolated Environments

docs/README.md

@@ -9,6 +9,8 @@ An engineer working for a [ISE](ISE.md) project...
 
 This is our playbook. All contributions are welcome! Please feel free to submit a pull request to get involved.
 
+New here? Start with [How to use this playbook](start-here/README.md), then choose the guide for your role.
+
 ## Why Have a Playbook
 
 * To increase overall efficiency for team members and the whole team in general.
@@ -17,7 +19,9 @@ This is our playbook. All contributions are welcome! Please feel free to submit
 
 If you do nothing else follow the [Engineering Fundamentals Checklist](./engineering-fundamentals-checklist.md)!
 
-The [first week of an ISE project](./the-first-week-of-an-ise-project.md) is a breakdown of the sections of the playbook according to the structure of an Agile sprint.
+The [project kickoff checklist](./start-here/project-kickoff-checklist.md) is a breakdown of the sections of the playbook according to the structure of an Agile sprint.
+
+Use [AI-Assisted Engineering](./ai-assisted-engineering/README.md) as the shared baseline for using AI tools in engineering work while preserving human ownership, validation, security, privacy, accessibility, and project governance.
 
 ## General Guidance