documentation-placement

name	documentation-placement
description	Document placement using timeline test and HestAI visibility rules. Maps artifacts to .hestai-sys/, .hestai/, docs/, .hestai/state/ with phase artifact rules, format selection, anti-patterns, and documentation-first protocols.
allowed-tools	["Read","Write","Bash"]
triggers	["documentation placement","ADR placement","phase artifact","documentation first","B1 migration gate","visibility rules"]

===DOCUMENTATION_PLACEMENT=== META: TYPE::SKILL VERSION::"2.3" STATUS::ACTIVE COMPRESSION_TIER::AGGRESSIVE DOMAIN::HERMES[communication]+HESTIA[structure]

§1::CORE_PRINCIPLE

TIMELINE_TEST::[ IF[document_before_code]→.hestai/north-star/|.hestai/rules/, IF[document_describes_implementation]→docs/, IF[document_guides_implementation]→docs/, IF[operational_state_or_tracking]→.hestai/state/context/, IF[session_or_handoff]→.hestai/state/sessions/ ]

RATIONALE::"Timeline→placement: planning=.hestai/, implementation=docs/, operational=.hestai/state/"

CANONICAL_REFERENCE::.hestai-sys/standards/rules/visibility-rules.oct.md

§2::REPOSITORY_STRUCTURE

// Per visibility-rules.oct.md v1.7

SYSTEM_GOVERNANCE[.hestai-sys/]::[ READ_ONLY[injected_from_src/hestai_mcp/_bundled_hub/], standards/workflow/→"System North Star (000-SYSTEM-HESTAI-NORTH-STAR.md)", standards/rules/→"Naming standard, visibility rules, test standards", agents/→"Agent definition templates (.oct.md)", templates/→"Project scaffolding templates", library/skills/→"Ecosystem-wide operational skills", library/agents/→"Agent definitions", library/patterns/→"Reusable patterns and examples", library/schemas/→"Schema definitions", library/octave/→"OCTAVE usage guides", tools/→"System utility scripts (validators, checkers)" ]

NOTE::"Agents CANNOT place artifacts in .hestai-sys/ — it is injected read-only at runtime"

PROJECT_GOVERNANCE[.hestai/]::[ north-star/→"North Star documents (000-*-NORTH-STAR.md + components/)", decisions/→"Compiled governance decisions (debate outcomes, NOT ADRs)", rules/→"Project standards, methodology, workflow guidance, specs", schemas/→"Schema definitions" ]

DEVELOPER_DOCS[docs/]::[ adr/→"ADR-NNNN-topic.md (GitHub issue-based numbering per ADR-0031)", api/→"API endpoint documentation", development/→"Setup guides", deployment/→"Deployment guides" ]

OPERATIONAL_STATE[.hestai/state/]::[ context/→"PROJECT-CONTEXT.md, PROJECT-CHECKLIST.md, PROJECT-HISTORY.md", context/apps//→"APP-CONTEXT.md, APP-CHECKLIST.md, APP-HISTORY.md", sessions/active/→"Active session working state", sessions/archive/→"YYYY-MM-DD---octave.oct.md (committed) + raw.jsonl (gitignored)", reports/→"YYYY-MM-DD-* audit reports, scan outputs, quality gate evidence" ]

DEBATE_ARTIFACTS[debates/]::[ json→GITIGNORED[full_debate_machine_format], oct.md→COMMITTED[compressed_debate_synthesis] ]

CLAUDE_CODE[.claude/]::[ agents/→"Agent definitions (.oct.md)", commands/→"Slash commands", skills/→"Project-specific skills (per-repo, NOT ecosystem-wide)", hooks/→"Git workflow automation" ]

NOTE::.claude/skills/→project_specific|.hestai-sys/library/skills/→ecosystem_wide

§3::PHASE_ARTIFACT_MAPPING

// Lifecycle: Spec (the plan) → Report (the evidence) → Doc (the product) // Artifacts graduate through the lifecycle as phases progress

PLACEMENT::[ D1_NORTH_STAR::.hestai/north-star/[immutable_anchor], D2_IDEAS_CONSTRAINTS_DESIGN::.hestai/rules/specs/[active_spec], D3_BLUEPRINT::.hestai/rules/specs/[spec_MIGRATES_to_docs/_at_B1_gate], B0_VALIDATION::.hestai/state/reports/[gate_evidence], B1_BUILD_PLAN::.hestai/rules/specs/[task_breakdown_for_B2], B2_IMPLEMENTATION_LOG::.hestai/state/reports/[evidence_stream], B3_QA_SECURITY::.hestai/state/reports/[audit_trail], B4_HANDOFF_USER_GUIDE::docs/[graduated_permanent_documentation] ]

GRADUATION_RULES::[ D3_blueprint→migrates_from_.hestai/rules/specs/_to_docs/_at_B1_gate, B0_architectural_decisions→recorded_as_ADRs_in_docs/adr/, B4_handoff_docs→graduate_from_draft_to_docs/_at_delivery ]

ADR_SUPREMACY::[ RULE::"When in doubt between .hestai/decisions/ and docs/adr/ → choose docs/adr/", .hestai/decisions/→compiled_debate_decisions[agent_facing_OCTAVE_governance_outcomes], docs/adr/→all_architecture_implementation_design_decisions[developer_facing_markdown], DISTINCTION::"debate-hall exports→.hestai/decisions/[.oct.md] | developer decisions→docs/adr/[.md]" ]

§4::FORMAT_SELECTION

// Per visibility-rules.oct.md FORMAT_RULES + FILE_RETENTION_POLICY

OCTAVE_FORMAT[.oct.md]::[ agent_definitions, governance_rules, north_star_summaries[agent_consumed], methodology_docs, context_files[PROJECT-CONTEXT_etc], session_archives[compressed_semantic], compiled_debate_decisions ]

MARKDOWN_FORMAT[.md]::[ north_star_full[human_authored_strategic_vision], developer_guides[setup_deployment], ADRs[architecture_decisions], READMEs[navigation_pointers], human_first_documentation ]

NOTE::"Full North Stars (.md) are human-authored vision; summaries (.oct.md) are agent-optimized"

FORMAT_DECISION_TREE::[ "Primary audience AI agents?"→YES→.oct.md, "Standards/methodology/system-standard?"→YES→.oct.md, "Primary audience human developers?"→YES→.md, "ADR or setup guide?"→YES→.md ]

RETENTION_RULE::[ json_jsonl[raw]→GITIGNORED[machine_format+large+reconstructible], oct.md[compressed]→COMMITTED[semantic_density+audit_trail], "Raw machine formats are ephemeral; semantic compressions are permanent" ]

§5::DOCUMENTATION_FIRST_PROTOCOL

SEQUENCE::[ 1::write_docs_first[ADR+specification+blueprint], 2::merge_docs_PR[before_implementation], 3::implementation_PR_references_merged_docs[via_PR_number], 4::implementation_blocked_until_docs_merged ]

HANDOFF::"Docs PR merged (#N) → Implementation: 'Implements ADR-XXX (merged in PR #N)'"

MERGE_STRATEGY::[ D3_BLUEPRINT::immediate[before_B0], ADRs::immediate[before_implementation], API_DOCS::with_or_before_implementation, ARCHITECTURE_AS_BUILT::with_implementation, DEVIATIONS::as_discovered ]

§6::B1_MIGRATION_GATE

CONTEXT_REQUIREMENTS::[ B1_01_B1_02::.hestai/rules/specs/[design_phase_artifacts], MIGRATION_GATE::manual_checkpoint[verify_D3→docs/], B1_03_B1_05::docs/[implementation_documentation] ]

CRITICAL::"B1_02 in .hestai/rules/specs/, B1_03 in docs/ after manual migration"

§7::ANTI_PATTERNS

// From visibility-rules.oct.md ANTI_PATTERNS

AVOID::[ DUPLICATE_CONTENT::"ADRs ONLY in docs/adr/ — never in .hestai/", DEVELOPER_DOCS_IN_HESTAI::"Developers will not find setup guides in .hestai/ — use docs/", COMMIT_EPHEMERAL::"Session handoffs go to .hestai/state/sessions/ (shared state, not git)", MIX_ABSTRACTION_LEVELS::"Dashboard (PROJECT) guides to detail (APP) — no implementation in PROJECT-CONTEXT", NON_NORTH_STAR_IN_NORTH_STAR_FOLDER::"Only 000--NORTH-STAR files and components/ belong in north-star/", CONFUSE_DECISIONS_WITH_ADRS::".hestai/decisions/ = compiled governance decisions | docs/adr/ = formal ADRs", PLACE_IN_HESTAI_SYS::".hestai-sys/ is read-only injected — agents cannot write there" ]

§8::PROJECT_CONTEXT_STATUS

PURPOSE::"Mitigate worktree isolation with visible project status"

LOCATION::.hestai/state/context/PROJECT-CONTEXT.md

SECTIONS::[ feature_name_and_branch, blueprint_link::docs/, ADR_status::[MERGED+IN_REVIEW], current_phase::[B1+B2+B3+B4], PR_link[with_WIP_marker], agent_assigned ]

UPDATE_PROTOCOL::[ on_worktree_creation::update, on_PR_merge::complete, on_phase_gate::refresh ]

§9::ADR_FRONT_MATTER

ARCHITECTURE_DOCS::[ applies_to_tag, supersedes, superseded_by, schema_version, phase::D3, status::[ORIGINAL+AS_BUILT+DEVIATION] ]

ADR_DOCS::[ adr_number::"MUST match GitHub Issue number (zero-padded 4 digits)", title, status::[ACCEPTED+SUPERSEDED+DEPRECATED], decision_date::ISO_8601, implements::blueprint_section, deviates_from ]

NUMBERING_RULE::"ADR-<GITHUB_ISSUE_NUMBER>-.md with zero-padded 4 digits" LOCATION::docs/adr/ VALIDATION::scripts/ci/validate-doc-numbering.sh[enforced_on_push]

§10::CLEANUP_AT_PHASE_GATES

MANDATORY_POINTS::[ after_B1_02::before_migration, after_B2_04::before_B3, after_B3_04::before_B4, after_B4_05::before_delivery ]

AGENT_BOUNDARIES::[ directory-curator::"Reports only", workspace-architect::"Fixes violations, owns migrations", holistic-orchestrator::"Enforces at gates" ]

§11::INTEGRATION

TRIGGERS_WHEN::[documentation_created, artifact_placed, B1_migration] CONSULT::[holistic-orchestrator, workspace-architect, system-steward]

COMPANION_DOCS::[ .hestai-sys/standards/rules/visibility-rules.oct.md→"WHERE does artifact belong?", .hestai-sys/standards/rules/naming-standard.oct.md→"HOW to name once placed?", .hestai/rules/hub-authoring-rules.oct.md→"WHERE in system governance payload?" ]

WISDOMS::[ "Documentation_is_prerequisite_not_side_effect", "Timeline_determines_placement", "B1_migration_is_critical_checkpoint", "PROJECT-CONTEXT.md_prevents_worktree_blindness", ".hestai-sys/_is_read_only_system_governance" ]

===END===