Code review: flowstate README contradicts repository mutation contract

[ajbeaver]

Generated by Offband issue reporting.

Summary

Code review: flowstate README contradicts repository mutation contract

Routing

• Repo: offband/FlowState
• Repo class: public_tool
• Rule id: code_review.docs_contract
• Candidate key: code-review:flowstate:dispatch-context-injection
• Category: code-review
• Severity: warning
• Review profile: code_review
• Review target: flowstate
• Labels: offband-report, weekly, needs-owner, code-review
• Source: code_review.bounded_ai

Expected

Product repositories should avoid actionable code risks identified by bounded source review.

Observed

README.md:31: The README says flow codex install ai-builder --path <redacted-path> makes the project contain .flow/context.toml and .flow/codex-runtime.md, but the later Security / Non-Execution section says FlowState does not mutate repositories.

Why It Matters

Users and reviewers cannot rely on the stated non-mutation security boundary; an install command appears to write project-local files despite the documented guarantee.

Decision Needed

Clarify the security contract by either documenting runtime attachment writes as the explicit exception or changing the command/behavior so the non-mutation claim is true.

Policy Source

config/issue-reporting.json: code_review

Evidence

{
  "artifact_path": "<redacted-path>",
  "canonical_topic": "dispatch-context-injection",
  "dedupe_core": "readme-contradicts-repository-mutation",
  "dedupe_subject": "terms:readme-contradicts-repository-mutation",
  "finding": {
    "confidence": "high",
    "finding_class": "docs_contract",
    "impact": "Users and reviewers cannot rely on the stated non-mutation security boundary; an install command appears to write project-local files despite the documented guarantee.",
    "line": 31,
    "owner_decision": "Clarify the security contract by either documenting runtime attachment writes as the explicit exception or changing the command/behavior so the non-mutation claim is true.",
    "path": "README.md",
    "summary": "The README says `flow codex install ai-builder --path <redacted-path>` makes the project contain `.flow/context.toml` and `.flow/codex-runtime.md`, but the later Security / Non-Execution section says FlowState does not mutate repositories.",
    "title": "README contradicts repository mutation contract"
  },
  "line": 31,
  "path": "README.md",
  "semantic_topic": "command-error"
}

Suggested Resolution

Clarify the security contract by either documenting runtime attachment writes as the explicit exception or changing the command/behavior so the non-mutation claim is true.

Report

• Report generated: 2026-07-08T12:16:21Z
• Candidate key: code-review:flowstate:dispatch-context-injection