Add mutation tools and role-based artifact access for agent-mediated IDD workflows

[slusset]

Summary

IDD currently has robust validation tools (read-only, post-hoc) and evidence generation (tool-mediated with --write flag), but spec artifacts (personas, journeys, stories, models, features, contracts) are created and modified via direct Write calls in skills with no pre-write validation or access control.

In multi-agent systems where different agents (PA, Coding Agent, QA Agent) interact with IDD artifacts, this creates two problems:

1. Format drift: An LLM writing YAML freehand will eventually introduce invalid fields, drop required metadata, invent new status values, or break front-matter conventions. Validators catch this post-hoc, but the damage is done — the commit exists.

2. Role confusion: Nothing prevents a Coding Agent from modifying a solution narrative, or a QA agent from altering a domain model. In multi-agent orchestration, artifact ownership matters.

Problem

Today, the mutation path for IDD artifacts is:

LLM invokes skill → skill instructs Write tool → raw YAML/Markdown written to disk

Validation happens later (in CI, via idd validate). This means:

• Invalid specs can be committed and only caught in CI
• No invariant enforcement at write time (e.g., front-matter refs must reference existing files)
• No concept of "who is allowed to modify this artifact type"
• When an LLM updates a model, it might break traceability links that validators would have caught

Desired outcome

1. Mutation tools (validate-before-write)

Add tool-mediated mutation for IDD artifacts, following the pattern already established by generate-evidence --write:

LLM calls mutation tool → tool validates schema + invariants → tool writes to disk

For each artifact family:

Artifact	Mutation Tool	Validates Before Write
Persona	idd create-persona / idd update-persona	Front-matter schema, required fields
Journey	idd create-journey / idd update-journey	Persona refs exist, step structure
Story	idd create-story / idd update-story	Journey/persona refs exist, AC format
Model	idd create-model / idd update-model	Source story refs, attribute schema, lifecycle transitions
Feature	idd create-feature / idd update-feature	Scenario structure, story traceability tags
Contract	idd create-contract / idd update-contract	OpenAPI/AsyncAPI/JSON-RPC schema conformance
Capability	idd create-capability / idd update-capability	Scope refs exist, artifact inventory

These don't need to be full CRUD — even just a --validate-before-write mode on the existing Write pattern would help. The key is: the tool checks invariants before persisting, not after.

2. Role-based artifact access

Define which actor roles can create/modify which artifact types. This becomes relevant when multiple agents collaborate:

Artifact Layer	Owner Role	Can Modify	Read-Only
Roadmap/Plan	PM / PA	PA	All
Personas, Journeys, Stories	PM / PA	PA, with stakeholder input	CA, QA
Domain Models	Architect / PA	PA, CA (implementation details only)	QA
Features (Gherkin)	PA / QA	PA (scenarios), QA (step defs)	CA
Contracts (OpenAPI/AsyncAPI/JSON-RPC)	PA / Architect	PA, CA (implementation alignment)	QA
Code	CA	CA	PA (review), QA (testing)
Test Results / Evidence	QA / Certification	QA, Certification tool	PA, CA

This could be expressed as:

• Metadata in skill definitions (allowed-roles alongside existing allowed-tools)
• A .idd/roles.yaml config that maps agent types to artifact access
• Validation rules that check git blame / commit author against allowed modifiers

3. Skill integration

Update skills to use mutation tools instead of raw Write when available:

# Before (current)
## Workflow
1. Create persona file using Write tool at specs/personas/{name}.md

# After (proposed)
## Workflow  
1. Create persona using `idd create-persona --id {name} --role "..." --goals "..."`
   OR use Write tool with validated template, then run `idd validate front-matter`

Use case: agent-orchestrator

The agent-orchestrator project has already built a proof-of-concept of this pattern for its plan/roadmap layer:

• PlanManager enforces invariants on every mutation (valid state transitions, dependency satisfaction, no circular deps)
• LLMs call pm.advance_milestone() instead of editing YAML
• CI runs validate-plan.py as a safety net

This pattern should generalize to all IDD artifact types. The plan layer itself is orchestrator-specific (project management, not methodology), but the mutation-with-validation pattern belongs upstream.

Scope

In scope:

• Define the mutation tool interface for each artifact family
• Implement validate-before-write for at least: persona, journey, story, model
• Define role-based access model and configuration format
• Update skill documentation to reference mutation tools
• Add tests for mutation tool validation behavior

Out of scope:

• Replacing the existing Write-based workflow (mutation tools are additive)
• Implementing a full RBAC system (start with documentation and validation warnings)
• Plan/roadmap schema (stays in consuming projects, not in IDD)

Acceptance criteria

• Mutation tools exist for core artifact families (persona, journey, story, model at minimum)
• Mutation tools validate schema, front-matter, and referential integrity before writing
• Role-based access model is documented with clear ownership per artifact layer
• At least one skill is updated to demonstrate mutation tool usage
• Validation warnings are emitted when an artifact is modified by a non-owner role (advisory, not blocking initially)
• Existing Write-based workflow continues to work (mutation tools are opt-in)

Relationship to other issues

• Builds on Establish a formal language-theoretic schema for IDD specification formats #24 (formal schema) — mutation tools need a schema to validate against
• Complements Add AsyncAPI and JSON-RPC support at the contract layer #26 (AsyncAPI/JSON-RPC) — mutation tools for the new contract types
• Informed by agent-orchestrator PlanManager pattern (proof-of-concept)

Why this matters

As IDD is adopted in multi-agent systems, the spec layer becomes a shared resource modified by different actors with different responsibilities. Without validated mutations and access control, format drift and role confusion will erode the traceability chain that IDD is designed to maintain. The validation tools catch problems after the fact; mutation tools prevent them.