docs: orient the problem analysis brief harness experiment

[swgiacomelli]

Purpose and value

Record a self-contained orientation for a proposed experiment that asks whether ph-agent-toolkit can support a durable front-end analysis process:

a maintainer states a problem in ordinary language, structured analysis preserves and challenges the framing, and a standardized Problem Analysis Brief leads with consumer value, risk, cost, reversibility, and the decision required while keeping technical analysis in supporting sections.

The immediate value of this PR is a handoff boundary. Another agent can review the orientation and prepare a bounded first-slice plan without relying on private conversational or Notion context.

Scope and governing decision

• Experiment: problem-analysis-brief-harness
• Stage: proposed
• Assurance: experimental
• Governing repository boundaries: STATUS.md, AGENTS.md, docs/ARCHITECTURE.md, and docs/EXPERIMENT_LIFECYCLE.md

This draft PR records a proposal only. It does not authorize implementation, create a toolkit package, advance the experiment to experiment, or replace the normal Discussion/Issue transition for later implementation work.

Added orientation

• experiments/problem-analysis-brief-harness/README.md
  • experiment question, hypothesis, counter-hypothesis, authority boundary, validation scope, non-guarantees, and transition criteria;
• experiments/problem-analysis-brief-harness/AGENT_ORIENTATION.md
  • complete next-agent reading order, value-first briefing contract, deterministic-versus-semantic boundary, provisional core-only package shape, required commands, refusal behavior, deliverables, escalation triggers, definition of done, and a reusable handoff instruction;
• experiments/problem-analysis-brief-harness/cases/README.md
  • eight planned accepted, refused, non-ready, authority, traceability, uncertainty, and deterministic-rendering cases;
• an experiment index entry and [Unreleased] changelog entry.

Proposed first implementation boundary

The orientation recommends a first core-only experiment:

• one closed, versioned JSON analysis bundle;
• offline deterministic validation and Markdown rendering;
• validate and render command surfaces;
• explicit gate and non-authorization checks;
• value, risk, recommendation, challenge, and technical-annex structure;
• success and refusal fixtures before model orchestration.

It explicitly defers agent packages, providers, network access, autonomous research, GitHub/Notion mutation, course-of-action machinery, campaign graphs, repository creation, and release behavior.

Evidence and checks

Documentation-only branch inspection:

• branch is five commits ahead of main and not behind;
• aggregate diff contains three new experiment documents plus the experiment index and changelog update;
• all referenced repository-local authority documents exist on main.

No Python behavior, package metadata, workspace dependency, or lockfile changed, so package suites were not run for this orientation-only draft. Rendered Markdown and relative links still require human review.

Handoff

The next agent's first output should be a reviewable implementation plan and identified contract questions—not code. The bounded assignment is included verbatim at the end of AGENT_ORIENTATION.md.

Remaining decisions

• accept, revise, or reject the proposed experiment boundary;
• decide whether the provisional problem-analysis capability name is sufficiently narrow;
• decide whether one closed bundle is the right first artifact or still too speculative;
• authorize or refuse a follow-on core-only implementation experiment.

Merging this documentation does not answer those questions automatically.