Added start docs.

robmoffat · robmoffat · commit 67484c431a56 · 2026-02-15T22:03:35.000Z
diff --git a/docs/capabilities/Execution.md b/docs/capabilities/Execution.md
@@ -16,3 +16,13 @@ gemara:
 ## Description
 
 Execution capability allows agents to run the code they generate or invoke, observe outputs, and iterate based on results. This enables autonomous debugging, testing, and deployment workflows.
+
+## Privileged Execution
+
+A critical aspect of agent execution is that it typically occurs **on behalf of the user**, inheriting their credentials, permissions, and access rights. This means:
+
+- **Ambient Authority**: Agents execute with whatever permissions the user has granted to the development environment — often broad access to filesystems, networks, cloud resources, and secrets.
+- **Credential Inheritance**: API keys, SSH keys, cloud credentials, and other secrets accessible to the user become accessible to the agent.
+- **Impersonation**: Actions taken by the agent may be indistinguishable from actions taken by the user in audit logs and access control systems.
+
+This creates an amplification effect: a compromised or misdirected agent can cause harm proportional to the user's privilege level, not the agent's intended scope.
diff --git a/docs/capabilities/Start.md b/docs/capabilities/Start.md
@@ -0,0 +1,22 @@
+---
+title: Agentic Software Development Capabilities
+description: The foundational capabilities that enable AI agents to participate in software development
+sidebar_position: 1
+slug: /capabilities
+---
+
+# Agentic Capabilities
+
+The capabilities that enable AI agents to autonomously participate in software development workflows. Each capability represents a distinct type of action an agent can take — and each introduces its own threat surface.
+
+## Why Capabilities Matter
+
+Understanding capabilities is essential for risk management because:
+
+- **Capabilities enable threats**: Every risk in this framework is enabled by one or more capabilities. You cannot have "supply chain poisoning" without `internet-access`; you cannot have "verification illusion" without `code-generation`.
+- **Capabilities can be constrained**: The most direct control over agent risk is limiting which capabilities an agent has access to.
+- **Capabilities compound**: Agents with multiple capabilities can chain them in unexpected ways — `file-system-access` + `internet-access` = data exfiltration potential.
+
+## Capability Inventory
+
+<TagList tag="Capability" filter="capabilities" />
diff --git a/docs/capabilities/_category_.yaml b/docs/capabilities/_category_.yaml
@@ -1,3 +1,6 @@
 ---
 label: Capabilities
+link:
+  id: Start
+  type: doc
 position: 1
diff --git a/docs/practices/Independent-Verification.md b/docs/practices/Independent-Verification.md
diff --git a/docs/practices/Start.md b/docs/practices/Start.md
@@ -0,0 +1,14 @@
+---
+title: Agentic Software Development Practices
+description: Controls and practices for managing risks in agentic software development
+sidebar_position: 1
+slug: /practices
+---
+
+# Agentic Practices
+
+Controls, practices, and mitigations for managing the risks introduced by AI agents in software development workflows.
+
+## Practice Inventory
+
+<TagList tag="Control" filter="practices" />
diff --git a/docs/practices/_category_.yaml b/docs/practices/_category_.yaml
@@ -1,3 +1,6 @@
 ---
 label: Practices / Controls
+link:
+  id: Start
+  type: doc
 position: 3
diff --git a/docs/risks/Autonomy-Control-Risks.md b/docs/risks/Autonomy-Control-Risks.md
@@ -26,6 +26,9 @@ gemara:
     - name: AI Agent
       type: Internal
       description: Pursues goals that diverge from human intent, optimizes proxy metrics, or self-modifies constraints
+    - name: Human Operator
+      type: Internal
+      description: Grants excessive autonomy, fails to set appropriate boundaries, or does not intervene when agent exceeds scope
   external-mappings:
     - reference-id: mitre-atlas
       entries:
diff --git a/docs/risks/Containment-Isolation-Risks.md b/docs/risks/Containment-Isolation-Risks.md
@@ -26,6 +26,9 @@ gemara:
     - name: AI Agent
       type: Internal
       description: Discovers and exploits containment weaknesses through normal operation or tool chaining
+    - name: Human Operator
+      type: Internal
+      description: Configures weak containment, grants excessive permissions, or disables safeguards for convenience
   external-mappings:
     - reference-id: mitre-atlas
       entries:
diff --git a/docs/risks/Data-Privacy-Risks.md b/docs/risks/Data-Privacy-Risks.md
@@ -8,7 +8,7 @@ tags:
 gemara:
   id: data-privacy-risks
   title: Data & Privacy Risks
-  description: Threats arising from AI agents that expose secrets in code, leak sensitive data through network access, retain PII inappropriately, or violate data handling policies.
+  description: Threats arising from AI agents that expose secrets in code, leak sensitive data through network access, retain or leak PII inappropriately, or violate data handling policies.
   capabilities:
     - reference-id: file-system-access
       entries:
@@ -29,6 +29,9 @@ gemara:
     - name: AI Agent
       type: Internal
       description: Handles sensitive data without appropriate care, embeds secrets in code, or retains PII inappropriately
+    - name: Human Operator
+      type: Internal
+      description: Grants agent excessive data access, fails to configure data handling boundaries, or shares secrets in prompts
   external-mappings:
     - reference-id: mitre-atlas
       entries:
diff --git a/docs/risks/Deployment-Rollback-Risks.md b/docs/risks/Deployment-Rollback-Risks.md
@@ -26,6 +26,9 @@ gemara:
     - name: AI Agent
       type: Internal
       description: Prioritizes deployment speed over safety, creates irreversible states, or bypasses approval gates
+    - name: Human Operator
+      type: Internal
+      description: Approves risky deployments without adequate review, sets weak approval gates, or skips rollback planning
   external-mappings:
     - reference-id: mitre-atlas
       entries:
diff --git a/docs/risks/Economic-Pressure-Risks.md b/docs/risks/Economic-Pressure-Risks.md
@@ -23,6 +23,9 @@ gemara:
     - name: AI Agent
       type: Internal
       description: Over-optimizes for measurable efficiency metrics, sacrificing quality or security for speed
+    - name: Human Operator
+      type: Internal
+      description: Makes cost/speed tradeoffs under deadline pressure, accepts lower quality for faster delivery
     - name: Organisational Culture
       type: Systemic
       description: Rewards unsafe acceleration, creates pressure to bypass safety controls for delivery
diff --git a/docs/risks/Human-Factors-Risks.md b/docs/risks/Human-Factors-Risks.md
@@ -26,6 +26,9 @@ gemara:
     - name: AI Agent
       type: Internal
       description: Optimizes for approval rather than correctness, exploits cognitive biases, or overwhelms reviewers
+    - name: Human Operator
+      type: Internal
+      description: Susceptible to manipulation, fatigue, or cognitive biases; rubber-stamps agent outputs under time pressure
   external-mappings:
     - reference-id: mitre-atlas
       entries:
diff --git a/docs/risks/Start.md b/docs/risks/Start.md
@@ -0,0 +1,25 @@
+---
+title: Agentic Software Development Risks
+description: Threats and risks specific to AI agents participating in software development
+sidebar_position: 1
+slug: /risks
+---
+
+# Agentic Risks
+
+The threats that emerge when AI agents autonomously write, modify, and deploy code. These risks are distinct from traditional AI risks (bias, hallucination) because they concern **AI as a producer of software**, not AI as a decision-making component.
+
+## Actor Taxonomy
+
+Risks in this framework involve four types of actors:
+
+| Actor | Type | Description |
+|-------|------|-------------|
+| **External Attacker** | External | Adversaries who exploit, compromise, or manipulate the system |
+| **AI Agent** | Internal | The agent itself exhibiting unsafe, misaligned, or careless behaviors |
+| **Human Operator** | Internal | The human user/developer making configuration or approval decisions |
+| **Organisational Culture** | Systemic | Organizational pressures and incentive structures that enable risk |
+
+## Risk Inventory
+
+<TagList tag="Threat" filter="risks" />
diff --git a/docs/risks/Verification-Testing-Risks.md b/docs/risks/Verification-Testing-Risks.md
@@ -23,6 +23,9 @@ gemara:
     - name: AI Agent
       type: Internal
       description: Generates minimal tests to pass coverage thresholds, or shares blind spots between code generation and verification
+    - name: Human Operator
+      type: Internal
+      description: Over-trusts AI-generated tests, fails to require or perform independent verification
     - name: Organisational Culture
       type: Systemic
       description: Over-relies on AI-generated tests without independent verification requirements
diff --git a/docs/risks/_category_.yaml b/docs/risks/_category_.yaml
@@ -1,3 +1,6 @@
 ---
 label: Risks
+link:
+  id: Start
+  type: doc
 position: 2
diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -51,9 +51,9 @@ const config = {
           src: 'img/logo.svg',
         },
         items: [
-          { to: '/risks/Verification-Illusion', label: 'Risks', position: 'left' },
-          { to: '/practices/Independent-Verification', label: 'Practices', position: 'left' },
-          { to: '/capabilities/Code-Generation', label: 'Capabilities', position: 'left' },
+          { to: '/risks', label: 'Risks', position: 'left' },
+          { to: '/practices', label: 'Practices', position: 'left' },
+          { to: '/capabilities', label: 'Capabilities', position: 'left' },
           {
             href: 'https://riskfirst.org',
             label: 'Risk-First',
@@ -72,9 +72,9 @@ const config = {
           {
             title: 'Framework',
             items: [
-              { label: 'Risks', to: '/risks/Verification-Illusion' },
-              { label: 'Practices', to: '/practices/Independent-Verification' },
-              { label: 'Capabilities', to: '/capabilities/Code-Generation' },
+              { label: 'Risks', to: '/risks' },
+              { label: 'Practices', to: '/practices' },
+              { label: 'Capabilities', to: '/capabilities' },
             ],
           },
           {
diff --git a/scripts/validate.sh b/scripts/validate.sh
