h-spec

name	h-spec
description	Manage Haft's typed specification lifecycle and source-currentness repair: inspect current SpecSections, draft or clarify carriers, classify FPF semantic fanout, record operator-requested spec changes, and cross explicit approve/rebaseline/reopen gates only with human authorization. Use for "spec status", "update specs", "запиши в спеки", stale spec sections, newer FPF source revisions, or semantic changes that must be repaired across several spec carriers. Treat markdown as a carrier and the kernel projection as the lifecycle contract. Use h-status for read-only module/file coverage and h-onboard for first bootstrap.
when_to_use	A specification description, carrier, lifecycle state, or cross-carrier semantic repair is current.
argument-hint	[spec question, section id, or clarification]
allowed-tools	Bash Read Grep Glob Write Edit mcp__haft__haft_query mcp__haft__haft_spec_section mcp__haft__haft_onboard

h-spec — Typed spec lifecycle and semantic repair

Keep object, description, carrier, and authority separate:

• object: the system, behavior, role, boundary, or term being described;
• description: the SpecSection claim;
• carrier: .haft/specs/*.md and its fenced block;
• lifecycle authority: the kernel projection plus explicit human gates.

TargetSystemSpec, SoftwareSystemSpec, and related carrier names are Haft local-practice concepts. Do not attribute a target system vs enabling system kind distinction to FPF A.1. When FPF precision is needed, recover the actual holon/system, context, transformation, role, method, WorkPlan, and Work relations from the source.

Conditional project-memory orientation

When this specification work is context-heavy, multi-session, or reliance-bearing and the exact EntityOfConcern is not already current, resolve its identity with haft_query(action="memory", memory_request={"mode":"resolve","contract_version":"haft.memory.v1", "basis":{"kind":"project_current"},"query":"...","max_candidates":5}). Select the exact candidate by the current use rather than rank, then use the closed memory_request neighborhood branch advertised by the tool schema with projection_profile_ref="agent_orientation.v2".

Inspect result_kind before relying on content. project_basis_unavailable, known absence, or explicit abstention is visible but non-blocking: continue the spec lifecycle work without inventing a profile, entity, artifact, or human gate. This read does not replace code-graph preflight before editing code or a generated carrier. Never persist typed memory merely because a read failed; persistence requires an explicit operator save request or a concrete operator-named or agent-inferred receiving use supplied by current Work, with request provenance.

1. Read lifecycle first

mcp__haft__haft_spec_section(action="lifecycle")

lifecycle and next_step are project/scope-level ProjectSpecificationSet workflow projections. Never pass section_id to them and never read their ready or terminal result as the lifecycle state of one named section. For an exact section, use haft_query(action="spec_trace", section_id="<id>") to inspect its current edition, status, and baseline, then haft_query(action="spec_use", section_id="<id>", use_context="<concrete receiving use>") when stronger-use admission is current. The kernel rejects an action-inapplicable section_id and returns these recovery routes rather than silently ignoring it.

If the MCP action is unavailable, use haft spec next --json or haft spec status --json as the read-only projection of the same lifecycle contract and report that fallback. Do not infer lifecycle state from carrier grep or Markdown status fields. In status output, keep workflow and health separate: workflow ready means no next onboarding phase, not a clean health check, current baseline, or release readiness.

Missing canonical profile

When the same spec request returns profile_underdetermined, preserve that request, including its exact ScopeID when one was supplied. Treat recovery_surface=haft_onboard and next_action as navigation, not admission authority:

1. Read haft_onboard(action="status").
2. For needs_profile, prepare at most a non-binding review.
3. For profile_review_ready, show the readable review without applying it.
4. Apply only after the operator directly and unambiguously selects the exact reviewed profile and scope; the host routes that request through h-onboard without requiring a skill name.
5. After apply and any required restart, retry the same specification request.

Unrelated draft or clarification work may continue only when it does not rely on profile applicability. Never infer or auto-admit a profile, select software for convenience, or invent a SpecSection lifecycle state.

TargetSystemSpec relation boundary

For every declared realization scope, TargetSystemSpec is Required even when the profile carries entity_reference: none. The optional entity_reference supports exact EntityOfConcern memory, traceability, and stronger identity-bearing use; it is not a specification-applicability gate. Do not prepare or apply a profile change merely to continue TargetSystemSpec lifecycle.

If a current lifecycle response still reports missing_basis=admitted_target_system_relation, treat the connected runtime or installed skill projection as stale. Rebuild or reconnect the exact candidate, then retry the unchanged read-only request. Do not ask the operator to choose a target relation as recovery for this lifecycle condition.

Changing or replacing an existing entity_reference remains a separate profile effect only when that relation itself is the current question. It does not authorize a SpecSection approve, rebaseline, or reopen act.

Use state, current action, object, carrier, section identity, workflow_intent, and human_gate as returned. A lifecycle action belongs to this spec state machine; it is not a universal project phase.

2. Draft or clarify

For draft or clarify:

1. Read workflow_intent.context_for_agent, expected fields, checks, and carrier.
2. Ground the draft in repository evidence: existing specs, source entry points, build/test configuration, decisions, and relevant docs.
3. Ask at most 1-3 questions only for values the repository cannot establish.
4. Edit the fenced yaml spec-section block and keep uncertainty explicit.
5. Run haft spec validate to check authored draft and active carriers without profile-applicability filtering, then call lifecycle again. Use haft_query(action="spec_validate") for the same read-only structured report through MCP.

spec validate composes L0/L1/L1.5 structural checks with advisory semantic review. It keeps no active sections as a separate lifecycle observation, not as a reason to skip draft semantics. It does not determine applicability, activate or approve a section, create evidence, admit stronger use, mutate a carrier, or establish compatibility with a newer FPF source revision. Use haft spec check separately when the current question is profile-applicable spec health rather than draft-carrier validation.

Do not maintain a second schema template in this skill.

SoftwareSystemSpec scope

When workflow_intent.document_kind=software-system, describe the idealized software that realizes the active TargetSystemSpec in Haft's local carrier model. TargetSystemSpec is not asserted here as an FPF Core kind:

• assigned role and responsibility allocation;
• functional and procedural behavior;
• externally meaningful interfaces;
• software constraints and selected structure.

Do not put the team, coding agents, delivery workflow, release policy, MethodPack rules, or evidence-production policy into SoftwareSystemSpec. Those belong to the engineering/enabling system and its own carriers or configuration. Also do not use SoftwareSystemSpec as an implementation plan, source-tree tour, or runtime evidence report. It states the current software contract; performed work and evidence remain separate artifacts.

3. Record an operator-requested change

Phrases such as запиши в спеки, update the spec, or put this into the software spec authorize the relevant carrier edit. They do not authorize approve, rebaseline, reopen, or a binding DecisionRecord.

If the carrier is ambiguous, use lifecycle and ask one narrow question. Do not guess among target, software, and term-map concerns. These are Haft routing labels, not a claim that FPF prescribes three corresponding system kinds.

4. Internal semantic fanout review

When a term, kind assignment, claim strength, or boundary changes across carriers, run this routine inside h-spec:

1. Find every authored occurrence and generated mirror.
2. Classify each as definition, use, alias, historical citation, generated projection, or unrelated homonym.
3. Preserve the governed object and claim strength; do not perform blind text replacement.
4. Update only affected carriers and list deliberate non-changes.
5. Run spec checks and report remaining fanout.

When one boundary sentence mixes definition, admissibility, commitment, and evidence, unpack those L/A/D/E claims internally before editing. These are subroutines, not public skills.

Source-currentness repair

When a SpecSection claim cites or relies on FPF meaning:

1. Recover the exact current direct pattern body and source identity through FPF Query before editing the claim.
2. Compare the claim with that source. A green structural check or semantic review of the existing claim register does not establish compatibility with a newer FPF source revision.
3. Classify each affected occurrence as current source meaning, Haft local-practice/API vocabulary, sealed legacy compatibility spelling, historical citation, or unrelated homonym.
4. Prepare an explicit before/after semantic change for every affected active section and name the implementation or wire surface that must change with it. Never repair source drift by blind token replacement.
5. Keep source compatibility, implementation evidence, and SpecSection baseline currentness as separate results.

In particular, an implementation symbol such as MemberOf or EntitySet may remain a sealed legacy compatibility name while the current specification uses the source-native classification objects. Never present a compatibility spelling as current FPF meaning merely because old code or records still expose it. Recover the current C.3 pattern body instead of maintaining a shadow C.3 inside this skill.

5. Human gates

• approve: show the section and obtain explicit operator approval before changing draft status or calling approve.
• triage: show findings and the admissible rebaseline, reopen, rollback, deprecate, or supersede choices. Call a mutation only after the operator selects one and supplies or accepts its reason.

Before requesting either gate, give a self-contained Human Gate Brief. Name the lifecycle act and every affected section by readable title and ID, the exact semantic fields or relations that would change, what remains unchanged, and why only the affected operation is blocked. List every real option now and, for each, the immediate consequence or return condition and weakest link. Summarize an existing comparison/parity basis and non-dominated or Pareto set when one exists; for a fixed apply/defer/reject lifecycle choice, explicitly say that no Pareto front exists or applies. State the advisory recommendation, freshness or expiry of the review/dry-run, and ask for the human engineer's assessment of the options, trade-offs, and recommendation in natural language. IDs, hashes, human_gate, and requires_operator_act are audit data, not substitutes for this explanation. The brief itself is not approval.

Accept ordinary language as the substantive answer to the engineering consultation, never as a lifecycle receipt. Never ask the engineer for a command, skill invocation, exact reply phrase, or resumption token as a substitute for explaining and choosing the lifecycle outcome. Only after the engineer's position is explicit may a separately required lifecycle act be explained, together with what it will and will not authorize.

Do not silently reclassify enabling-system policy as software behavior during migration. Keep unresolved policy outside the SoftwareSystemSpec carrier and surface the required human classification. Never bind a DecisionRecord from this skill.

6. Relate the current edition to project memory

When an exact current SpecSection edition and exact EntityOfConcern are both needed by a concrete operator-named or agent-inferred receiving use, project their non-binding relation:

mcp__haft__haft_spec_section(
  action="project",
  section_id="<exact section id>",
  entity_ref={
    "ref_kind_id":"U.EntityRef",
    "reference_id":"<exact current EntityOfConcern>"
  },
  bounded_context_ref="<exact current bounded context>"
)

This reloads the exact current SQL edition, seals its semantic hash, and may admit Haft.SpecSectionAtConcern. It returns a Haft.SpecSectionRecordRef when committed. The action does not edit the carrier and cannot approve, rebaseline, reopen, or otherwise cross a lifecycle gate. Never infer a concern identity from a section title.

Result

Report lifecycle state, current local action, carrier and human-readable section identity, edits, checks, any exact projected record_reference, and any open human gate. Use h-status for read-only decision coverage of modules or files.