@c4a/context-cli 0.6.19 → 0.7.0

package/indexers/bundles/context-markdown-indexer/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: context-markdown-indexer
+description: Context-managed Provider for evidence-bound document knowledge. Use only when the Context Indexer lifecycle selects this Provider, not as a standalone workflow.
+metadata:
+  context-role: "indexer-provider"
+  context-public-entry: "false"
+  context-provider-version: "1.0.0"
+---
+
+# Context Markdown Indexer
+
+Provider authors must satisfy
+`node_modules/@c4a/context/docs/guides/markdown-indexer-skill-authoring.md` and
+the shared Provider/customization guide before publishing or extending this
+Skill. Those documents are authoring contracts; the current captured evidence,
+workset and Route remain execution authority.
+
+Use this Provider only through the Context Indexer lifecycle. Context supplies exact captured sources, profile authority, worksets, and evidence views; the Provider does not read arbitrary workspace paths or write approved knowledge directly.
+
+The machine-readable authority is `context-indexer.yaml`. Context materializes the detailed guidance only after verifying this Bundle's release identity and complete file ledger.

package/indexers/bundles/context-markdown-indexer/context-indexer.yaml

@@ -0,0 +1,147 @@
+protocol: context.indexer.provider/v1
+id: context-markdown-indexer
+version: 1.0.0
+domains: [markdown]
+
+activation:
+  target_kinds: [document, document-set, documentation-site]
+  required_signals:
+    - id: captured-document
+      description: The registered target scope contains a current captured Markdown or structured document snapshot.
+  supporting_signals:
+    - id: explicit-audience
+      description: The source identifies a reader, task, policy, decision, procedure, or reference boundary.
+    - id: cross-source-evidence
+      description: The readable scope contains current corroborating material for unresolved claims.
+  negative_signals:
+    - id: transient-conversation
+      description: The material is an unapproved transient conversation without a durable source identity.
+  agent_questions:
+    - Which reader goal and authority apply to each source-backed Section?
+
+provides:
+  profiles:
+    - domain-reference
+    - product-requirements
+    - technical-guide
+    - user-and-developer-guide
+    - public-api-reference
+    - runbook
+    - faq-support
+    - standard-policy
+    - decision-record
+    - incident-review
+    - test-validation
+    - release-migration-guide
+    - documentation-site
+  operations:
+    - id: main-index
+      consumes: context.indexer.main-workset/v1
+      produces: context.indexer.main-result/v1
+      accepts_layer_fragments: [fact-enrichment, template-variables]
+    - id: material-answer
+      consumes: context.indexer.material-question-workset/v1
+      produces: context.indexer.material-answer-result/v1
+      supported_evidence_kinds: [contract, configuration, documentation, runbook, decision-record, test-result, runtime-observation, tool-snapshot]
+      accepts_layer_fragments: [fact-enrichment]
+  source_roles: [authoritative-document, supporting-document, operational-document, decision-record]
+  logical_units:
+    - id: reader-subject
+      identity: canonical-subject-key
+      artifacts:
+        recommended: [content]
+        supported_policy_variants: [standard]
+
+provider:
+  instructions:
+    - path: references/indexer.md
+      profiles:
+        - domain-reference
+        - product-requirements
+        - technical-guide
+        - user-and-developer-guide
+        - public-api-reference
+        - runbook
+        - faq-support
+        - standard-policy
+        - decision-record
+        - incident-review
+        - test-validation
+        - release-migration-guide
+        - documentation-site
+    - path: references/classification.md
+      profiles:
+        - domain-reference
+        - product-requirements
+        - technical-guide
+        - user-and-developer-guide
+        - public-api-reference
+        - runbook
+        - faq-support
+        - standard-policy
+        - decision-record
+        - incident-review
+        - test-validation
+        - release-migration-guide
+        - documentation-site
+    - path: references/structure-and-artifacts.md
+      profiles:
+        - domain-reference
+        - product-requirements
+        - technical-guide
+        - user-and-developer-guide
+        - public-api-reference
+        - runbook
+        - faq-support
+        - standard-policy
+        - decision-record
+        - incident-review
+        - test-validation
+        - release-migration-guide
+        - documentation-site
+    - path: references/semantic-planning.md
+      profiles:
+        - domain-reference
+        - product-requirements
+        - technical-guide
+        - user-and-developer-guide
+        - public-api-reference
+        - runbook
+        - faq-support
+        - standard-policy
+        - decision-record
+        - incident-review
+        - test-validation
+        - release-migration-guide
+        - documentation-site
+    - path: references/editorial-policy.md
+      profiles:
+        - domain-reference
+        - product-requirements
+        - technical-guide
+        - user-and-developer-guide
+        - public-api-reference
+        - runbook
+        - faq-support
+        - standard-policy
+        - decision-record
+        - incident-review
+        - test-validation
+        - release-migration-guide
+        - documentation-site
+  forbidden_fallbacks: [whole-document-single-classification, unsupported-section-publication, inferred-authority]
+  completion_checks: [section-disposition-closure, source-authority-binding, material-gap-closure]
+
+customization:
+  supports: [config, instructions-append, template-override, program-extend]
+
+quality_guidance:
+  metric_ids:
+    - inventory-disposition-coverage
+    - duplicated-fact-target-ratio
+    - narrative-enumeration-ratio
+    - normalized-template-repetition-ratio
+    - implementation-body-ratio
+    - reference-only-reader-targets
+    - unresolved-ordinal-partitions
+    - discretionary-artifacts-per-logical-unit

package/indexers/bundles/context-markdown-indexer/references/classification.md

@@ -0,0 +1,63 @@
+# Section classification and projection intent
+
+Classify evidence at Section granularity. A profile describes the source family;
+it does not force one whole document into one reader purpose. For every emitted
+Section, choose the semantic `document_kind`, `reader_goal`, and
+`artifact_kind` before grouping Sections into Artifacts.
+
+Use body evidence, source authority, audience, and the reader task. File names,
+URLs, headings, navigation labels, and the selected profile are hints, not proof
+that every Section has the same intent. Do not infer authority from polished
+language or an official-looking path.
+
+## Canonical projection vocabulary
+
+The current community Markdown profiles use the following semantic intents.
+The CLI profile contract owns their stable storage projection; this table does
+not authorize a collection or output path.
+
+| Profile or Section family | Use when the evidence primarily… | `document_kind` | `reader_goal` | `artifact_kind` |
+| --- | --- | --- | --- | --- |
+| `domain-reference` | defines a durable domain, vocabulary, boundary, or business concept | `domain-reference` | `understand-domain` | `content` |
+| `product-requirements` | states product intent, behavior, scope, actors, or acceptance needs | `product-requirements` | `understand-product-intent` | `content` |
+| `technical-guide` | explains architecture, runtime behavior, interfaces, or design constraints | `technical-guide` | `understand-technical-design` | `content` |
+| user/developer product guidance | explains a user-visible capability or product behavior | `product-requirements` | `understand-product-intent` | `content` |
+| user/developer technical guidance | explains implementation-facing design or integration context | `technical-guide` | `understand-technical-design` | `content` |
+| user/developer task guidance | gives a repeatable task, setup, operation, or troubleshooting sequence | `task-guide` | `complete-reader-task` | `content` |
+| public API contract | supports lookup of public operations, fields, compatibility, or examples | `public-api-reference` | `look-up-public-contract` | `content` |
+| public contract policy | states normative compatibility or usage constraints around a public contract | `public-contract-policy` | `follow-public-contract-policy` | `content` |
+| `runbook` | directs operation, diagnosis, mitigation, recovery, or rollback | `runbook` | `operate-or-recover-system` | `content` |
+| `faq-support` | answers a durable reader question with reusable evidence | `faq-support` | `resolve-reader-question` | `content` |
+| `standard-policy` | defines a stable rule, standard, policy, or compliance boundary | `standard-policy` | `follow-standard-or-policy` | `content` |
+| `decision-record` | records alternatives, a choice, rationale, and consequences | `decision-record` | `understand-decision-and-tradeoffs` | `content` |
+| `incident-review` | records impact, timeline, cause, response, and follow-up learning | `incident-review` | `learn-from-incident` | `content` |
+| `test-validation` | defines or reports verification, acceptance, or observed results | `test-validation` | `verify-behavior-or-acceptance` | `content` |
+| release explanation | explains what changed, compatibility, or release impact | `release-guide` | `understand-release-change` | `content` |
+| migration procedure | tells a reader how to migrate, verify, and recover | `migration-guide` | `complete-migration` | `content` |
+
+`documentation-site` is an umbrella router. Apply the matching row above to
+each source-backed Section; do not invent a site-wide projection intent and do
+not collapse a multi-document site to one classification.
+
+## Classification order
+
+1. Establish the Section's current source authority and audience from the
+   authorized evidence view.
+2. State the concrete question the Section enables a reader to answer or task
+   it enables them to complete.
+3. Choose the narrowest matching `document_kind` and `reader_goal` pair from
+   the current profile contract.
+4. Use `artifact_kind: content` for the current community Markdown Bundle. Do
+   not invent a specialized Artifact kind unless the supplied profile contract
+   explicitly registers it.
+5. Return the intent on every actual or template-projected Section. Do not put
+   a collection, directory, filename, or package root in the Result.
+
+When a Section mixes multiple reader tasks, split it along continuous evidence
+boundaries. Keep one Section only when the material forms one coherent answer
+for one reader goal. A heading change alone does not require a split, and a
+shared heading does not justify combining unrelated tasks.
+
+If no registered intent fits, return a material/capability disposition instead
+of selecting the nearest label. Unsupported or authority-ambiguous material
+must not become a reader Artifact.

package/indexers/bundles/context-markdown-indexer/references/editorial-policy.md

@@ -0,0 +1,106 @@
+# Section editorial policy
+
+Apply editorial decisions to one source-backed Section at a time. A signal is a
+review lead with a recommended outcome; it is not authority to change facts,
+cross Section boundaries, or discard evidence. Preserve exact links, code,
+commands, identifiers, numbers, conditions, attachments, and source meaning.
+
+The community policy owns scenario interpretation and revision guidance. The
+Context plan may also report syntax, protected-value, or safety-baseline
+signals. Use the same decision discipline for both, while leaving detection,
+source spans, stale checks, protected values, revision persistence, and final
+validation to Context.
+
+## Signal catalog
+
+| Signal | Meaning in the current Section | Confidence | Recommended outcome | Eligible omission reason |
+| --- | --- | --- | --- | --- |
+| `unanswered-question-set` | Multiple reader questions have no answer, decision, or next action. | `review` | `omit` only when the Section is only the unresolved question set; otherwise separate the supported material. | `unanswered-question` |
+| `answered-question-set` | Multiple questions already have source-backed answers. | `review` | `reshape` as a concise FAQ without deleting answers. | none |
+| `empty-table-row` | A reader-visible table row carries no value. | `high` | `repair` the table structure. | none |
+| `placeholder-content` | The Section contains only placeholder material. | `high` | `omit` the non-knowledge Section. | `empty-or-placeholder` |
+| `wide-table` | A table combines many columns with complex cells. | `high` | `reshape` into a short index and evidence-preserving details. | none |
+| `long-table-cell` | A table cell contains prose that no longer works as a lookup value. | `high` | `reshape` without summarizing away facts. | none |
+| `raw-or-unlabeled-link` | A destination is shown without a descriptive reader label. | `high` | `repair` the label or surrounding sentence while preserving the destination exactly. | none |
+| `adjacent-links` | Neighboring links do not explain their relationship. | `high` | `repair` the separator or labels without changing destinations. | none |
+| `volatile-query-url` | A destination appears session-, signature-, token-, or time-bound. | `review` | `request-input` unless current evidence proves a stable destination or the signal is a false positive. | none |
+| `strikethrough-only-block` | The Section contains only obsolete-looking struck-through material and no replacement. | `review` | `omit` when it has no continuing historical reader value. | `obsolete-without-replacement` |
+| `brainstorm-without-decision` | Proposals or open considerations appear without a recorded decision. | `review` | `omit` only the decision-free draft; do not infer an answer. | `draft-without-decision` |
+| `duplicate-fragment` | Equivalent reader-visible content already has a canonical source-backed representation. | `high` | `omit` the duplicate only after authority, lifecycle, and meaning are proved equivalent. | `duplicate-content` |
+| `unstable-owner-reference` | The Section appears to depend on a named individual rather than a durable responsibility. | `review` | `request-input`, or `keep` only when Section evidence proves the label is a stable role and the signal is a false positive. | none |
+| `sensitive-value-candidate` | Authorized evidence contains a credential-shaped or sensitive value candidate. | `review` | `request-input`; never reproduce a secret-like example in guidance or output. | none |
+| `heading-hierarchy-invalid` | Heading levels do not form a valid reader hierarchy. | `high` | `repair` headings without changing Section meaning. | none |
+| `heading-content-overloaded` | A heading contains link inventory or body content. | `high` | `repair` by moving details into the Section body. | none |
+| `markdown-syntax-damaged` | Reader Markdown is structurally incomplete or malformed. | `high` | `repair` the syntax before publication. | none |
+| `conversion-artifact` | Source-conversion annotations remain reader visible. | `high` | `omit` only the conversion residue. | `conversion-artifact` |
+| `mixed-facts-and-draft` | Stable statements and unresolved draft material are mixed together. | `review` | `reshape` to preserve supported facts and isolate the unresolved part. | none |
+
+Compact tables, answered limitations with impact and action, deprecations with
+a current replacement, and historical evidence with continuing reader value
+are knowledge. Do not omit them merely because a nearby signal name appears to
+fit. File length, page count, deadline, or effort never changes the outcome.
+
+## Outcomes
+
+- `keep`: use when there is no actionable signal, or for a `review` signal only
+  with a Section-specific assessment that proves a false positive or explains
+  why the proposed edit would damage source fidelity.
+- `repair`: make a local presentation correction without changing facts or
+  protected values.
+- `reshape`: reorganize the same supported material without broadening,
+  narrowing, or summarizing away its evidence.
+- `omit`: remove only an explicitly eligible non-knowledge fragment with the
+  exact omission reason supplied by the plan.
+- `request-input`: pause for information that cannot be recovered from the
+  authorized Section or evidence view. It is an outcome, not a silent `keep`.
+
+Resolve safe actions across the complete current workset. A large batch is not
+a reason to default to `keep`, skip a Section, or lower the quality standard.
+In managed operation, complete every independently safe action without adding a
+routine review pause. Managed authority does not lower these rules and does not
+turn genuinely missing input into `keep`; ask once for the remaining batched
+input after completing the independent analysis.
+
+## Assessment contract
+
+An assessment is required only when keeping a reported `review` signal or when
+a repaired/reshaped result retains a review signal after rescan. It must:
+
+1. be Section-specific rather than copied across a batch;
+2. name every remaining signal code;
+3. cite concrete source evidence for a false positive, or state the exact
+   source fidelity loss the recommended edit would cause;
+4. explicitly say `false-positive` for a kept `request-input` signal;
+5. never cite time, cost, effort, workload, batch size, deadline, or progress.
+
+A `high` signal cannot be justified by assessment and kept unchanged; it must
+be resolved. A Section without a signal can be kept without an assessment.
+Every repair or reshape is subject to the same post-revision signal scan and
+protected-value validation; selecting an action is not proof of resolution.
+
+## Anonymous decision examples
+
+- Two unanswered planning questions with no decision: choose `omit` with
+  `unanswered-question`; never invent the answers.
+- Two source-backed question/answer pairs: choose `reshape` into an FAQ and
+  retain both answers and their evidence.
+- A compact two-column lookup table: choose `keep`; width alone is not a
+  `wide-table` signal.
+- A five-column table containing long links and prose: choose `reshape` into an
+  index plus details while preserving destinations and values.
+- `Owner: platform-operations` where the same Section defines that string as a
+  durable role: `keep` may be justified with
+  `unstable-owner-reference: false-positive because the source defines a stable responsibility`.
+- A signed or expiring destination with no stable replacement in evidence:
+  choose `request-input`; do not copy its sensitive query value into the
+  assessment.
+- A current rule followed by an undecided proposal: choose `reshape`, retain
+  the rule, and isolate the proposal rather than omitting the whole Section.
+- Struck-through text that is the only surviving historical record may be kept
+  only with a Section-specific `strikethrough-only-block` assessment explaining
+  the exact source fidelity loss; ordinary obsolete-only prose should be
+  omitted.
+
+Before returning a decision, confirm every Section has one outcome, every kept
+signal has a valid assessment, every omission has an eligible reason, and no
+revision changes authority, evidence, identity, or protected values.

package/indexers/bundles/context-markdown-indexer/references/indexer.md

@@ -0,0 +1,23 @@
+# Markdown Indexer authoring contract
+
+Classify and author at the source-backed Section level. A document profile describes reader intent; it is not an output directory. Mixed documents may contain Sections with different reader goals, but every Section must retain one stable subject, owner, source authority, and projection intent.
+
+Use `classification.md` as the semantic source for `document_kind`, `reader_goal`, and current `artifact_kind` selection. Use `structure-and-artifacts.md` for mixed-document routing, Section-versus-Artifact promotion, density, duplicate/conflict handling, and target candidate resolution. The CLI-supplied profile contract remains the only authority for collection and path projection.
+
+Use `semantic-planning.md` for evidence authority, SubjectKey/target-resolution
+judgment, relation and structured-claim gates, content-purpose precision, and
+stale/collision recovery behavior. It adapts the useful semantic gates from the
+former align path to the current Result ABI; it does not authorize legacy align
+commands or `context.structure.v1`.
+
+Use `editorial-policy.md` for scenario editorial signals, recommended outcomes, Section-specific assessments, omission eligibility, and anonymous decision examples. Context still owns signal spans, protected values, revision CAS/storage, rescans, and final validation.
+
+Preserve exact commands, identifiers, links, attachments, tables, and code blocks when they are evidence-bearing. Separate deterministic catalogs from explanation. Do not publish unsupported claims, conversion annotations, placeholders, or unresolved requests as knowledge.
+
+When current source material cannot answer a required canonical question, return the exact material-question disposition for the supplied target. Answers may use only authorized evidence kinds and spans. Context owns review, layout, collection mapping, material-gap persistence, quality thresholds, and final close.
+
+Follow the operation in the supplied run request. For `main-index`, return only the current `IndexerResult`/`ArtifactResult` contract; Context derives the exact source-span, selected-fact, logical-unit, Artifact, and negative group-input dependencies from that result. For `material-answer`, return only `context.indexer.material-answer-result/v1`. Each binding must echo one eligible `question_key`, its exact `question_revision_digest`, and canonical evidence claims containing only `kind`, authorized `source_ref`, normalized `source_spans`, and the current content `evidence_digest`. Do not return reader prose, an answer body, source-origin/input identities, an `EvidenceItemRef`, a future Artifact/Section identity, or an actualization. Context canonicalizes evidence, performs the limited Review, derives a body-free planned answer from the approved binding, and maps its supplied answer landing after layout.
+
+Never create a legacy `MarkdownCollectionSlice` or invoke the independent `alignProse` phase. Never mix `main-index` and `material-answer` output.
+
+Do not return output paths, collection names, arbitrary question text, new authority, or pass/fail claims.

package/indexers/bundles/context-markdown-indexer/references/semantic-planning.md

@@ -0,0 +1,146 @@
+# Evidence, subject, and claim planning
+
+Use these rules while producing the operation selected by the current run
+request. For the current `main-index` `ArtifactResult`, apply every rule below. For
+`material-answer`, produce only evidence claims for eligible questions; the
+question identity, landing, canonical evidence items, planned-answer projection
+and post-layout actualization remain Context-owned. These rules preserve the
+useful semantic judgments from the former classification and align path without
+restoring `context.structure.v1`, collection selection, or a second write
+workflow. Context remains the authority for schemas, SubjectKey normalization,
+identities, paths, collisions, stale state, layout changes, Review, and
+publication.
+
+## Evidence and authority
+
+Read every authorized evidence item required by the current workset before
+making a source-wide decision. A file name, URL, title, heading, navigation
+label, polished wording, profile id, or example is a navigation signal, not
+proof of subject identity, authority, or reader intent.
+
+Use only current source roles, evidence bindings, target-resolution views, and
+question targets supplied with the workset. Supporting or context-only material
+may guide investigation but cannot become a cited Section or structured claim
+unless the current authority makes it eligible. Preserve exact identifiers,
+commands, links, numbers, conditions, code, and source-authored uncertainty.
+
+Positive example: a Section is classified from its complete requirement text
+and stated audience. Negative example: a document is classified as a runbook
+only because its path contains `ops/`.
+
+## Subject boundary
+
+The primary logical-unit SubjectKey is fixed by the workset. Do not replace it
+with a title-derived key. When Context supplies target-resolution entries,
+close every entry with exactly one current disposition:
+
+- `reuse-existing` only for an exact evidence-supported subject match;
+- `create-independent` only when evidence establishes a distinct durable
+  subject and separate reader value under a permitted SubjectKey schema;
+- `request-material` when a semantic decision is possible but identity facts
+  or authority are insufficient;
+- `unsupported` when the required parser, evidence kind, or capability is not
+  available.
+
+Treat local material as a Section before proposing an independent subject or
+Artifact. A heading, table row, FAQ label, warning, short example, relationship
+phrase, or one-off conclusion does not establish independent identity. A
+concrete product or technical object, an atomic term, a repeatable process with
+source-backed steps and outcome, or a real grouping scope with supported child
+subjects may justify a separate subject when the current schema permits it.
+
+Positive examples include an independently named service with its own contract,
+or a repeatable recovery procedure with actors, steps, outcome, and standalone
+retrieval value. Negative examples include “component usage” as one sentence,
+“three modes” as a parallel list, a navigation-only placeholder, or “X impact
+on Y” without an independent referent. Keep those as Sections, registered
+questions, or unresolved target decisions as appropriate.
+
+Titles and headings are evidence, not identity. Keep reader-facing labels in
+the authored content; do not invent aliases, slugs, collections, containment,
+or paths to force a match. A subject shaped like a grouping scope needs current
+supported child identities. A process-shaped subject needs actual process
+evidence, not merely a word such as “flow”, “migration”, or “strategy”.
+
+## Section and Artifact planning
+
+Apply `classification.md` and `structure-and-artifacts.md` at Section scope.
+Keep source-backed Sections continuous when possible. Split unrelated reader
+tasks even under one heading; merge adjacent headings only when they form one
+coherent answer with compatible projection intent. A dedicated Artifact must
+clear the same independent reader-task and evidence-boundary test regardless of
+content type.
+
+Use density only to choose an inspection granularity. `macro`, `meso`, `micro`,
+and `single-pass` never choose a SubjectKey, authority, projection intent, or
+quality outcome.
+
+## Relation and structured-claim gate
+
+Emit a structured claim only when its subject is authorized, its owner Section
+exists, and the cited evidence in that same Section supports the claim kind.
+Do not convert a vague “related” mention, shared table membership, name
+similarity, containment, or endpoint-only evidence into a stronger relation.
+When evidence conflicts and source precedence does not resolve it, preserve the
+conflict in the supported diagnostic or material-question disposition instead
+of selecting by file order, heading order, or polished wording.
+
+Source-authored uncertainty belongs in the reader prose when it is material.
+Do not use a confidence label to conceal Agent uncertainty, and do not invent a
+structured field that the current schema does not expose. Missing endpoint,
+ownership, or relation evidence must remain unresolved rather than becoming a
+dangling claim.
+
+Positive example: a cited Section explicitly states that one component consumes
+another component's output, and both subjects are authorized. Negative example:
+two components appear in one “See also” list, so the Indexer invents a runtime
+dependency.
+
+## Content-purpose precision
+
+Choose the narrowest registered Section projection intent. Preserve these
+semantic boundaries when they apply:
+
+- a decision needs alternatives or options, the selected path, and rationale;
+- an incident review needs incident identity plus impact/timeline and cause,
+  response, mitigation, or follow-up evidence;
+- a test/validation Section needs a checkable target, scenario, observation, or
+  acceptance result;
+- a standard/policy Section needs a stable normative rule or constraint;
+- a task or migration guide needs a reader action, verification, and relevant
+  recovery boundary;
+- an example is literal sample material, not ordinary scenario prose;
+- a comparison distinguishes at least two subjects across meaningful
+  dimensions.
+
+If the registered vocabulary cannot express the evidence, return a material or
+capability disposition. Do not use a broad narrative label merely to avoid the
+missing-intent path.
+
+## Duplicate, deletion, and recovery rules
+
+Collapse duplicate statements only when their subject, authority, reader task,
+and evidence boundary are the same. Preserve separate Sections when authority,
+lifecycle, reader task, or evidence boundary differs. Omit material only under
+the eligible reasons in `editorial-policy.md`; an answered question, actionable
+limitation, replacement-bearing deprecation, source-backed decision, or
+recovery instruction remains knowledge.
+
+On an ambiguous target, return the current unresolved/material disposition. On
+a stale workset, digest mismatch, schema mismatch, collision, or forged layout,
+stop and use the fresh Context route; do not repair the failure by changing a
+semantic label, inventing an alias, or hand-authoring a path. A destructive or
+ambiguous layout change is handled by Context's conditional human Gate. A
+non-destructive addition does not create a review pause merely because it is
+new.
+
+If the same current semantic quality problem survives three accepted revision
+attempts, keep already-passing Sections intact and request one aggregated piece
+of content-organization, source-fidelity, or missing-material guidance. Retry
+history and assessments are runtime audit data, never reader knowledge.
+
+Before returning the Result, verify that every required evidence item and
+target-resolution entry has a disposition, every Section has one current
+projection intent and evidence boundary, every claim is owned and cited, every
+duplicate/conflict decision is explicit, and no collection, path, temporary
+identity, placeholder, or unsupported claim appears in the Result.

package/indexers/bundles/context-markdown-indexer/references/structure-and-artifacts.md

@@ -0,0 +1,109 @@
+# Structure, Artifact promotion, and candidate resolution
+
+Plan reader output from source-backed Sections outward. Headings and files are
+navigation aids; the stable unit is the reader subject plus its evidence-bound
+Sections. Context owns identity derivation, schema validation, layout, paths,
+conflict detection, Review, and publication.
+
+## Section first, Artifact when justified
+
+Keep a candidate as a Section by default. A heading, table row, FAQ label,
+single warning, short example, or local subtopic is not independently a reader
+Artifact merely because it has a title.
+
+Record the semantic boundary decision in conformance reasoning as
+`retain-section-group` or `promote-reader-artifact`; these are fixture and
+guidance labels, not extra fields in `ArtifactResult`.
+
+Promote source material to a dedicated Artifact when evidence supports at least
+one of these boundaries:
+
+- it serves a distinct reader task or projection intent from adjacent material;
+- it is independently retrievable outside the surrounding page and carries
+  enough context to answer that task without the parent prose;
+- it has its own authority, lifecycle, owner, timeline, or cross-cutting scope;
+- it is a coherent, substantial unit whose inclusion would make the surrounding
+  Artifact mix unrelated reader purposes;
+- another Section in the proposed Artifact has an incompatible projection
+  intent under the current CLI profile contract.
+
+Do not promote solely because the source has many headings, a recognized label,
+or a long table. Do not create thin Artifacts to improve counts. If material has
+an independent subject rather than merely a separate reader page, use the
+workset's target-resolution choices; never invent a Node identity from a title.
+
+Within one Artifact, every Section must use that Artifact's `artifact_kind`.
+Start by grouping only Sections with the same exact
+`document_kind + reader_goal + artifact_kind` intent. Different intents may be
+combined only when the current CLI-provided contract proves they share one
+layout destination and the combined page remains one coherent reader task. If
+the contract would project them differently, return separate Artifacts; do not
+return a path or ask Context to move Sections silently.
+
+## Reading density
+
+Density is a private reading and planning strategy, not Result metadata, a
+quality score, or a separate stage.
+
+| Mode | Use when | Authoring behavior |
+| --- | --- | --- |
+| `macro` | A long source has many major headings or broad topic shifts. | Establish major reader-task boundaries first, then inspect each boundary before producing Sections. |
+| `meso` | A normal guide or record has several related sections. | Use meaningful local units and preserve precise evidence spans; this is the default. |
+| `micro` | Material is fragmented, note-like, or dense with short independent claims. | Keep evidence windows narrow and avoid bundling unrelated claims into one Section. |
+| `single-pass` | A short coherent source can be read completely within the supplied budget. | Avoid over-segmentation while still closing every evidence disposition. |
+
+Markdown headings are planning hints, not hard boundaries. Sibling headings can
+remain together when they form one coherent reader answer. Unrelated headings
+must split even if a common parent exists. Density never chooses authority,
+identity, projection intent, or pass/fail status.
+
+## Candidate resolution
+
+Treat CLI anomaly and existing-target views as constraints on a semantic
+decision, not as automatic recommendations. For each candidate, choose one
+evidence-backed outcome:
+
+- `accept-correction`: the diagnostic identifies a real ownership, grouping,
+  projection, or evidence error; return the corrected Result.
+- `dismiss-with-rationale`: the signal is mechanically true but the current
+  grouping remains semantically coherent; preserve the Result and state the
+  source-backed rationale in the supplied diagnostic surface.
+- `keep-unresolved`: evidence cannot distinguish valid alternatives; return the
+  registered material question, target-resolution, unsupported, or diagnostic
+  disposition instead of guessing.
+
+For duplicates, keep one canonical statement when evidence and reader purpose
+are the same. Preserve separate Sections only when each has a distinct
+authority, lifecycle, reader task, or evidence boundary. For conflicting facts,
+do not pick a winner from file order, heading order, recency without authority,
+or polished wording. Use source precedence supplied by the workset; otherwise
+keep the conflict unresolved.
+
+When the workset offers target-resolution entries:
+
+- reuse an existing subject only for an exact evidence-supported match;
+- create an independent subject only when the evidence supports standalone
+  identity and reader value;
+- request material when the semantic decision is possible but evidence is
+  insufficient;
+- return unsupported when the required parser or capability is absent.
+
+The CLI validates subject keys, refs, schema, digests, collision rules, stale
+state, and output layout. Do not repair those mechanical failures by changing a
+semantic label, creating an alias, or returning a hand-authored path.
+
+## Result check
+
+Before returning an `ArtifactResult`, confirm:
+
+- every actual Section has one registered projection intent and current
+  evidence;
+- mixed reader intents were evaluated Section by Section;
+- every dedicated Artifact clears an evidence-backed promotion boundary;
+- every Artifact contains only layout-compatible Sections and one Artifact
+  kind;
+- density affected only reading granularity, not authority or quality claims;
+- duplicates, conflicts, and ambiguous targets have an explicit semantic
+  disposition;
+- no collection, path, temporary batch identity, or unsupported claim appears
+  in the Result.

package/indexers/bundles/context-markdown-indexer/tests/fixtures/anonymous.json

@@ -0,0 +1,31 @@
+{
+  "protocol": "context.indexer.authoring-fixture/v1",
+  "id": "anonymous-technical-guide",
+  "anonymized": true,
+  "profile": "technical-guide",
+  "source_role": "authoritative-document",
+  "logical_unit_id": "reader-subject",
+  "logical_unit_ref": "node:anonymous-technical-guide",
+  "canonical_facts": {
+    "target": {
+      "eligible": true
+    }
+  },
+  "artifact_policy_variant": "standard",
+  "artifacts": [
+    {
+      "artifact_id": "guide",
+      "artifact_kind": "content",
+      "purpose": "required",
+      "reader_question_refs": [
+        "question:source-authority"
+      ],
+      "evidence_refs": [
+        "evidence:anonymous-guide-source"
+      ]
+    }
+  ],
+  "evidence_refs": [
+    "evidence:anonymous-guide-source"
+  ]
+}