@accelerationguy/accel 1.0.0

package/modules/radar/docs/standards/schemas.md

@@ -0,0 +1,269 @@
+# Schema Convention
+
+## Purpose
+
+Schemas define **HOW** agents produce output. They are the data contracts of the Radar framework — specifying field names, types, enums, validation rules, and structural constraints that make agent output composable, validatable, and machine-parseable.
+
+Without schemas, agent output drifts. One agent describes severity as "high", another as "H", another as "3". One agent includes a confidence score, another omits it. Schemas eliminate this drift by enforcing a single structural contract that all agents must conform to.
+
+Transform extends the schema set with remediation and change-risk schemas, while Core schemas remain shared across both Core and Transform systems.
+
+Radar uses approximately 9 schema files (5 Core + 4 Transform), each defining a reusable data structure consumed by agents and workflows.
+
+## Location
+
+```
+src/schemas/             (Core — shared by both systems)
+src/transform/schemas/   (Transform-specific)
+```
+
+## Naming
+
+**Pattern:** `{kebab-name}.md`
+
+**Examples:**
+- `finding.md`
+- `disagreement.md`
+- `confidence.md`
+- `signal.md`
+- `report-section.md`
+- `playbook.md`
+- `change-risk.md`
+- `intervention-level.md`
+- `verification-plan.md`
+
+## Required Structure
+
+Every schema file consists of YAML frontmatter followed by 4 mandatory sections.
+
+### Frontmatter (Required)
+
+```yaml
+---
+id: {kebab-name}
+name: [Schema Name]
+version: [semver]
+used_by: [which agents/workflows consume this schema]
+---
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | yes | Kebab-case identifier, must match filename without extension |
+| `name` | string | yes | Human-readable schema name |
+| `version` | string | yes | Semantic version (e.g., `1.0.0`). Increment on breaking changes. |
+| `used_by` | list of strings | yes | Agent IDs and/or workflow names that consume this schema |
+
+### Body Sections (All Required)
+
+| Section | Header | Purpose |
+|---------|--------|---------|
+| Purpose | `## Purpose` | What this schema represents, why it exists, when it's used. |
+| Template | `## Template` | The actual template in a fenced code block with typed placeholders. |
+| Field Reference | `## Field Reference` | Complete field documentation table. |
+| Validation Rules | `## Validation Rules` | Numbered list of constraints that must hold for a valid instance. |
+| Examples | `## Examples` | One or more correctly filled instances demonstrating proper usage. |
+
+## Cross-References
+
+| Direction | What | How |
+|-----------|------|-----|
+| Referenced BY | Agent assembly manifests (`src/agents/`) | `schemas.output`, `schemas.confidence`, `schemas.signal_input` fields |
+| Referenced BY | Workflows (`src/workflows/`) | For output validation steps |
+| Referenced BY | Transform workflows (`src/transform/workflows/`) | Transform workflows reference Transform schemas for output validation |
+| Does NOT reference | Personas, domains, tools | Schemas are universal contracts, independent of who fills them or what data feeds them. **Exception:** Transform schemas may reference Core schemas (e.g., playbook schema references finding schema's `finding_id` format) |
+
+## Example Skeleton
+
+````markdown
+---
+id: finding
+name: Finding
+version: 1.0.0
+used_by: [security-engineer, principal-engineer, sre, data-engineer, api-designer]
+---
+
+## Purpose
+
+[What this schema represents and when it's used.
+
+Example: "A Finding is a single identified issue, risk, or observation produced by
+an agent during domain audit phases. Findings are the primary unit of agent output —
+every concern an agent raises must be expressed as a Finding. Findings feed into
+disagreement resolution, severity calibration, and final report generation."]
+
+## Template
+
+```markdown
+### {finding_id}
+
+**Domain:** {domain_number} — {domain_name}
+**Agent:** {agent_id}
+**Severity:** [critical | high | medium | low | informational]
+**Confidence:** [high | medium | low]
+
+**Title:** [One-line finding title — specific and descriptive]
+
+**Description:**
+[What was found. Factual description of the issue, pattern, or observation.
+Two to four sentences.]
+
+**Evidence:**
+[Concrete evidence supporting this finding. File paths, code snippets,
+tool signals, configuration excerpts. Must be verifiable.]
+
+**Impact:**
+[What could go wrong. Business and technical consequences if this
+issue is not addressed.]
+
+**Recommendation:**
+[Suggested remediation. Specific, actionable, and scoped to the finding.]
+
+**References:**
+- [CWE/CVE/standard reference, if applicable]
+- [Related findings by ID, if applicable]
+```
+
+## Field Reference
+
+| Field | Type | Required | Description | Valid Values |
+|-------|------|----------|-------------|--------------|
+| `finding_id` | string | yes | Unique identifier. Format: `F-{DD}-{NNN}` where DD is domain number and NNN is sequence. | Pattern: `F-\d{2}-\d{3}` |
+| `domain_number` | string | yes | Two-digit domain number this finding belongs to. | `00` through `13` |
+| `domain_name` | string | yes | Human-readable domain name. | Must match domain file's `name` field |
+| `agent_id` | string | yes | ID of the agent that produced this finding. | Must match an agent file's `id` field |
+| `severity` | enum | yes | Assessed severity of the finding. | `critical`, `high`, `medium`, `low`, `informational` |
+| `confidence` | enum | yes | Agent's confidence in the finding's accuracy. | `high`, `medium`, `low` |
+| `title` | string | yes | One-line descriptive title. | Max 120 characters |
+| `description` | string | yes | Factual description of the issue. | 2-4 sentences |
+| `evidence` | string | yes | Verifiable proof. File paths, code, tool output. | Must reference concrete artifacts |
+| `impact` | string | yes | Consequences if unaddressed. | Business and/or technical impact |
+| `recommendation` | string | yes | Actionable remediation guidance. | Specific to this finding |
+| `references` | list of strings | no | CWE, CVE, standard refs, or related finding IDs. | Free-form but should use standard identifiers |
+
+## Validation Rules
+
+1. `finding_id` must be unique across the entire audit. No two findings may share an ID.
+2. `domain_number` must reference an existing domain (00-13).
+3. `agent_id` must reference an agent that has the specified domain in its `domains` list.
+4. `severity` must be one of the five enumerated values. No other values are valid.
+5. `confidence` must be one of the three enumerated values.
+6. `evidence` must contain at least one concrete reference (file path, code snippet, or tool signal ID). Assertions without evidence are invalid.
+7. `title` must not exceed 120 characters.
+8. [Additional validation rules specific to this schema.]
+
+## Examples
+
+### Example: High-Severity Security Finding
+
+```markdown
+### F-04-001
+
+**Domain:** 04 — Security
+**Agent:** security-engineer
+**Severity:** critical
+**Confidence:** high
+
+**Title:** Hardcoded database credentials in application configuration
+
+**Description:**
+Production database credentials are stored as plaintext strings in
+`config/database.py`. The username, password, and host are directly
+embedded in source code rather than injected via environment variables
+or a secrets manager.
+
+**Evidence:**
+File: `config/database.py`, lines 12-14:
+\```python
+DB_USER = "admin"
+DB_PASS = "pr0d_s3cret_2024"
+DB_HOST = "prod-db.internal.company.com"
+\```
+Corroborated by gitleaks signal: `GL-047` (high-entropy secret detected).
+
+**Impact:**
+Anyone with repository access has production database credentials.
+Credential rotation requires a code change and deployment. If the
+repository is compromised, the database is immediately accessible.
+
+**Recommendation:**
+Move credentials to environment variables or a secrets manager (e.g.,
+AWS Secrets Manager, HashiCorp Vault). Remove plaintext values from
+source code and rotate the exposed credentials immediately.
+
+**References:**
+- CWE-798: Use of Hard-coded Credentials
+- Related: F-04-003 (missing secrets scanning in CI)
+```
+````
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Wrong |
+|--------------|----------------|
+| Embedding interpretation guidance | "If severity is critical, the agent should escalate..." is workflow logic, not schema definition. Schemas define structure; rules and workflows define behavior. |
+| Including persona-specific fields | A field like `security_impact` that only one agent type would fill breaks universality. If a field isn't meaningful for all consumers listed in `used_by`, it doesn't belong in the schema. |
+| Loose field definitions | "`description`: any text" is not a definition. Specify what belongs in the field, how long it should be, and what constitutes valid content. Precision prevents drift. |
+| Missing enum values | Every enum field must list ALL valid values explicitly. "severity: one of several levels" is incomplete. "severity: critical, high, medium, low, informational" is complete. |
+| No validation rules | A schema without validation rules is just a template. Validation rules make schemas enforceable — they define what "correct" means. |
+| Version not updated on changes | Breaking changes to a schema (adding required fields, changing enum values, renaming fields) must increment the version. Consumers depend on the contract; changing it silently breaks the system. |
+| Playbook without intervention level | Every remediation must be classified. A playbook with no intervention level is ungoverned. |
+| Risk assessment without evidence | Scores without evidence are opinions. Every risk dimension requires supporting evidence. |
+
+## Transform Schema Definitions
+
+Transform introduces 4 additional schemas that live in `src/transform/schemas/`. These schemas govern remediation planning, change-risk assessment, intervention governance, and verification procedures. They build on top of Core schemas — particularly the finding schema — and are consumed exclusively by Transform agents and workflows.
+
+### Remediation Playbook (`playbook.md`)
+
+The playbook schema defines a structured remediation plan for a single finding. Each playbook maps a finding through transformation layers (abstract pattern to project-specific fix) and includes risk metadata and verification steps.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `finding_ref` | string | yes | Finding ID being remediated (e.g., `F-04-001`). Must match a valid finding ID from the Core finding schema. |
+| `intervention_level` | enum | yes | Governance level for this remediation. Valid values: `suggesting`, `planning`, `authorizing`, `executing`. |
+| `transformation_layers` | object | yes | Contains: `abstract_pattern` (string), `framework_mapping` (string), `language_mapping` (string), `project_context` (string). Each layer refines the remediation from general principle to project-specific guidance. |
+| `before_example` | string | yes | Code showing the anti-pattern as it exists in the target codebase. |
+| `after_example` | string | yes | Code showing the correct pattern after remediation. |
+| `verification_steps` | list of strings | yes | Ordered steps to verify the fix works. Each step must be concrete and executable. |
+| `risk_metadata` | object | yes | Contains: `blast_radius` (1-5), `coupling_risk` (1-5), `regression_probability` (1-5), `architectural_tension` (1-5). Each dimension scored with justification. |
+| `educational_context` | string | no | Pedagogical explanation for AI-assisted developers. Explains *why* the anti-pattern is harmful and *why* the remediation is preferred. |
+
+### Change Risk Assessment (`change-risk.md`)
+
+The change-risk schema captures a multi-dimensional risk evaluation for a proposed change. Every change that Transform considers must be assessed across four risk dimensions, each backed by evidence, before a recommendation is issued.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `change_id` | string | yes | Unique change identifier. |
+| `finding_refs` | list of strings | yes | Finding IDs this change addresses. Each must match a valid finding ID. |
+| `blast_radius` | object | yes | Contains: `score` (integer, 1-5), `evidence` (string), `affected_files` (list of strings). How widely the change ripples through the codebase. |
+| `coupling_risk` | object | yes | Contains: `score` (integer, 1-5), `evidence` (string), `new_dependencies` (list of strings). Whether the change introduces or tightens coupling. |
+| `regression_probability` | object | yes | Contains: `score` (integer, 1-5), `evidence` (string), `test_coverage_pct` (number). Likelihood the change breaks existing functionality. |
+| `architectural_tension` | object | yes | Contains: `score` (integer, 1-5), `evidence` (string), `design_conflicts` (list of strings). Whether the change conflicts with the codebase's architectural direction. |
+| `overall_risk` | enum | yes | Aggregate risk classification. Valid values: `low`, `medium`, `high`, `critical`. |
+| `recommendation` | enum | yes | Action recommendation based on risk assessment. Valid values: `proceed`, `proceed_with_caution`, `human_review_required`, `reject`. |
+
+### Intervention Level (`intervention-level.md`)
+
+The intervention-level schema defines the governance tiers that control what Transform is permitted to do. Each level sets thresholds for finding confidence, evidence requirements, and high-risk behavior.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `level` | enum | yes | The intervention tier. Valid values: `suggesting`, `planning`, `authorizing`, `executing`. |
+| `minimum_finding_confidence` | enum | no | Minimum confidence a finding must have for this level to apply. Valid values: `low`, `medium`, `high`. |
+| `minimum_evidence_sources` | integer | no | Minimum number of independent evidence sources required. |
+| `allowed_when_risk_high` | boolean | no | Whether this intervention level is permitted when the change risk exceeds "high". |
+
+### Verification Plan (`verification-plan.md`)
+
+The verification-plan schema defines the checks that must be performed before, after, and in regression testing of a change. It also specifies rollback criteria and procedures, ensuring every Transform change is reversible.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `change_id` | string | yes | The change this verification plan covers. Must match a change-risk assessment's `change_id`. |
+| `pre_change_checks` | list of objects | yes | Each object contains: `check_name` (string), `command_or_instruction` (string), `expected_result` (string). Checks to run before applying the change. |
+| `post_change_checks` | list of objects | yes | Each object contains: `check_name` (string), `command_or_instruction` (string), `expected_result` (string). Checks to run after applying the change. |
+| `regression_checks` | list of objects | yes | Each object contains: `check_name` (string), `command_or_instruction` (string), `expected_result` (string). Checks to confirm no existing functionality is broken. |
+| `rollback_criteria` | list of strings | yes | Conditions under which rollback is required. Each criterion must be specific and observable. |
+| `rollback_procedure` | string | yes | How to undo the change. Must be a concrete, step-by-step procedure. |

package/modules/radar/docs/standards/tools.md

@@ -0,0 +1,273 @@
+# Tool Convention
+
+## Purpose
+
+Tools define **INPUTS** — how to run external analysis tools, parse their output, and normalize it into the Radar signal format. Tools are the bridge between raw scanner output and structured agent input.
+
+In Radar, tools produce **signals**; agents **interpret** them. A tool file never says what a finding means — it only says how to run the scanner, what the raw output looks like, and how to map that output into a normalized signal schema that agents can consume. The interpretation, severity assessment, and contextual judgment all happen at the agent layer.
+
+Some tools produce signals consumed by both Core diagnostic agents and Transform intervention agents. Additionally, Transform introduces a new category of tool usage: change-risk analysis tooling that feeds the Change Risk Modeler.
+
+Radar uses 7 or more tool files, one per external analysis tool.
+
+## Location
+
+```
+src/tools/
+```
+
+## Naming
+
+**Pattern:** `{kebab-name}.md`
+
+One tool per file, even when tools are commonly used together (e.g., Syft and Grype are separate files despite being complementary).
+
+**Examples:**
+- `semgrep.md`
+- `trivy.md`
+- `gitleaks.md`
+- `syft.md`
+- `grype.md`
+- `git-history.md`
+- `checkov.md`
+
+## Required Structure
+
+Every tool file consists of YAML frontmatter followed by 6 mandatory sections.
+
+### Frontmatter (Required)
+
+```yaml
+---
+id: {kebab-name}
+name: [Tool Display Name]
+type: [static_analysis | vulnerability_scan | secrets_detection | iac_scan | sbom | history_mining | code_quality]
+domains_fed: [list of domain numbers this tool produces signals for]
+install_required: [true | false]
+install_command: [command to install, if required]
+---
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | yes | Kebab-case identifier, must match filename without extension |
+| `name` | string | yes | Human-readable tool name (e.g., "Semgrep", "Trivy") |
+| `type` | enum | yes | Tool category. One of: `static_analysis`, `vulnerability_scan`, `secrets_detection`, `iac_scan`, `sbom`, `history_mining`, `code_quality`, `change_risk_analysis` |
+| `domains_fed` | list of strings | yes | Two-digit domain numbers this tool produces signals for |
+| `install_required` | boolean | yes | Whether the tool requires explicit installation |
+| `install_command` | string | conditional | Required if `install_required` is `true`. Exact command to install the tool. |
+
+### Body Sections (All Required)
+
+| Section | Header | Purpose |
+|---------|--------|---------|
+| Purpose | `## Purpose` | What this tool does and what types of signals it produces. |
+| Configuration | `## Configuration` | How to configure the tool for Radar use. Config files, rule sets, policies. |
+| Execution | `## Execution` | Exact commands to run the tool. Input parameters, expected runtime characteristics. |
+| Output Format | `## Output Format` | What raw tool output looks like. Representative example snippet. |
+| Normalization | `## Normalization` | How to transform raw output into Radar signal schema. Field mapping table. |
+| Limitations | `## Limitations` | What the tool cannot detect. Known false positive/negative patterns. |
+
+## Cross-References
+
+| Direction | What | How |
+|-----------|------|-----|
+| Referenced BY | Domain files (`src/domains/`) | In the Tool Affinities section |
+| Referenced BY | Agent assembly manifests (`src/agents/`) | `tools: [{tool-id}, ...]` field |
+| Referenced BY | Workflows (`src/workflows/`) | For tool execution steps |
+| References | Signal schema (`src/schemas/signal.md`) | Normalization target format |
+
+## Example Skeleton
+
+````markdown
+---
+id: semgrep
+name: Semgrep
+type: static_analysis
+domains_fed: ["04", "01", "06"]
+install_required: true
+install_command: pip install semgrep
+---
+
+## Purpose
+
+[What this tool does and what kinds of signals it produces.
+
+Example: "Semgrep is a static analysis tool that pattern-matches source code
+against a library of rules covering security vulnerabilities, code quality
+issues, and framework-specific anti-patterns. It produces signals for
+injection flaws, authentication weaknesses, insecure cryptography,
+hardcoded secrets, and architectural pattern violations."]
+
+## Configuration
+
+[How to configure the tool for Radar use. Include actual config file contents
+where applicable.]
+
+### Config File
+
+```yaml
+# .semgrep.yml (place in target repository root or pass via --config)
+rules:
+  - p/security-audit
+  - p/owasp-top-ten
+  - p/secrets
+  - [additional rule packs relevant to Radar domains]
+```
+
+### Rule Sets
+
+- [Rule set 1 — e.g., "`p/security-audit` — broad security pattern matching"]
+- [Rule set 2 — e.g., "`p/owasp-top-ten` — OWASP Top 10 coverage"]
+- [Additional rule sets with brief description of what each covers]
+
+### Configuration Notes
+
+- [Note 1 — e.g., "Use `--severity ERROR WARNING` to exclude INFO-level noise"]
+- [Note 2 — e.g., "Set `--timeout 300` for large repositories"]
+- [Additional configuration guidance]
+
+## Execution
+
+### Primary Command
+
+```bash
+semgrep scan \
+  --config auto \
+  --json \
+  --output {output_dir}/semgrep-results.json \
+  --severity ERROR WARNING \
+  --timeout 300 \
+  {target_path}
+```
+
+### Parameters
+
+| Parameter | Value | Description |
+|-----------|-------|-------------|
+| `{target_path}` | Path to repository root | Directory to scan |
+| `{output_dir}` | `.radar/signals/` | Where to write output |
+
+### Runtime Expectations
+
+- [Expected runtime — e.g., "2-10 minutes for repositories under 100k lines"]
+- [Resource requirements — e.g., "Requires ~2GB RAM for large rule sets"]
+- [Common failure modes — e.g., "Times out on generated code; exclude with --exclude"]
+
+## Output Format
+
+[Description of what the raw output looks like, followed by a representative snippet.]
+
+```json
+{
+  "results": [
+    {
+      "check_id": "[rule.id — e.g., python.lang.security.injection.sql-injection]",
+      "path": "[file path relative to scan root]",
+      "start": { "line": 42, "col": 5 },
+      "end": { "line": 42, "col": 68 },
+      "extra": {
+        "message": "[Human-readable description of the finding]",
+        "severity": "[ERROR | WARNING | INFO]",
+        "metadata": {
+          "cwe": ["[CWE-89]"],
+          "owasp": ["[A03:2021]"],
+          "confidence": "[HIGH | MEDIUM | LOW]"
+        }
+      }
+    }
+  ]
+}
+```
+
+## Normalization
+
+Transform raw tool output into Radar signal schema format.
+
+### Field Mapping
+
+| Raw Field | Signal Field | Transformation |
+|-----------|-------------|----------------|
+| `check_id` | `rule_id` | Direct mapping |
+| `path` | `file_path` | Prepend repository root if relative |
+| `start.line` | `location.start_line` | Direct mapping |
+| `end.line` | `location.end_line` | Direct mapping |
+| `extra.message` | `description` | Direct mapping |
+| `extra.severity` | `tool_severity` | Map: ERROR=high, WARNING=medium, INFO=low |
+| `extra.metadata.cwe` | `references.cwe` | Direct mapping (array) |
+| `extra.metadata.confidence` | `tool_confidence` | Map: HIGH=high, MEDIUM=medium, LOW=low |
+| (generated) | `signal_id` | Generate: `{tool_id}-{sequential_number}` |
+| (generated) | `source_tool` | Set to `{tool_id}` |
+
+### Normalization Notes
+
+- [Note 1 — e.g., "Semgrep severity is relative to its rule set, not absolute.
+  Map to Radar signal severity but do not treat as final finding severity."]
+- [Note 2 — e.g., "Deduplicate signals with identical check_id and file_path+line."]
+- [Additional normalization guidance]
+
+## Limitations
+
+### Cannot Detect
+
+- [Limitation 1 — e.g., "Business logic flaws — Semgrep matches patterns, not intent"]
+- [Limitation 2 — e.g., "Runtime-only vulnerabilities (race conditions, timing attacks)"]
+- [Limitation 3 — e.g., "Issues in dynamically generated code or templated strings"]
+
+### Known False Positive Patterns
+
+- [Pattern 1 — e.g., "Flags test fixtures that intentionally contain vulnerable patterns"]
+- [Pattern 2 — e.g., "Reports 'hardcoded secret' on non-secret constants with high entropy"]
+- [Additional false positive patterns agents should be aware of]
+
+### Known False Negative Patterns
+
+- [Pattern 1 — e.g., "Misses injection via indirect variable concatenation across functions"]
+- [Pattern 2 — e.g., "Does not follow data flow through ORMs with custom query methods"]
+- [Additional false negative patterns]
+````
+
+## Transform Tool Conventions
+
+Transform agents consume tool signals differently from Core agents. Core agents interpret signals as evidence for findings. Transform agents use signals as input for change-risk modeling and remediation context.
+
+**Tools that feed Transform (in addition to Core):**
+
+| Tool Category | Purpose | Change Risk Dimension |
+|--------------|---------|----------------------|
+| Dependency graph analyzers | Map module coupling and dependency chains | Coupling risk |
+| Test coverage mappers | Identify tested vs untested code paths | Regression probability |
+| Change impact analyzers | Estimate blast radius of proposed changes | Blast radius |
+| Git history miners | Identify change frequency, ownership, and churn patterns | All dimensions |
+
+**Reused Core tools for Transform:**
+- `git-history` tool signals feed both Core (Domain 11-12: change risk, ownership) and Transform (regression probability, blast radius estimation)
+- `sonarqube` complexity metrics inform both Core (code health) and Transform (architectural tension estimation)
+
+**Tool output normalization for change-risk signals:**
+
+Transform-specific normalization adds a change-risk mapping in addition to the standard signal normalization:
+
+| Raw Signal | Change Risk Signal | Transformation |
+|-----------|-------------------|----------------|
+| Test coverage percentage per file | `regression_probability_input` | Lower coverage = higher regression probability |
+| Import/dependency count per module | `coupling_risk_input` | More dependencies = higher coupling risk |
+| File modification frequency (churn) | `blast_radius_input` | High churn = many dependents = higher blast radius |
+| Cyclomatic complexity | `architectural_tension_input` | High complexity = harder to change safely |
+
+**New tool type: `change_risk_analysis`**
+
+Tools in this category produce signals specifically for the Change Risk Modeler. They follow the same convention structure (Purpose, Configuration, Execution, Output Format, Normalization, Limitations) but their normalization section maps to change-risk dimensions rather than finding severity.
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Wrong |
+|--------------|----------------|
+| Embedding audit logic | "If this finding appears, it means the application is vulnerable" is interpretation — that's agent work. Tool files describe *what* the tool outputs and *how* to normalize it, not *what it means*. |
+| Tool-specific severity scales without normalization guidance | Every tool has its own severity scale. Without explicit mapping to Radar signal schema severity, agents receive inconsistent input. The normalization section must include severity mapping. |
+| Missing execution commands | A tool spec that doesn't include the exact command to run is incomplete. Workflows need to execute tools programmatically. If the command isn't here, it doesn't exist. |
+| Combining multiple tools in one file | Syft and Grype are complementary but separate tools with separate execution, output formats, and signal types. One file per tool, always. Cross-reference via domain affinities if needed. |
+| Omitting limitations | Every tool has blind spots. Failing to document what a tool *cannot* detect leads agents to assume absence of signals means absence of issues. Limitations are as important as capabilities. |
+| Prescriptive interpretation of output | "A HIGH severity Semgrep finding should be treated as critical" is prescriptive interpretation. The tool file maps `HIGH` to the signal field `tool_severity: high`. The agent decides the actual finding severity using its persona and domain knowledge. |
+| Tool that claims to assess change risk without evidence | A tool output that says 'high risk' without measurable data (coverage percentage, dependency count, churn rate) is not useful for Transform. Change risk must be grounded in quantifiable signals. |
+| Conflating tool severity with change risk | A Semgrep finding with severity 'HIGH' does not mean the fix has high change risk. Tool severity describes the problem's impact. Change risk describes the danger of the fix. These are orthogonal dimensions. |