fix(traceability): fix all markdownlint errors in documentation

Fix 1,205 MD060 table alignment errors, MD040 missing code fence
languages, MD025 multiple H1 headings, and MD041 missing first-line H1
across all 17 markdown files in scripts/aidlc-traceability/.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Author: harmjeff

scripts/aidlc-traceability/LEGAL_DISCLAIMER.md

@@ -1,6 +1,8 @@
+# Legal Disclaimer
+
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

scripts/aidlc-traceability/README.md

@@ -118,7 +118,7 @@ Each agent is focused on a specific artifact pair, preventing context pollution
 
 ## Project Structure
 
-```
+```text
 AIDLC-Traceability/
 ├── src/traceability/        # Main implementation
 │   ├── cli.py              # Click-based CLI
@@ -175,6 +175,7 @@ uv sync
 ### Markdown Report
 
 The markdown report includes:
+
 - Summary statistics (artifact counts, coverage percentages)
 - Complete traceability matrix showing all relationships
 - Gap analysis highlighting orphaned artifacts
@@ -183,6 +184,7 @@ The markdown report includes:
 ### HTML Report
 
 The HTML report provides:
+
 - Interactive dark mode toggle
 - Resizable sidebar for navigation
 - Collapsible sections
@@ -199,4 +201,4 @@ This tool generates traceability documentation to support your development and c
 
 ## License
 
-This project is licensed under the [MIT License](LICENSE).
+This project is licensed under the [MIT License](LICENSE).

scripts/aidlc-traceability/docs/ai-compliance.md

@@ -7,18 +7,19 @@ Copyright (c) 2026 AIDLC Traceability Tool Contributors
 
 ## GenAI Use Case Classification
 
-| Attribute | Value |
-|-----------|-------|
-| **Use Case** | Development tooling — automated traceability analysis |
-| **Risk Level** | LOW |
-| **Domain** | Software engineering documentation |
-| **Decision Impact** | Advisory only — generates reports for human review |
-| **PII Processing** | None — tool processes code and documentation artifacts |
+| Attribute           | Value                                                                 |
+| ------------------- | --------------------------------------------------------------------- |
+| **Use Case**        | Development tooling — automated traceability analysis                 |
+| **Risk Level**      | LOW                                                                   |
+| **Domain**          | Software engineering documentation                                    |
+| **Decision Impact** | Advisory only — generates reports for human review                    |
+| **PII Processing**  | None — tool processes code and documentation artifacts                |
 | **Safety-Critical** | No — tool does not make health, financial, legal, or safety decisions |
 
 ### Risk Justification
 
 This is a **low-risk** GenAI use case because:
+
 1. The AI generates suggested relationships between development artifacts (requirements, stories, code)
 2. All AI output is validated against known artifact IDs before inclusion in reports
 3. Reports are for informational and documentation purposes; no automated decisions are made
@@ -29,59 +30,60 @@ This is a **low-risk** GenAI use case because:
 
 ### Amazon Bedrock — Claude Sonnet
 
-| Attribute | Value |
-|-----------|-------|
-| **Provider** | Anthropic (via Amazon Bedrock marketplace) |
-| **Model** | Claude Sonnet 4 (`us.anthropic.claude-sonnet-4-20250514-v1:0`) |
-| **Access Method** | Amazon Bedrock API (on-demand) |
-| **Data Retention** | None — Amazon Bedrock does not retain customer prompt/completion data |
-| **Training Data Usage** | None — customer data is not used for model training |
+| Attribute               | Value                                                                 |
+| ----------------------- | --------------------------------------------------------------------- |
+| **Provider**            | Anthropic (via Amazon Bedrock marketplace)                            |
+| **Model**               | Claude Sonnet 4 (`us.anthropic.claude-sonnet-4-20250514-v1:0`)        |
+| **Access Method**       | Amazon Bedrock API (on-demand)                                        |
+| **Data Retention**      | None — Amazon Bedrock does not retain customer prompt/completion data |
+| **Training Data Usage** | None — customer data is not used for model training                   |
 
 ### Legal Approval and Right to Use
 
-| Component | License/Terms | Approval Status |
-|-----------|--------------|-----------------|
-| **Claude Sonnet (via Amazon Bedrock)** | [AWS Service Terms](https://aws.amazon.com/service-terms/) — Amazon Bedrock section | Pre-approved: Amazon Bedrock marketplace models are available to all AWS customers with Amazon Bedrock access. No separate Anthropic license required. |
-| **Strands Agents SDK** (`strands-agents`) | Apache License 2.0 ([source](https://github.com/strands-agents/strands-agents)) | Pre-approved: Open-source, permissive license compatible with MIT. No usage restrictions or distribution limitations. |
-| **Strands Agents Tools** (`strands-agents-tools`) | Apache License 2.0 | Pre-approved: Same terms as strands-agents SDK. |
-| **boto3** (AWS SDK) | Apache License 2.0 | Pre-approved: Official AWS SDK, open source. |
+| Component                                         | License/Terms                                                                       | Approval Status                                                                                                                                        |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Claude Sonnet (via Amazon Bedrock)**            | [AWS Service Terms](https://aws.amazon.com/service-terms/) — Amazon Bedrock section | Pre-approved: Amazon Bedrock marketplace models are available to all AWS customers with Amazon Bedrock access. No separate Anthropic license required. |
+| **Strands Agents SDK** (`strands-agents`)         | Apache License 2.0 ([source](https://github.com/strands-agents/strands-agents))     | Pre-approved: Open-source, permissive license compatible with MIT. No usage restrictions or distribution limitations.                                  |
+| **Strands Agents Tools** (`strands-agents-tools`) | Apache License 2.0                                                                  | Pre-approved: Same terms as strands-agents SDK.                                                                                                        |
+| **boto3** (AWS SDK)                               | Apache License 2.0                                                                  | Pre-approved: Official AWS SDK, open source.                                                                                                           |
 
 **Organizational approval**: Users deploying this tool should verify that their organization's policies permit the use of Amazon Bedrock and the Claude model family. Many organizations pre-approve all Amazon Bedrock marketplace models under their AWS Enterprise Agreement.
 
 ## Third-Party Framework Usage
 
 ### Strands Agents SDK
 
-| Attribute | Value |
-|-----------|-------|
-| **Package** | `strands-agents` |
-| **License** | Apache License 2.0 |
-| **Source** | Open source |
-| **Purpose** | Agent orchestration framework for Amazon Bedrock model invocation |
+| Attribute         | Value                                                                    |
+| ----------------- | ------------------------------------------------------------------------ |
+| **Package**       | `strands-agents`                                                         |
+| **License**       | Apache License 2.0                                                       |
+| **Source**        | Open source                                                              |
+| **Purpose**       | Agent orchestration framework for Amazon Bedrock model invocation        |
 | **Data Handling** | SDK passes prompts to Amazon Bedrock API; no independent data collection |
 
 ## Implemented AI Security Controls
 
 The following security controls are implemented in `src/traceability/agent.py` and the pipeline:
 
-| Control | Implementation | File:Line |
-|---------|---------------|-----------|
-| **Input isolation** | Each of 4 agents receives only its relevant artifact pair; no cross-agent data leakage | `agent.py:86-170` |
-| **Static system prompts** | System prompts are hardcoded strings; no user input is injected into system prompts | `agent.py:86-170` |
-| **Output format enforcement** | Agents are instructed to respond in JSON only; non-JSON responses are discarded | `agent.py:173-228` |
-| **Artifact ID validation** | All `source_id` and `target_id` values validated against known parsed artifact IDs | `agent.py:189-215` |
-| **Invalid relationship filtering** | Relationships referencing non-existent artifacts are silently discarded and counted | `agent.py:205-215` |
-| **Output sanitization** | AI-generated text is not rendered as raw content; only validated artifact IDs are used to create graph edges. Report generators escape all artifact content via `html.escape()` before rendering | `generators/html.py:116-117` |
-| **Graceful degradation** | Amazon Bedrock failures are caught; pipeline falls back to heuristic-only analysis | `pipeline.py:229-234` |
-| **Data volume limits** | Source code reading limited to 30 files, 200 lines each | `agent.py:50-65` |
-| **No code execution** | No `eval()`, `exec()`, or dynamic code execution of AI responses | Verified by Bandit scan |
-| **Configurable opt-out** | AI analysis is fully optional via `--no-ai` flag | `cli.py:26` |
+| Control                            | Implementation                                                                                                                                                                                   | File:Line                    |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- |
+| **Input isolation**                | Each of 4 agents receives only its relevant artifact pair; no cross-agent data leakage                                                                                                           | `agent.py:86-170`            |
+| **Static system prompts**          | System prompts are hardcoded strings; no user input is injected into system prompts                                                                                                              | `agent.py:86-170`            |
+| **Output format enforcement**      | Agents are instructed to respond in JSON only; non-JSON responses are discarded                                                                                                                  | `agent.py:173-228`           |
+| **Artifact ID validation**         | All `source_id` and `target_id` values validated against known parsed artifact IDs                                                                                                               | `agent.py:189-215`           |
+| **Invalid relationship filtering** | Relationships referencing non-existent artifacts are silently discarded and counted                                                                                                              | `agent.py:205-215`           |
+| **Output sanitization**            | AI-generated text is not rendered as raw content; only validated artifact IDs are used to create graph edges. Report generators escape all artifact content via `html.escape()` before rendering | `generators/html.py:116-117` |
+| **Graceful degradation**           | Amazon Bedrock failures are caught; pipeline falls back to heuristic-only analysis                                                                                                               | `pipeline.py:229-234`        |
+| **Data volume limits**             | Source code reading limited to 30 files, 200 lines each                                                                                                                                          | `agent.py:50-65`             |
+| **No code execution**              | No `eval()`, `exec()`, or dynamic code execution of AI responses                                                                                                                                 | Verified by Bandit scan      |
+| **Configurable opt-out**           | AI analysis is fully optional via `--no-ai` flag                                                                                                                                                 | `cli.py:26`                  |
 
 For detailed technical documentation of these controls, see [docs/ai-security.md](ai-security.md).
 
 ## No Training Data Used
 
 This tool does not:
+
 - Train or fine-tune any AI models
 - Create or manage training datasets
 - Store AI interaction data for future training
@@ -95,11 +97,11 @@ The AI agents perform **artifact relationship mapping** — connecting requireme
 
 ### Potential Bias Vectors
 
-| Vector | Risk | Mitigation |
-|--------|------|-----------|
-| Naming bias | AI may favor artifacts with descriptive names over terse ones | Heuristic linker provides baseline; AI adds to it |
-| Language bias | Non-English artifact names may produce fewer matches | Not applicable — tool targets English-language AI-DLC projects |
-| Completeness bias | AI may over-connect well-documented artifacts, under-connect sparse ones | Gap analysis independently identifies unconnected artifacts |
+| Vector            | Risk                                                                     | Mitigation                                                     |
+| ----------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------- |
+| Naming bias       | AI may favor artifacts with descriptive names over terse ones            | Heuristic linker provides baseline; AI adds to it              |
+| Language bias     | Non-English artifact names may produce fewer matches                     | Not applicable — tool targets English-language AI-DLC projects |
+| Completeness bias | AI may over-connect well-documented artifacts, under-connect sparse ones | Gap analysis independently identifies unconnected artifacts    |
 
 ### Fairness Assessment
 

scripts/aidlc-traceability/docs/ai-security.md

@@ -12,47 +12,55 @@ This document describes the security controls applied to the AI-powered analysis
 ## Input Controls
 
 ### Prompt Construction
+
 - System prompts are static strings defined in `agent.py`; no user input is injected into system prompts
 - User artifact data (IDs, titles, descriptions) is included in the user message portion of the prompt
 - Each agent receives only the artifact types relevant to its analysis scope (e.g., the Req→Story agent only sees requirements and stories)
 
 ### Data Volume Limits
+
 - Component→Code agent limits source code reading to **30 files** and **200 lines per file**
 - Artifact lists are formatted as structured text (ID: Title format), not raw file contents
 - Boilerplate files are marked and excluded from detailed analysis
 
 ## Output Validation
 
 ### JSON Response Parsing
+
 - All agent responses are expected in JSON format with a defined schema
 - `_parse_agent_json()` in `agent.py` enforces the expected structure:
   - Must contain a `relationships` array with `source_id` and `target_id` fields
   - May contain an `insights` array of string observations
 
 ### Artifact ID Validation
+
 - Every `source_id` and `target_id` in AI-discovered relationships is validated against the set of known artifact IDs parsed in Stage 2
 - Relationships referencing non-existent artifact IDs are silently discarded
 - The count of invalid/discarded relationships is tracked and logged
 - This prevents the AI from hallucinating artifact IDs or injecting arbitrary nodes into the traceability graph
 
 ### Error Handling
+
 - JSON parse failures are caught; the pipeline continues with rule-based results only
 - Amazon Bedrock API errors (timeouts, throttling, auth failures) are caught and logged
 - No AI error causes the pipeline to fail; it degrades gracefully to heuristic-only analysis
 
 ## Prompt Injection Mitigations
 
 ### Scope Isolation
+
 - Four separate agents with focused system prompts prevent cross-concern contamination
 - Each agent can only produce relationships between its assigned artifact types
 - The Req→Story agent cannot create Component→Code relationships, and vice versa
 
 ### Output Format Enforcement
+
 - Agents are instructed to respond only in JSON format
 - Non-JSON responses are discarded entirely
 - The tool does not execute, eval, or interpret any text from AI responses as code
 
 ### Read-Only File Access
+
 - The `read_source_code_file` tool available to the Component→Code agent is read-only
 - It returns file content as a string; it cannot modify files
 - File paths are resolved relative to the project root

scripts/aidlc-traceability/docs/architecture.md

@@ -126,6 +126,7 @@ flowchart LR
 ```
 
 **Key properties:**
+
 - The tool only **reads** project files; it does not modify them
 - Reports are written to the local filesystem only
 - Amazon Bedrock calls are outbound HTTPS (TLS 1.2+) and only occur when AI is enabled
@@ -184,12 +185,12 @@ graph TB
 
 ## Technology Stack
 
-| Component | Technology | Purpose |
-|-----------|-----------|---------|
-| CLI | Click | Command-line interface |
-| Models | Pydantic | Data validation and serialization |
-| Graph | NetworkX | Directed graph for traceability relationships |
-| AI | Strands Agents + Amazon Bedrock | Optional relationship discovery |
-| AWS | boto3 | Amazon Bedrock API access |
-| Templates | Jinja2 (available) | Report template rendering |
-| Output | Rich | Terminal formatting |
+| Component | Technology                      | Purpose                                       |
+| --------- | ------------------------------- | --------------------------------------------- |
+| CLI       | Click                           | Command-line interface                        |
+| Models    | Pydantic                        | Data validation and serialization             |
+| Graph     | NetworkX                        | Directed graph for traceability relationships |
+| AI        | Strands Agents + Amazon Bedrock | Optional relationship discovery               |
+| AWS       | boto3                           | Amazon Bedrock API access                     |
+| Templates | Jinja2 (available)              | Report template rendering                     |
+| Output    | Rich                            | Terminal formatting                           |

scripts/aidlc-traceability/docs/bedrock-security.md

@@ -96,11 +96,11 @@ If temporary credentials are not available, use named profiles with access keys
 
 When AI analysis is enabled, the following data is sent to the Amazon Bedrock API:
 
-| Data Type | Content | Volume |
-|-----------|---------|--------|
-| Artifact summaries | IDs, titles, descriptions from parsed artifacts | All artifacts |
-| Source code snippets | File contents for Component→Code linking | Up to 30 files, 200 lines each |
-| System prompts | Agent instructions (static, no user data) | 4 prompts per run |
+| Data Type            | Content                                         | Volume                         |
+| -------------------- | ----------------------------------------------- | ------------------------------ |
+| Artifact summaries   | IDs, titles, descriptions from parsed artifacts | All artifacts                  |
+| Source code snippets | File contents for Component→Code linking        | Up to 30 files, 200 lines each |
+| System prompts       | Agent instructions (static, no user data)       | 4 prompts per run              |
 
 ### Data Residency