Advisorygraphen

AdvisoryGraphen Skill

Use this skill when a task asks for evidence-backed consulting, technical advisory, architecture review, product decision analysis, AI transformation governance, delivery risk analysis, or projection of advisory findings into reports or tasks.

This skill is not just a CLI runbook. Use AdvisoryGraphen to structure obstructions, hypotheses, reviewable completion candidates, proposal content, and audience-specific projections. The primary agent loop is:

bounded source -> propose facade -> status/report -> review or observe
-> inspect proposal content -> request or apply reviewed structure -> rerun status

For small inputs where a full advisory space would be heavier than the task, start with micro review instead of forcing the full loop. You classify each claim; the command does not pattern-match prose. Build an advisorygraphen.micro_review.request.v1 document where every claim carries a classification (test_backed, source_backed, assumption, unsupported_strong_claim, or unsupported) and, for any evidence-backed claim, concrete evidence_refs:

small AI answer / note / issue -> classify each claim honestly -> micro review
-> inspect obstructions (supported-without-evidence, unsupported strong claims,
high-blast-radius), assumptions, missing checks, alternative hypotheses, and
escalation mode

A claim marked source_backed/test_backed without evidence_refs becomes a claim_marked_supported_without_evidence obstruction — do not certify support you cannot cite. Use the full loop only when micro review escalates (high blast radius, many claims, two or more unsupported strong claims, many unsupported claims) or the user needs durable review-gated structure.

For advisory work about a problem, default to a problem-driven hypothesis workflow:

one bounded problem -> multiple competing hypotheses -> observations/falsifiers
-> classify hypothesis support -> derive proposals only from supported hypotheses
-> project proposal trace and remaining uncertainty

Phase references

Read the relevant reference before starting each phase:

Safety rules

• Do not treat AI-inferred structure as accepted fact.
• Do not accept a completion candidate without explicit review.
• Do not hide projection loss.
• Do not collapse context-specific terms into one meaning without a mapping.
• Do not present unsupported claims as evidence-backed conclusions.
• Do not treat accepted completion review as structural application; inspect blocker_resolution_state.application_requirements first.
• Do not autonomously apply hypothesis lifecycle proposals unless a policy allows the outcome and evidence trust level.
• Do not ignore HigherGraphen gluing blockers. Treat higher_graphen_gluing_review.policy_blockers and higher_graphen_gluing_policy.policy_blockers as evidence requiring candidate revision or explicit completion review.

Workflow

For a pull request, prefer the bounded facade over hand-authoring a snapshot:

advisorygraphen pr-review \
  --base origin/main --head HEAD \
  --test-report check.log \
  --view compact --output review.json --format json

compact is the default and emits deterministic must_review, should_review, and can_skim buckets plus a SHA-256 reference to the retained full artifact. Use --view full for the audit-capable artifact. Add --github-pr <number> to capture merge state, head-bound CI, and base freshness. Refresh only volatile state with pr-review refresh-liveness; a changed head is refused and requires a full rebuild. Neither passing CI nor a priority bucket accepts a requirement.

After an explicit PR-review decision has been recorded in the full artifact's results.reviewed_results, export it without mutating CaseGraphen:

advisorygraphen export casegraphen-evidence \
  --projection review.json \
  --case-space-id case_space:pr-13 \
  --target-cell-id work:human-pr-review \
  --transition-to active \
  --satisfies evidence:review-pr-13 \
  --output review-evidence.json --format json

The exporter refuses unreviewed-only projections and unresolved or digest-mismatched compact references. Applying or reviewing the resulting packet remains a separate CaseGraphen authority act. If the receiving native space ID differs from its case-space ID, pass it with --claim-space-id.

1. Define one bounded problem statement before collecting proposals. If the user gives several concerns, split them or explicitly choose the current problem.
2. Create multiple competing hypotheses for that problem. Include at least one alternative cause and one falsifiable condition for each hypothesis.
3. Define a bounded source snapshot that records the problem, hypotheses, observation sources, known extraction loss, and trust notes.
4. Collect observations that can support, weaken, or falsify the hypotheses. Prefer direct command output, repository files, tests, metrics, or reviewed source material over agent inference.
5. For normal operation, run advisorygraphen propose --input <snapshot> --case <case-dir> --format json. This validates, lifts, checks, proposes completions, proposes hypothesis lifecycle transitions, generates ai_agent, imports the case, and writes advisorygraphen.case-manifest.json.
6. Run advisorygraphen status --case <case-dir> --brief --format json before resuming an existing case. Inspect result.summary, result.top_blockers, and result.next_best_action first; expand full blockers, frontier_items, and waiting_items only after choosing the next operation class.
7. Run advisorygraphen report --case <case-dir> --audience ai_agent --format json before choosing review, observation, or reporting steps.
8. Inspect obstructions, hypotheses, falsifiers, and argumentation_incidences.
9. Classify each hypothesis as strongly_supported, supported, supported_needs_followup, plausible_secondary, falsified, or insufficient_evidence. Do not collapse this classification into a single narrative before recording it.
10. Derive recommendations only from hypotheses with support. If a proposal depends on a weak or untested hypothesis, mark it as follow-up observation rather than primary action.
11. Use advisorygraphen review completion accept|reject --case <case-dir> or advisorygraphen review hypothesis support|falsify|accept|reject --case <case-dir> only for explicit review decisions.
12. Use low-level validate, lift, check, completions propose, hypothesis propose, project, and case commands for CI, debugging, or custom orchestration; in that mode still generate project --audience ai_agent before deciding the next agent operation.
13. Inspect projection fields (see references/projection.md).
14. Classify each candidate using its proposal_content (see references/proposal-review.md).
15. For candidates that may be accepted, run advisorygraphen completions dry-run and inspect higher_graphen_gluing_review before asking for review or recording an acceptance.
16. Generate the requested human projection or audit_trace, including the hypothesis classification, proposal trace, falsified/secondary hypotheses, and remaining uncertainty.
17. When follow-up observation tasks are present, run the bounded observation, record it with observation record, then use result.promotion_gate to support or falsify the hypothesis before rerunning case reason.
18. Keep candidates unreviewed unless the user explicitly accepts or rejects them, or an explicit conservative policy allows an automated lifecycle event.

Agent operating model

HigherGraphen is operated primarily by AI agents through AdvisoryGraphen. Humans set goals, constraints, and explicit accept/reject decisions; they do not need to hand-edit HG structure.

Treat ai_agent projection and case reason output as the resume protocol. If a candidate is accepted, do not mark the obstruction resolved until the required cells and incidences in blocker_resolution_state.application_requirements have been applied and check/case reason have been rerun.

If later knowledge shows a prior log entry or obstruction was wrong (a translation error, a log gap, a false positive — never merely "I changed my mind without new evidence"), record it as a case correct supersedes|invalidates|resolves event (issue #7) rather than arguing outside the log; this still requires --reviewer/--reason like any other review event. supersedes/invalidates target a prior case-log entry id (log:NNNNNN); the entry stays in the append-only log, but replay stops honoring its effect (an invalidated completions accept event stops contributing review_status; an invalidated hypothesis event stops contributing lifecycle_status). Corrections are themselves correctable: a correction entry can be targeted by a later supersedes/invalidates, restoring the original state on the next replay (e.g. invalidating a resolves correction puts the obstruction back into blockers).

resolves targets an obstruction id and is evidence for a human, not an eraser, with hybrid semantics: the obstruction is excluded from blockers, frontier_items, and waiting_items (do not work a retracted finding), but it stays in check/case reason output (derived state must stay replay-derived) and remains listed in blocker_resolution_state with a distinct resolution_status of resolved_by_correction carrying the resolving correction's id. close_status distinguishes closure kinds via closure_kind: "blocked" (a real blocker remains), "closeable" (structurally closeable, no corrections involved), or "closeable_with_corrections" (closeable only because of resolves corrections, with corrections_relied_on and corrected_obstruction_ids naming which) — closeable is never plain true from corrections alone; treat closeable_with_corrections as requiring the same scrutiny as any other correction rather than as equivalent to a structural close. Inspect case reason's corrections array to see the full chain (kind, target, reviewer, reason, timestamp).

A snapshot or space may declare metadata.reviewer_authorities (issue #6, actor × capability pairs — accept_completion, reject_completion, support_hypothesis, falsify_hypothesis, accept_hypothesis, reject_hypothesis, apply_structure, correct, assert_source_backed). When declared, an actor who performs a review-kind event (accept/reject, hypothesis lifecycle, corrections, apply-accepted) without the matching capability yields a derived acceptance_without_authority obstruction naming the actor and required capability — the event still writes to the log and takes effect; the obstruction does not undo it, it flags it for review. Invalidating that event (case correct supersedes|invalidates) removes its authority obstruction on the next replay along with its structural effect. When no reviewer_authorities declaration exists at all, no authority obstructions are ever produced and any actor string is honored, exactly as before this issue — do not infer an authority model where none is declared. The same declaration also governs whether a self-asserted provenance.origin: "source_backed" record reaches reviewed_or_source_backed trust for the hypothesis autonomy gate: without the asserting actor holding assert_source_backed, such a record is capped at agent_inferred and cannot alone unlock hypothesis apply-proposals.

Read this before treating a declaration as a control, not just an audit trail. reviewer_authorities is agent-authored input carried through lift unchanged — every obstruction and the provenance cap carry metadata.authority_source: "snapshot_declared" to say so explicitly. An actor that authored (or controls) the snapshot can grant itself any capability, including assert_source_backed, and defeat the corresponding check entirely — this feature gives auditability of a declared authority model, not prevention against an actor who controls its own declaration. Do not report a declared-and-matched capability as proof an independent authority reviewed anything; report it as "this actor's action matched what the snapshot declared," and note when the same actor plausibly authored that declaration. A non-circular root (e.g. a repo-committed policy file gated by human PR review, independent of anything an agent writes into a snapshot) is not implemented and remains an open requirement before this becomes an actual control.

In the AI-agent projection, inspect agent_operation_contract before taking action. Treat review_gated_commands as commands that require explicit review, inspect correspondence_analysis for HigherGraphen overlap, difference, and gluing failures, and prefer concrete ranked_observation_tasks from the hypothesis_promotion_workflow over broad follow-up questions.

For completion work, treat HigherGraphen gluing output as part of the review contract:

• completions dry-run exposes higher_graphen_gluing_review for each candidate-specific application attempt.
• completions accept records higher_graphen_gluing_policy in review-event metadata. If blockers remain and the reviewer still accepts, the event must carry policy_override: "explicit_completion_review".
• completions apply-accepted carries higher_graphen_gluing_review, policy_blockers, and policy_override into applied-structure output.

Do not interpret gluing success as acceptance. Do not interpret gluing failure as automatic rejection. It is review evidence that must be resolved by revising the candidate or by an explicit completion review decision.

External source boundary

Before running the workflow on external material:

1. Ensure the snapshot is bounded and contains no secrets.
2. Keep customer-specific spaces, reports, and case logs out of public repos.
3. Prefer synthetic or public fixtures for examples.
4. Preserve source IDs so proposal content can carry witnesses.
5. Disclose source_boundary.extraction_loss / .excluded_summary (the known-loss declaration), projection_loss, and projection_loss_metrics in summaries, including each entry's loss_evaluation (what was checked, how, on what range) and residual_loss_risk — a complete-looking known-loss list is not itself a safety guarantee (Sokkō methodology §3.3). check's review_signals flags a source_boundary missing residual_loss_risk (signal_type: "residual_loss_risk_undeclared"); treat it as a review prompt, not a blocker.

If the source snapshot lacks enough structure for a concrete proposal, report the missing structure rather than fabricating facts.

Verification guarantee tiers

A test_or_verification record, or a verifies / implements relation, may declare metadata.guarantee_tier: formal_verified, bounded_checked, statistically_supported, evaluator_supported, or runtime_observed. The tier is your classification; the tool validates the value, rejects it outside verification records/relations (exit 1), and propagates it to check's result.verifications and the ai_agent projection, but never infers one. Absence is legal and shown as absent.

Read the tier when reporting that a requirement is verified: a passing test is bounded_checked, not proof. Never present a lower tier as formal_verified, and never treat a declared tier as authority — it is deliberately not an autonomy-gate input, so hypothesis apply-proposals ignores it and carries it as display-only declared_guarantee_tier (ADR 0002: a self-declared classification cannot unlock autonomous application).

Commands

advisorygraphen validate --input INPUT.json --format json
advisorygraphen micro review --input MICRO_REVIEW_REQUEST.json --output MICRO_REVIEW.json --format json
advisorygraphen dogfood adversarial-fixture --output ADVERSARIAL_INPUT.json --format json
advisorygraphen dogfood repo-snapshot --repo REPO --output DOGFOOD_INPUT.json --format json
advisorygraphen code repo-snapshot --repo REPO --output CODE_INPUT.json --format json
advisorygraphen lift --input INPUT.json --package technical_advisory --output SPACE.json --format json
advisorygraphen check --space SPACE.json --ruleset technical_advisory_mvp --output CHECK.json --fail-on high --format json
advisorygraphen completions propose --space SPACE.json --from-report CHECK.json --output COMPLETIONS.json --format json
advisorygraphen completions dry-run --space SPACE.json --from-report COMPLETIONS.json --candidate-id CANDIDATE --output DRY_RUN.json --format json
advisorygraphen project --space SPACE.json --report CHECK.json --completions-report COMPLETIONS.json --audience ai_agent --format json --output AI_AGENT.json
advisorygraphen project --space SPACE.json --report CHECK.json --audience executive --format markdown --output REPORT.md
advisorygraphen project --space SPACE.json --report CHECK.json --audience audit_trace --format json --output AUDIT.json
advisorygraphen case import --store STORE --space SPACE.json --revision-id REVISION --format json
advisorygraphen case reason --store STORE --space-id SPACE_ID --format json
advisorygraphen case reason --store STORE --space-id SPACE_ID --exposure human_visible --format json
advisorygraphen case close-check --store STORE --space-id SPACE_ID --base-revision REVISION --format json
advisorygraphen case close-check --store STORE --space-id SPACE_ID --base-revision REVISION --exposure reflexive --format json
advisorygraphen case correct supersedes --store STORE --space-id SPACE_ID --target-id log:000002 --reviewer REVIEWER --reason REASON --base-revision REVISION --format json
advisorygraphen case correct invalidates --store STORE --space-id SPACE_ID --target-id log:000002 --reviewer REVIEWER --reason REASON --base-revision REVISION --format json
advisorygraphen case correct resolves --store STORE --space-id SPACE_ID --target-id OBSTRUCTION_ID --reviewer REVIEWER --reason REASON --base-revision REVISION --format json
advisorygraphen completions accept --store STORE --candidate-id CANDIDATE --from-report COMPLETIONS.json --reviewer REVIEWER --reason REASON --base-revision REVISION --format json
advisorygraphen completions reject --store STORE --candidate-id CANDIDATE --from-report COMPLETIONS.json --reviewer REVIEWER --reason REASON --base-revision REVISION --format json
advisorygraphen completions apply-accepted --store STORE --space-id SPACE_ID --reviewer REVIEWER --reason REASON --base-revision REVISION --format json
advisorygraphen hypothesis propose --space SPACE.json --from-report CHECK.json --output HYPOTHESIS_PROPOSALS.json --format json
advisorygraphen observation record --store STORE --space-id SPACE_ID --from-projection AI_AGENT.json --task-id TASK_ID --result OBSERVATION_RESULT.json --reviewer REVIEWER --reason REASON --base-revision REVISION --format json
advisorygraphen hypothesis apply-proposals --store STORE --from-report HYPOTHESIS_PROPOSALS.json --policy POLICY.json --reviewer ai-agent:codex --reason REASON --base-revision REVISION --format json
advisorygraphen hypothesis falsify --store STORE --from-report CHECK.json --hypothesis-id HYPOTHESIS --evidence EVIDENCE_ID --reviewer REVIEWER --reason REASON --base-revision REVISION --format json
advisorygraphen hypothesis support --store STORE --from-report CHECK.json --hypothesis-id HYPOTHESIS --evidence EVIDENCE_ID --reviewer REVIEWER --reason REASON --base-revision REVISION --format json
advisorygraphen hypothesis accept  --store STORE --from-report CHECK.json --hypothesis-id HYPOTHESIS --evidence EVIDENCE_ID --reviewer REVIEWER --reason REASON --base-revision REVISION --format json
advisorygraphen hypothesis reject  --store STORE --from-report CHECK.json --hypothesis-id HYPOTHESIS --evidence EVIDENCE_ID --reviewer REVIEWER --reason REASON --base-revision REVISION --format json
advisorygraphen propose --input INPUT.json --case CASE_DIR --package technical_advisory --ruleset technical_advisory_mvp --audience ai_agent --format json
advisorygraphen status --case CASE_DIR --format json
advisorygraphen status --case CASE_DIR --brief --format json
advisorygraphen report --case CASE_DIR --audience ai_agent --format json --output AI_AGENT.json
advisorygraphen review completion accept --case CASE_DIR --candidate-id CANDIDATE --reviewer REVIEWER --reason REASON --base-revision REVISION --format json
advisorygraphen review completion reject --case CASE_DIR --candidate-id CANDIDATE --reviewer REVIEWER --reason REASON --base-revision REVISION --format json
advisorygraphen review hypothesis support --case CASE_DIR --hypothesis-id HYPOTHESIS --evidence EVIDENCE_ID --reviewer REVIEWER --reason REASON --base-revision REVISION --format json
advisorygraphen review hypothesis falsify --case CASE_DIR --hypothesis-id HYPOTHESIS --evidence EVIDENCE_ID --reviewer REVIEWER --reason REASON --base-revision REVISION --format json
advisorygraphen review hypothesis accept --case CASE_DIR --hypothesis-id HYPOTHESIS --evidence EVIDENCE_ID --reviewer REVIEWER --reason REASON --base-revision REVISION --format json
advisorygraphen review hypothesis reject --case CASE_DIR --hypothesis-id HYPOTHESIS --evidence EVIDENCE_ID --reviewer REVIEWER --reason REASON --base-revision REVISION --format json

report --audience ai_agent supports JSON only; Markdown is a hard validation error.

Every projection carries exposure (human_visible or reflexive) and exposure_source (audience_default or caller_declared), alongside projection_loss_metrics. exposure declares whether the projection re-enters an AI agent's own context; ai_agent defaults to reflexive (the primary case: the projection is fed back to the agent that authored the snapshot), every other audience defaults to human_visible. exposure is an audience-derived convention, not an observed route fact — exposure_source records whether the value came from that default or from an explicit override. project --exposure human_visible|reflexive, case reason --exposure human_visible|reflexive, and case close-check --exposure human_visible|reflexive override the default on the flagship reflexive loop (the case-log-replayed ai_agent/audit_trace projections); facade report/propose have no override knob and simply inherit the audience default, consistent with how the facade layer already hides other project knobs. This is declaration and audit visibility only and changes no command's behavior.

Dogfood evaluation protocol (concealed/exposed/removed)

When running as part of a resident dogfood cycle (see docs/20-dogfood-evaluation-protocol.md), mark which arm the current run belongs to before acting:

• Exposed (default): the ai_agent projection is fed back to you as usual — no override needed, exposure stays reflexive.
• Concealed / removed: an evaluator generates case reason/case close-check/project --audience ai_agent with --exposure human_visible and does not show you the result this cycle; you act on your own judgment only. Do not request or read the withheld projection.

After the cycle, the arm and its outcome are recorded as an observation event in the case log: prefer observation record (add an additive dogfood_protocol: {arm, fixture_id, cycle, question} object inside --result, alongside the required observation_status/evidence_ids/ summary/supports_hypothesis/falsifies_hypothesis fields) when the flagged obstruction has a matching task under recommendation_trace.follow_up_observations; otherwise add an agent observation record (docs/03-data-contracts.md § Agent observation records) with the same metadata.dogfood_protocol shape and bring it in via case import. See docs/20-dogfood-evaluation-protocol.md for the full protocol, including the narrow-source calibration workstream.

Minimum external smoke test

For a new external installation or agent bundle, run:

advisorygraphen validate --input examples/dogfood/agent-operations/advisory.input.json --format json
advisorygraphen lift --input examples/dogfood/agent-operations/advisory.input.json --package technical_advisory_mvp --output /tmp/advisory.space.json --format json
advisorygraphen check --space /tmp/advisory.space.json --ruleset technical_advisory_mvp --output /tmp/advisory.check.json --format json
advisorygraphen completions propose --space /tmp/advisory.space.json --from-report /tmp/advisory.check.json --output /tmp/advisory.completions.json --format json
advisorygraphen completions dry-run --space /tmp/advisory.space.json --from-report /tmp/advisory.completions.json --output /tmp/advisory.dry-run.json --format json
advisorygraphen project --space /tmp/advisory.space.json --report /tmp/advisory.check.json --completions-report /tmp/advisory.completions.json --audience ai_agent --output /tmp/advisory.ai-agent.json --format json

Expected smoke result:

• commands exit successfully;
• obstructions may be present and are domain findings, not CLI failures;
• completion candidates remain review_status: unreviewed;
• proposal_content_summary is present in the AI-agent projection;
• correspondence_analysis is present in the AI-agent projection;
• dry-run entries include higher_graphen_gluing_review;
• projection loss is present and must be disclosed;
• no candidate is treated as accepted structure.

Hypothesis-to-proposal evaluation smoke

Run this medium fixture when validating AdvisoryGraphen's main value: controlling early AI convergence and over-proposal before recommendations become primary.

advisorygraphen validate --input examples/evaluation/medium-hypothesis-proposal/advisory.input.json --format json
advisorygraphen lift --input examples/evaluation/medium-hypothesis-proposal/advisory.input.json --package technical_advisory --output /tmp/medium-hypothesis.space.json --format json
advisorygraphen check --space /tmp/medium-hypothesis.space.json --ruleset technical_advisory_mvp --output /tmp/medium-hypothesis.check.json --format json
advisorygraphen completions propose --space /tmp/medium-hypothesis.space.json --from-report /tmp/medium-hypothesis.check.json --output /tmp/medium-hypothesis.completions.json --format json
advisorygraphen project --space /tmp/medium-hypothesis.space.json --report /tmp/medium-hypothesis.check.json --completions-report /tmp/medium-hypothesis.completions.json --audience ai_agent --output /tmp/medium-hypothesis.ai-agent.json --format json

Expected evaluation result:

• check contains proposal_derived_from_unsupported_hypothesis;
• check contains high_priority_proposal_missing_hypothesis_refinement;
• completion candidates are follow_up_observation, not primary;
• ai_agent.recommendation_trace.primary_count is 0;
• ai_agent.recommendation_trace.follow_up_observation_count is non-zero;
• ai_agent exposes ranked_observation_tasks;
• ai_agent exposes hypothesis_promotion_workflow;
• the fixture demonstrates that unsupported or unrefined AI proposals remain observation tasks until supporting evidence is recorded and reviewed.