From 8886c90e2c9235e82403a7ad8cf7737e3a3e6a9e Mon Sep 17 00:00:00 2001 From: Dan Risacher Date: Fri, 7 Aug 2026 15:39:20 -0400 Subject: [PATCH 1/2] Point the Early Adopter Stories nav entry at the story The nav listed the Army SMDCoE story as plays/army-smdcoe-play.md, but the file is docs/stories/army-smdcoe.md. MkDocs cannot resolve a nav target that does not exist, so it emitted the raw path as the link href and the navbar sent readers to /AI4SDLC/plays/army-smdcoe-play.md, which 404s -- both because no such page exists and because this site uses directory URLs, so no .md URL ever resolves. The story itself built and deployed correctly the whole time; only the way in was broken. MkDocs did warn about this ("A reference to 'plays/army-smdcoe-play.md' is included in the 'nav' configuration, which is not found in the documentation files"), but nothing surfaced it: code.mil's scripts/test runs mkdocs with --quiet, and its htmlproofer sweep excludes /AI4SDLC/ entirely. --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index ea0a1dd..1bdfe75 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -41,7 +41,7 @@ nav: - AI Workflow Design: plays/ai_sdlc_workflows-play.md - IDE Security: plays/ide-security.md - Early Adopter Stories: - - Army SMDCoE: plays/army-smdcoe-play.md + - Army SMDCoE: stories/army-smdcoe.md - Patterns: - Human-Machine Interaction Patterns: plays/human-machine-patterns.md - Practices: From 329b25a187c8d8a5d9245e3276387268df11fe69 Mon Sep 17 00:00:00 2001 From: Dan Risacher Date: Fri, 7 Aug 2026 15:43:04 -0400 Subject: [PATCH 2/2] Repair broken documentation links MkDocs was emitting nine link warnings. None failed the build, because code.mil runs the mkdocs build with --quiet and excludes /AI4SDLC/ from its htmlproofer sweep, so nothing surfaced them. Four links pointed at 'ai_sdlc_workflows_play.md'. The file is 'ai_sdlc_workflows-play.md' -- a hyphen, not an underscore, before "play". Four more in aiswec_play-outline.md were still written for the path the file had before it moved into docs/plays/, and carried a '../../docs/' prefix that resolves nowhere from its current location. The authoring notes in that file recorded the move as pending and prescribed exactly this fix, so this applies it and updates the note to describe where the file now lives. One pointed at 'resources/risk-reference.md', which does not exist anywhere in the repository. The surrounding sentence describes the Risk Reference Companion as upcoming, so the reference stays and only the dead link is removed; it can be linked once the document lands. Also repairs a tenth link that MkDocs does not check, because it validates Markdown targets and this one is a directory: documentation-play.md pointed at '../resources/', which has no index page and returns 404 on the live site today. It now links the two resources that exist. Verified by crawling the built site: 1631 internal links, none broken. --- docs/plays/aiswec_play-outline.md | 12 ++++++------ docs/plays/code-gen-play.md | 2 +- docs/plays/defining_your_why_play-outline.md | 2 +- docs/plays/documentation-play.md | 2 +- docs/plays/protovibe_play.md | 4 ++-- 5 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/plays/aiswec_play-outline.md b/docs/plays/aiswec_play-outline.md index 0ee1c0b..6149c1c 100644 --- a/docs/plays/aiswec_play-outline.md +++ b/docs/plays/aiswec_play-outline.md @@ -34,7 +34,7 @@ Play series: AI4SDLC | Status: Draft | Target publish: Late 2026 This play is the AI-SWEC question set — the full pre-event (B-xx) and post-event (P-xx) instrument — with guidance on how to conduct the assessment and use the responses to build an ADR. -Read the [Defining Your Why](../../docs/plays/defining_your_why_play-outline.md) play first. That play explains the Before/Measure/After arc, the Go/Slow/No-Go decision framework, and when and why to use AI-SWEC. This play is the instrument itself. +Read the [Defining Your Why](defining_your_why_play-outline.md) play first. That play explains the Before/Measure/After arc, the Go/Slow/No-Go decision framework, and when and why to use AI-SWEC. This play is the instrument itself. --- @@ -359,7 +359,7 @@ DORA — Team Process Metrics: *How AI-SWEC responses populate the ADR. The B-xx questions build it; the P-xx questions complete it.* -The ADR is initiated at the Go/Slow/No-Go decision point — before the pilot begins. See the [Defining Your Why](../../docs/plays/defining_your_why_play-outline.md) play, Section 6.1 for the ADR Jumpstart fields and initiation logic. This section shows which AI-SWEC questions feed which ADR fields. +The ADR is initiated at the Go/Slow/No-Go decision point — before the pilot begins. See the [Defining Your Why](defining_your_why_play-outline.md) play, Section 6.1 for the ADR Jumpstart fields and initiation logic. This section shows which AI-SWEC questions feed which ADR fields. | ADR Field | Pre-Event Source (B-xx) | Post-Event Source (P-xx) | | --- | --- | --- | @@ -374,7 +374,7 @@ The ADR is initiated at the Go/Slow/No-Go decision point — before the pilot be | Human Impact | — | P-19, P-22, P-15, P-23, P-34, P-35 | | Solution Fit Assessment | — | P-27, P-12, P-13, P-16, P-17 | -See the [ADR template](../../docs/resources/ArchitecturalDecisionRecord.md) in docs/resources. +See the [ADR template](../resources/ArchitecturalDecisionRecord.md) in docs/resources. > **Author notes — Section 7:** > @@ -425,11 +425,11 @@ See the [ADR template](../../docs/resources/ArchitecturalDecisionRecord.md) in d **Related Plays:** -- [Defining Your Why](../../docs/plays/defining_your_why_play-outline.md) — read first; the adoption decision framework, Before/Measure/After arc, Go/Slow/No-Go, and ADR Jumpstart +- [Defining Your Why](defining_your_why_play-outline.md) — read first; the adoption decision framework, Before/Measure/After arc, Go/Slow/No-Go, and ADR Jumpstart - [AI Autonomy Continuum](ai-autonomy_continuum_play.md) — pattern selection; agentic governance readiness; P1-P4 patterns - [AI Autonomy Implementation Guide](ai-autonomy-implementation-guide.md) — pattern-specific readiness checklists - [Fundamentals for Designing an AI-Augmented Tool Chain](fundamentals-play.md) — hosting models, tool selection -- [AI Workflow Design and Governance](ai_sdlc_workflows_play.md) — workflow governance, skills file governance +- [AI Workflow Design and Governance](ai_sdlc_workflows-play.md) — workflow governance, skills file governance **Key References:** @@ -468,7 +468,7 @@ This play is the structured assessment instrument behind the AI4SDLC adoption de - **Copyright:** Copyright block is at the top of the document and on Sections 5 and 6 headers. Do not remove or weaken these notices in prose. - **Verification required:** All B-xx and P-xx question IDs and text must be verified against `AI-SWEC_Beta_DecisionTool.xlsx` in `local_working_files/defining_why/` before prose draft. The August 2025 PDF is the source for this outline; the Excel is authoritative. - **No duplication with Defining Your Why.** This play does not explain the Before/Measure/After arc, Go/Slow/No-Go logic, adoption prerequisites, DORA metrics, field examples, or the ADR initiation point. Reference and link to the Defining Your Why play for all of that. -- **Link paths (update when moved to docs/plays/):** Links in this file are set for `local_working_files/defining_why/`. When moved to `docs/plays/`, shorten as follows: `../../docs/plays/defining_your_why_play-outline.md` → `defining_your_why_play-outline.md`; `../../docs/resources/ArchitecturalDecisionRecord.md` → `../resources/ArchitecturalDecisionRecord.md`. Companion play links (Section 10) will also need `../../docs/plays/` prefix removed once those plays exist in docs/plays/. +- **Link paths:** This file now lives in `docs/plays/`, and its links are set for that location. Relative links to sibling plays are bare filenames; links to `docs/resources/` are prefixed `../resources/`. - **No score, no maturity model.** Never frame sections as scoring. Never imply a threshold that constitutes passing. - **Online tool:** Describe as "in development" with intended capability. Do not imply availability. - **Framework evolution:** AI-SWEC is Beta as of August 2025. State that the question set may be refined. diff --git a/docs/plays/code-gen-play.md b/docs/plays/code-gen-play.md index ff033a0..8ed6159 100644 --- a/docs/plays/code-gen-play.md +++ b/docs/plays/code-gen-play.md @@ -450,7 +450,7 @@ These variations can affect everything from code style and verbosity to security - **Provide role-specific tradecraft guidance** for approved tools, including prompt examples, review checklists, and lessons learned from secure use in operational contexts. -> For systemic risk guidance, see the upcoming [Risk Reference Companion](../resources/risk-reference.md) where “Tool Drift”, “Model Fragmentation”, and "Prompt Misuse" are addressed in more depth. +> For systemic risk guidance, see the upcoming Risk Reference Companion, where “Tool Drift”, “Model Fragmentation”, and "Prompt Misuse" are addressed in more depth. ---- diff --git a/docs/plays/defining_your_why_play-outline.md b/docs/plays/defining_your_why_play-outline.md index 7b33029..51f5d69 100644 --- a/docs/plays/defining_your_why_play-outline.md +++ b/docs/plays/defining_your_why_play-outline.md @@ -443,7 +443,7 @@ The AI-SWEC B-xx question set maps directly to the Context, Decision, and Conseq - [AI Autonomy Continuum](ai-autonomy_continuum_play.md) — pattern selection, autonomy health index, shadow AI governance - [AI Autonomy Implementation Guide](ai-autonomy-implementation-guide.md) — pattern-specific readiness checklists, health metrics - [Fundamentals for Designing an AI-Augmented Tool Chain](fundamentals-play.md) — hosting models, trust architecture -- [AI Workflow Design and Governance](ai_sdlc_workflows_play.md) — workflow governance, review gates, skills file governance +- [AI Workflow Design and Governance](ai_sdlc_workflows-play.md) — workflow governance, review gates, skills file governance - [Requirements Engineering with AI Assistance](requirements_engineering_play.md) — maturity indicators, traceability - [AI-Augmented Testing](testing-play.md) — test coverage metrics, defect escape rate, test-from-code anti-pattern - [Code Completion and Generation](code-gen-play.md) — DevSecOps baseline requirements, code generation risk diff --git a/docs/plays/documentation-play.md b/docs/plays/documentation-play.md index d9aac83..d2b324e 100644 --- a/docs/plays/documentation-play.md +++ b/docs/plays/documentation-play.md @@ -456,7 +456,7 @@ Teams new to AI-assisted documentation should adopt an incremental approach: Reusable templates for common documentation artifacts (ADRs, API specs, runbooks, release notes) are being developed for the AI4SDLC resource library. These will include prompt patterns and validation checklists aligned with the GenAI patterns in this play. -*See [Resources](../resources/) for available templates as they are published.* +*See the [Architectural Decision Record](../resources/ArchitecturalDecisionRecord.md) and [play template](../resources/template.md) for what is available so far.* --- diff --git a/docs/plays/protovibe_play.md b/docs/plays/protovibe_play.md index 2137b08..cc46035 100644 --- a/docs/plays/protovibe_play.md +++ b/docs/plays/protovibe_play.md @@ -39,7 +39,7 @@ Naming the artifact matters more than naming the activity. The governance questi ### 1.2 Comprehension Is Its Own Axis -Proto-vibing is not a point on the task-level autonomy scale in the [AI & Agentic Workflow Design and Governance](ai_sdlc_workflows_play.md) play. That scale governs what an agent is *permitted* to do. Comprehension describes what the human *understood*. Every autonomy level presumes a human who comprehends, so a developer at Level 1 who applies a draft without reading it has satisfied the framework and learned nothing. That play already flags the same hazard when it warns that approving outputs without meaningful evaluation turns human-in-the-loop review into a formality. +Proto-vibing is not a point on the task-level autonomy scale in the [AI & Agentic Workflow Design and Governance](ai_sdlc_workflows-play.md) play. That scale governs what an agent is *permitted* to do. Comprehension describes what the human *understood*. Every autonomy level presumes a human who comprehends, so a developer at Level 1 who applies a draft without reading it has satisfied the framework and learned nothing. That play already flags the same hazard when it warns that approving outputs without meaningful evaluation turns human-in-the-loop review into a formality. Agent count is likewise orthogonal. One agent whose output nobody reads produces a protovibe. Twelve agents orchestrated against a spec, with an engineer owning the design, do not. Scaling the mechanism does not change the comprehension question, though it does raise the containment requirement (Section 6). @@ -179,7 +179,7 @@ Proto-vibing is groundbreaking potential with limitations and challenges. Run th ### Related Plays and Resources - [Leading Practices for Code Completion and Generation](code-gen-play.md) -- [AI & Agentic Workflow Design and Governance](ai_sdlc_workflows_play.md) +- [AI & Agentic Workflow Design and Governance](ai_sdlc_workflows-play.md) - [AI Autonomy Continuum](ai-autonomy_continuum_play.md) - [Requirements Engineering](requirements_engineering_play.md) - [Architectural Decision Records](../resources/ArchitecturalDecisionRecord.md)