@c4a/context-cli 0.7.9 → 0.7.10-alpha.2

package/plugins/skills/context-markdown-indexer/references/semantic-planning.md

@@ -1,176 +1,48 @@
-# Source, subject, and claim planning
-
-Use these rules while producing the current `main-index` `ArtifactResult`.
-Captured Markdown is ordinary source material: it may create or enrich the same
-knowledge candidates as code-derived input. If required material is still
-missing, return a material-gap disposition and let a later main-index run consume
-the newly captured source. Do not create an answer-only result, landing, or
-second review workflow. Context remains the authority for schemas, SubjectKey
-normalization, identities, paths, collisions, stale state, layout changes,
-Review, and publication.
-
-## Reader-subject grouping
-
-The rules below are the grouping guidance for the current document View.
-Context handles strategy selection, ordering, retry, and catalog fallback;
-do not retrieve a separate strategy definition or submit strategy metadata.
-
-For a partition workset, group captured document members by durable reader
-subject rather than by file, heading, route, or temporary capture batch. Use
-the complete authorized document text together with maintained title,
-`source_path`, route, audience, and reader-task evidence. These fields are
-evidence for the decision; none is sufficient by itself.
-
-Choose readable, durable subject names during Partition. Context's main-page
-path uses the subject namespace as the directory and local key as the basename;
-the group's key and authored title do not rename it. When the default namespace
-is a capture ID or opaque source token, use the existing explicit subject object
-with a source-supported product/platform namespace and topic key, such as
-`sample-web` / `faq`, under a permitted kind. Do not repeat the source token in
-both path segments or use random/hash suffixes to resolve collisions. Keep an
-existing subject and its approved path on updates; a title edit alone does not
-create a new identity. Review the proposed subject and final reader path, not
-only the page title. Context handles path normalization and layout confirmation.
-
-One group may contain multiple documents when they jointly explain the same
-reader subject. Split platform or runtime variants only when their supported
-contract, behavior, lifecycle, or reader task is materially different. Keep
-navigation-only indexes, generated duplicates, empty placeholders, and
-superseded pages out of authored groups with an explicit inventory
-disposition. Every current inventory member must still receive exactly one
-partition disposition. If durable subject boundaries cannot be established,
-return a failed Partition Result explaining the missing boundary evidence so
-Context can choose the next attempt. Do not silently substitute one group per file.
-
-## 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, authorized source views, 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
-
-For Author, 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;
-- `unresolved` with a `reason_code` when the supplied material cannot establish
-  identity or the required capability is unavailable. `request-material` and
-  `unsupported` are whole-Result outcomes, not target-resolution dispositions.
-
-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.
+# Source and article planning
+
+The CLI supplies mechanical navigation: titles, a bounded opening excerpt,
+heading hierarchy and existing article titles, descriptions and references.
+Start there, then optionally read the full authorized material wherever the
+reader question, grouping or authority is unclear. Do not require every source
+to be fully read before any plan can be submitted.
+
+## Topics and batches
+
+Consider code-related topics already discovered, then document topics. Reuse
+an existing article when it answers the same question for the same audience.
+Document business definitions may correct a mechanical code-topic name; explain
+the proposed change in the plan instead of forcing the document into a path
+mirror. This does not authorize renaming formal files outside the current task.
+
+A coherent document can directly suggest one target. A long document may need
+several articles; several documents may jointly answer one question. Neither
+file count nor heading count determines article count. Choose batches based
+on reader tasks, dependencies and useful shared reading, not source or skill
+identity. Do not create per-member dispositions or a separate semantic graph.
+
+Submit article targets, questions, authorized sources and batches through the
+current planning schema. Keep remaining investigation in pending_scopes when
+only part is ready. An unread source is unfinished, not implicitly excluded.
+Missing essential evidence remains a scoped gap. Long-term exclusions need
+the applicable user authorization.
+
+The first executable plan is presented in the work-start report and waits for
+feedback before bulk writing. Within the confirmed purpose and scope, later
+investigation can append tasks or explicitly replace unfinished tasks through
+the current plan-amendment action. Accepted content requires a revision task,
+not replacement of the successful submission. No separate completion receipt
+or mandatory planning pass per article is needed.
+
+## Authority and updates
+
+Titles, age, archive locations and polished language do not prove authority or
+irrelevance. Compare substantive content, intended audience and applicability.
+Historical decisions or procedures may still answer the reader's question.
+Ask about a missing decision when including or excluding it materially changes
+the agreed scope; do not ask again when the purpose is already established.
+
+Read the current article when proposing a substantive revision. Preserve useful
+steps, examples, images and limitations. A source change is a reason to
+reconsider affected content, not to rewrite every article. Follow current CLI
+recovery on a changed source, stale input or identity collision; never invent
+an alias or restore an old workflow from formal storage.

package/plugins/skills/context-markdown-indexer/references/structure-and-artifacts.md

@@ -1,115 +1,33 @@
-# 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.
-
-Do not collapse a substantial captured document into a page that only lists its
-headings or says the source should be consulted. Preserve supported procedures,
-API tables, examples, constraints, compatibility notes, and decisions inside
-the selected reader Artifact; remove only navigation chrome, conversion noise,
-duplicates, and content with an explicit omission disposition.
-
-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.
+# Article and section boundaries
+
+Use stable articles and sections, not graph subjects or Artifact promotion
+records. A heading, warning, short example or table row does not automatically
+justify an independent article. Keep a contribution in its existing article
+when it serves the same reader question.
+
+Create a separate article when a distinct reader task has enough supported
+context to stand alone, or when combining incompatible audiences, versions or
+procedures would confuse the reader. Several authorized sources may contribute
+to the same article. Group by meaning, not transport batches or folder names.
+
+For a large document, inspect major topic boundaries first; for a coherent
+short document, a single reading may be enough. Narrow citation windows remain
+necessary in either case. This is a private reading strategy, not a recorded
+density mode or a mandatory ledger.
+
+Preserve useful procedures, interface tables, examples, conditions, images and
+decisions. Do not replace a substantial source with a heading inventory or a
+sentence sending readers elsewhere. Remove repetition and conversion residue
+only without losing useful meaning. Page count and production cost are not
+reasons to discard required knowledge.
+
+Compare meaning, applicability and authority before merging duplicates.
+Conflicting accounts may describe different dates, environments or intentions.
+Keep the distinction explicit or request essential evidence; file order and
+polished wording do not choose the winner.
+
+When revising, preserve article identity and unaffected section identities.
+Use the task's base Markdown and reference table, and the current edits schema
+for replacements, splits, merges or deletions of sections. A new article plan
+does not authorize direct edits to formal files or silently dropping accepted
+content. CLI handles conflicts, real source checks and safe writes.

package/plugins/skills/context-markdown-indexer/tests/fixtures/anonymous.json

@@ -19,13 +19,7 @@
       "purpose": "required",
       "reader_question_refs": [
         "question:reader-structure"
-      ],
-      "evidence_refs": [
-        "evidence:anonymous-guide-source"
       ]
     }
-  ],
-  "evidence_refs": [
-    "evidence:anonymous-guide-source"
   ]
 }