@c4a/context-cli 0.7.5 → 0.7.9

package/providers/context/schemas/indexer-main-lifecycle-output.schema.json

@@ -43,13 +43,12 @@
     },
     {
       "type": "object",
-      "required": ["protocol", "request", "result", "operation_result", "authoring_audit", "accepted_record", "graph_outcome"],
+      "required": ["protocol", "request", "result", "operation_result", "accepted_record", "graph_outcome"],
       "properties": {
         "protocol": { "const": "context.indexer.main-run-validation/v1" },
         "request": { "type": "object" },
         "result": { "type": "object" },
         "operation_result": { "type": "object" },
-        "authoring_audit": { "type": ["object", "null"] },
         "accepted_record": { "type": "object" },
         "graph_outcome": { "const": "completed" }
       },

package/providers/context/schemas/indexer-registry-bootstrap.schema.json

@@ -0,0 +1,227 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "context.indexer.registry/v1",
+  "title": "Initial Indexer registry before Provider selection",
+  "description": "The requirements-only src/indexers.yaml configuration. This is not an Action Result. The Provider selection Route supplies indexers after this file is configured. Runtime validation also checks duplicate ids, source boundaries and contract references.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "protocol",
+    "requirements",
+    "indexers"
+  ],
+  "properties": {
+    "protocol": {
+      "const": "context.indexer.registry/v1"
+    },
+    "requirements": {
+      "$ref": "#/$defs/requirements"
+    },
+    "indexers": {
+      "type": "array",
+      "maxItems": 0
+    }
+  },
+  "$defs": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9._/-]*$",
+      "description": "Slash-separated segments cannot be empty or equal to '.' or '..'."
+    },
+    "ref": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9.-]*:[A-Za-z0-9][A-Za-z0-9._~:/#-]*$"
+    },
+    "digest": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "target": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "source_ref"
+      ],
+      "properties": {
+        "source_ref": {
+          "$ref": "#/$defs/ref"
+        },
+        "module_refs": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/ref"
+          },
+          "uniqueItems": true,
+          "default": [],
+          "description": "Omit to cover the full registered source boundary. Use only known module references to narrow it."
+        }
+      }
+    },
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "targets"
+      ],
+      "properties": {
+        "targets": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/target"
+          }
+        }
+      }
+    },
+    "question": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "ref",
+        "authority",
+        "contract_version",
+        "contract_digest"
+      ],
+      "properties": {
+        "ref": {
+          "$ref": "#/$defs/ref"
+        },
+        "authority": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "kind",
+            "ref",
+            "digest"
+          ],
+          "properties": {
+            "kind": {
+              "enum": [
+                "cli-base-contract",
+                "verified-contract-overlay"
+              ]
+            },
+            "ref": {
+              "$ref": "#/$defs/ref"
+            },
+            "digest": {
+              "$ref": "#/$defs/digest"
+            }
+          }
+        },
+        "contract_version": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "contract_digest": {
+          "$ref": "#/$defs/digest"
+        }
+      }
+    },
+    "exclusion": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "scope",
+        "reason"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/id"
+        },
+        "scope": {
+          "$ref": "#/$defs/scope"
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "requirement": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "reader_goals",
+        "coverage_domains",
+        "target_scope",
+        "evidence_source_scope"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/id"
+        },
+        "reader_goals": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/id"
+          }
+        },
+        "coverage_domains": {
+          "type": "object",
+          "minProperties": 1,
+          "propertyNames": {
+            "$ref": "#/$defs/id"
+          },
+          "additionalProperties": {
+            "enum": [
+              "required",
+              "optional",
+              "out-of-scope"
+            ]
+          }
+        },
+        "target_scope": {
+          "$ref": "#/$defs/scope"
+        },
+        "evidence_source_scope": {
+          "$ref": "#/$defs/scope"
+        },
+        "questions": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/question"
+          }
+        },
+        "exclusions": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/exclusion"
+          }
+        },
+        "purpose": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Short reader and task purpose in the user language; reuse explicit goals when absent."
+        }
+      }
+    },
+    "requirements": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/requirement"
+      }
+    },
+    "requirementSet": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "protocol",
+        "requirements"
+      ],
+      "properties": {
+        "protocol": {
+          "const": "context.indexer.requirement-set/v1"
+        },
+        "requirements": {
+          "$ref": "#/$defs/requirements"
+        }
+      }
+    }
+  }
+}

package/providers/context/schemas/source-batch-input.schema.json

@@ -3,23 +3,30 @@
   "$id": "https://context4ai.dev/schemas/context-source-batch-input.v1.json",
   "title": "Context source batch input",
   "description": "One confirmed batch of repository, local document, and Lark document source boundaries.",
-  "oneOf": [
-    {
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "work_start_report",
+    "sources"
+  ],
+  "properties": {
+    "work_start_report": {
       "type": "object",
       "additionalProperties": false,
       "required": [
-        "sources"
+        "path"
       ],
       "properties": {
-        "sources": {
-          "$ref": "#/$defs/sources"
+        "path": {
+          "const": ".tmp/work-start-report.md"
         }
-      }
+      },
+      "description": "The complete report already presented at the first-task source-boundary gate."
     },
-    {
+    "sources": {
       "$ref": "#/$defs/sources"
     }
-  ],
+  },
   "$defs": {
     "module": {
       "type": "string",

package/providers/context/schemas/source-update-result.schema.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "stage",
+    "decisions",
+    "scope_summary",
+    "new_topics"
+  ],
+  "properties": {
+    "stage": {
+      "const": "source-update"
+    },
+    "scope_summary": {
+      "type": "string",
+      "minLength": 1
+    },
+    "new_topics": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "path",
+          "title",
+          "source_refs",
+          "instruction"
+        ],
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1
+          },
+          "source_refs": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "instruction": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "decisions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "path"
+        ],
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1
+          },
+          "instruction": {
+            "type": "string",
+            "minLength": 1
+          },
+          "supporting_sources": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/providers/context/skills/configure-indexer-providers/SKILL.md

@@ -9,32 +9,93 @@ metadata:
 
 # Configure Indexer Providers
 
+Before dependent bulk work, follow
+[the shared homogeneous-source review](../../resources/procedures/homogeneous-source-review.md).
+Reuse explicit group decisions; when a newly observed group needs user choice,
+present its concrete scope and pause before parsing or submitting dependent work.
+
+
 Read
-`node_modules/@c4a/context/docs/guides/indexer-provider-and-customization.md`
+the `context.indexer.provider-guide` resource at the exact path in the current Route
 for the registry-only default, Provider-layer rules, conflict handling and
 completion conditions. This Action is the entry for
 `indexer-provider-required`; when an exact distribution is unavailable, follow
 the guide's `indexer-provider-unavailable` handling instead of substituting a
 different version or cache.
 
+The current output schema defines each accepted Indexer entry. Use the guide's
+Provider selection example with the current requirements and catalog values;
+the requirements-only bootstrap schema is not this Action's result schema.
+
 The current Action input already contains the exact requirements and
 CLI-bundled catalog. Select applicable Providers using that input and the Skills
-already visible in this conversation. Do not run a separate catalog command,
+already visible in this conversation. Each bundled entry includes compact
+`capabilities` and exact `guidance.skill_path` / `guidance.manifest_path` for
+the shipped release. Read those files only for a Provider you intend to select
+when its guidance is not already available; resolve its relative references
+against that supplied bundle, not an arbitrary installed copy. Do not run a separate catalog command,
 enumerate every installed Skill, or require a discovery report/confirmation.
-For a selected shipped Provider, copy its exact version, integrity and
-cli-bundled distribution from the supplied catalog. The same Skill/version
+For a selected shipped Provider, submit `{id, role, catalog_skill}` using the
+catalog's exact skill name, plus `config` only when needed. The CLI expands the
+version, integrity and distribution from the revision-bound catalog and validates
+the complete registry. Do not supply identity overrides alongside `catalog_skill`.
+Use full identity fields for an external Provider or a deliberately pinned existing
+entry; those still follow normal resolution and authorization. The same Skill/version
 visible in the Host is a projection, not another Provider or a reason for Host
 resolution. If selecting a relevant external Skill, read only its exact
 Host-exposed frontmatter and sibling `context-indexer.yaml` needed to identify
 it; manifest version is authoritative. Do not guess missing versions, substitute
 a different version, or scan caches. Read Provider guidance only when selected.
 
+Use `existing_indexers` in the Action input as the starting point. Preserve
+unrelated entries and reuse an applicable owner before adding a binding for a
+new reader topic. An installed Provider and a workspace binding are different:
+adding a binding does not create or install a Skill. Once the user has settled
+the knowledge purpose and workspace, complete ordinary compatible bindings
+without asking the user to approve internal Indexer counts or configuration.
+Do not invoke Indexer creation when the supplied catalog already covers the
+requested interpretation. Real capability gaps still follow the Provider guide.
+
+Business skill installation and switches belong to the Host. Discover relevant
+currently visible `context-…-indexer…` skills and read their actual manifests.
+Do not override a disabled default or a selected business replacement just
+because the CLI catalog lists it. There is no second CLI enable registry.
+
+Use Note/Sessions Providers for independent reader topics from those sources;
+a session does not require code association. FAQ, guide and decision are reader
+forms, not source types. Existing Code/Markdown pages retain one primary and
+receive supporting sources in their evidence/read scope. If specialized source
+interpretation is needed, explicitly select a compatible extension layer with
+`kind: extension`; `supporting` profiles are only from the same primary layer.
+The primary writes one final page, without duplicate session/note targets.
+
 When the Graph enters through `markdown-provider`, first require the completed
 capture report. Treat only the report's exact `source_inputs` as
 current evidence. Do not infer semantic ownership from filenames, titles, or
 headings, and do not persist the discovery list. Capture proves byte/currentness
 only; the selected Markdown Provider remains responsible for semantic indexing.
 
+Choose skills to cover the useful regions agreed with the user, not every
+capability a Provider advertises or every file in a registered source. Distinguish
+regions that need knowledge pages from materials only needed to support them;
+available material does not automatically require a separate skill or page.
+If representative reading exposes a substantial unresolved scope tradeoff,
+clarify it through the existing requirement workflow before dependent selection.
+This selection Result must not silently change requirements or expand read scope.
+
+Once purpose and scope are settled and the applicable Provider capabilities are
+known, use `procedure.work-start-report` and `template.work-start-report` from the
+current Route when the work warrants a report. This is the last planning handoff
+before Partition: write or update `.tmp/work-start-report.md` with the Host file
+tool. Explain discovered Indexer choices and non-selections using the supplied
+catalog, visible relevant Skills and this task's materials; label unapplied choices
+as proposals. Reuse the first report's confirmed purpose, scope and authority;
+updating it with compatible Provider choices does not require another pause.
+Ask again only for a material unresolved user decision or a current authorization
+Gate; do not bypass the initial report handoff if it has not happened.
+A useful report already formed during requirement setup should be reused; do not
+restart discussion or add report fields to the selection Result.
+
 Return only the compact current-Action result:
 
 ```yaml
@@ -49,12 +110,16 @@ visible to the Host; leave it empty for a CLI-bundled selection without external
 observations. It is not an inventory of installed Skills. `indexers` contains
 the semantic registry entries selected for the
 unchanged requirements in the Action input. Select portable distribution
-locators and exact versions and integrities. Each required
+locators and exact versions and integrities for full identity entries; use
+`catalog_skill` for an explicit bundled catalog choice. Each required
 requirement/domain/source/module owner cell needs one primary Indexer;
 overlapping read scope is allowed for enrichers. One Indexer may combine a
 primary layer, supporting profiles, extension layers, and composers, but
 Provider array order is not precedence.
 
+Keep catalog capabilities and guidance paths out of the submitted entries;
+they are selection help, not registry fields.
+
 Choose the applicable CLI-bundled community profile directly when no visible
 specialized Provider is required. The CLI constructs the full route input,
 performs fallback/conflict checks, validates the proposal, resolves and stages

package/providers/context/skills/configure-indexer-providers/references/guides/code-indexer-skill-authoring.md

@@ -0,0 +1,180 @@
+# Code Indexer Skill authoring
+
+This guide defines the release checklist for a Code Indexer Provider Skill.
+It does not reproduce Context's internal Agent Graph lifecycle. The Provider
+receives validated requirements, scopes, worksets and evidence views and
+returns only its declared structured Results/fragments.
+
+## Minimal package
+
+Use one `context-indexer.yaml` with protocol
+`context.indexer.provider/v1`. Give the Skill a SemVer version and publish the
+complete Bundle with a reproducible integrity digest. Instructions, templates,
+fixtures and portable program entries live below the Skill root. Do not invent
+source-specific manifest names or a second schema tree.
+
+Programs use a structured `runtime: node`, portable `entry` and literal `args`.
+They never use a free-form command. A detector only reports activation signals;
+an inspector only returns bounded evidence/enrichment. Neither is a hard-gate
+authority. CLI profile contracts and verified data-only overlays own mechanical
+rules, metric operators and thresholds.
+
+## Author contract checklist
+
+For generated API tables, test the final Candidate as well as the parser payload
+and template preview. Cover direct and supporting references, partial contracts,
+shared types with different implementation defaults, ambiguous or cross-file
+links, and an approved-page regeneration after the source changes. Keep a known
+field when only part of its implementation can be extracted. Do not equate an
+accepted result with a corrected page.
+
+Document what each supported language adapter actually establishes. Preserve
+written expressions without evaluating arbitrary code, distinguish declaration
+defaults from implementation defaults, and explain unresolved imports or types.
+Unknown material, an unsupported parse, and a renderer contradicting a known fact
+need different responses. Use existing material requests and repair routes;
+neither a new content-quality gate nor a Provider-specific retry ledger is needed.
+
+1. **Responsibility.** Classify supported code modules and produce evidence-
+   bound partitions, logical units, Artifact Bundles and Results. Do not own
+   source authorization, requirement approval, final review, CLI metrics or
+   package publication. Source-specific Note/Sessions layers may contribute
+   declared guidance to a code page; they do not become another primary or
+   turn a conversation's proposed change into implemented code behavior.
+2. **Manifest.** Use the sole `context-indexer.yaml` field tree. Bind domains,
+   profiles, operations/fragments, resources, source roles, logical units,
+   customization support and composition without duplicate aliases.
+3. **Resource composition.** Combine only declared programs, profile-bound
+   instructions, templates and optional detector/inspector resources. Omitted
+   capabilities remain unsupported; natural language cannot add them.
+   Put any Agent-executed grouping rules in those declared instructions or
+   templates so Context delivers them with the current View. A partition
+   strategy id or digest is not an instruction resource. Context selects and
+   records strategy attempts; the Agent returns semantic groups and dispositions,
+   without discovering strategy implementations or managing fallback order.
+4. **Activation and profiles.** Declare strong/supporting/negative signals.
+   Dependency names are candidates, not runtime proof. One module may combine
+   one primary profile with supporting/extensions and selected composers.
+5. **Sources and Artifacts.** Write for a reader outside the indexed module:
+   make responsibility, stable interfaces/entrypoints, handoffs and the core
+   state, failure, operation and source-of-truth facts needed for correct use
+   and attribution discoverable. Declare source roles and logical-unit intent;
+   select only CLI-registered Artifact kinds/policy variants. Keep logical unit
+   identity separate from physical Artifact count, and measure useful coverage
+   by answered profile questions rather than symbol or path counts.
+6. **Inventory protocols.** Close every input member with an explicit
+   disposition. Use stable aggregation, full-path example identity and
+   structured chain decisions; do not substitute page prose for inventory.
+7. **Metrics.** Reference registered metric ids as reader-quality guidance.
+   The CLI may report advisory observations, but a Provider cannot return a
+   pass, threshold, retry count, or risk-acceptance decision.
+8. **Revision boundary.** Hard contract or source failures block at their
+   owner. Reader-quality feedback reopens the same Author or Composer through
+   `context revise`; it does not create a metric retry ledger or risk Gate.
+9. **Reader questions.** Declare reusable question templates with stable refs,
+   target domains and allowed evidence contracts. Do not make a question id
+   globally unique to one SubjectKey group.
+10. **Inspector safety.** Accept only the versioned stdin request and bounded
+    authorized evidence view; emit strict JSON within limits. Never read the
+    repository, environment or network implicitly, and never expose raw
+    config values, secrets or unbounded stderr/stdout.
+11. **Base gates.** Do not reduce source scope integrity, identity, evidence,
+    requirement, disposition, reference-only or provenance gates. Provider
+    integrity identifies content; it does not grant pass authority.
+12. **Anonymous fixtures.** Cover at least a component library, Web app, API
+    service, SDK/library and runtime/worker with neutral paths and identifiers.
+13. **Release tests.** Validate the manifest/resource ledger, run positive and
+    negative fixtures, forward-test the complete Skill, pack it, reinstall the
+    exact artifact and compare Bundle bytes/digest.
+14. **Content ownership.** Public technology belongs in the community Skill;
+    company-wide infrastructure belongs in a separate namespaced Provider;
+    repository, service, team and business mappings belong in business/project
+    Providers. Community fixtures remain anonymous.
+15. **Marketplace layout.** Archives keep one top-level Skill directory with
+    `SKILL.md`, the manifest and referenced runtime resources. Exclude tests,
+    caches, credentials, local paths and Host-specific temporary manifests.
+16. **Material gaps.** Return a canonical question disposition in the same
+    main Result when required evidence is missing. Never render a gap as an
+    empty page or speculative prose. Registered Markdown or tool material may
+    enrich the same main indexing batch before Candidate generation; do not
+    create a separate answer operation, Candidate, checkpoint or Review. The
+    CLI projects allowed enrichment material into that same Authorized
+    Workset View; Providers must not reopen registered sources themselves.
+17. **Backend profiles.** Test neutral RPC/HTTP, Gateway, Event/function,
+    Cron/worker, sync/reconciliation, stateful service/storage and library
+    shapes. Local facts remain baseline when optional remote metadata is absent.
+18. **Versioning.** Use Skill/Provider SemVer, exact Provider pins and Bundle
+    integrity. Fixed dependencies require exact versions and resolved
+    integrity. `@context-indexer-origin` is required on workspace-local customization
+    files and grants no authority. It is not required on Provider bundle files.
+19. **Trust boundary.** Skill/manifest describes capabilities; the verified
+    Bundle supplies bytes; workspace customization supplies project deltas;
+    CLI contracts supply hard rules. Keep these four authorities distinct.
+20. **Requirement direction.** `IndexRequirementSet` constrains registry,
+    extractor and Result in one direction. Apply requirement/registry changes
+    through staged, digest-bound proposals and transactional apply; do not edit
+    a live registry around the Route.
+21. **Program and remote authority.** Programs must pass static policy and the
+    applicable trusted/sandbox authorization. Optional remote tools use a
+    versioned Host Action, exact source-bound request and readable receipt;
+    they never expand scope or perform writes.
+22. **End-to-end recovery.** Test discovery, exact Provider resolution,
+    content-addressed staging, controlled execution, Artifact/Evidence Result
+    validation and crash recovery. A resumed run reuses only complete accepted
+    records and never infers success from a partial receipt.
+23. **Customization ladder.** Preserve this order: Provider only → config →
+    instructions append → one template override → program extension →
+    restricted replace. Document the proof and exit condition at every step;
+    see [Provider selection and customization](./indexer-provider-and-customization.md).
+24. **Batch neutrality.** Write instructions for one semantic task and accept
+    that Context may transport several independent tasks in one Agent step.
+    Never derive identity, ordering, ownership or evidence scope from a task
+    key or batch position. Partition should decide consumer-facing ownership
+    from public anchors and unresolved material; detailed supporting Facts are
+    consumed in the bounded Author View rather than copied into every
+    Partition decision.
+
+The current Route delivers readable task material with goals and constraints
+first, followed by the authorized sources and facts. For behavioral explanations,
+read the complete source excerpts. Copy the displayed `source_items` into the
+section's `source_items`; use Fact references in `facts`, not as source items.
+Context resolves a text item's authorized source spans internally. Inventory
+identities and a repository reference do not identify section source material.
+These process-local excerpts are not new Facts or reader-page metadata. Do not
+reopen the repository or infer behavior from a locator alone when the supplied
+lines do not establish it. Batch size does not define a knowledge page boundary.
+
+Author task resources may point to one shared batch reading file. Read that path
+once, use shared material only for its listed task keys, and consider each task's
+own goals and source excerpts. Context shares identical material, not conclusions:
+prepare a separate result for each task and submit the `results[]` together through
+the current completion command. A retry includes the remaining tasks' material in
+full; no earlier batch file or additional reading command is required.
+
+## Result and composition rules
+
+Exactly one primary layer returns a complete partition/author Result for an
+operation. Pre-author extensions return only declared fragments and cannot
+change ownership, denominator or Subject identity. Post-author composers bind
+one current `PrimaryResultView` and return only a derived proposal fragment;
+an empty composer run still has a receipt. Composer selection is the
+intersection of registry selection, manifest declaration and current profile
+applicability, not array order.
+
+Use canonical SubjectKey schemas and the Context NodeRef formula. All selected
+Providers must reuse the same Node when the SubjectKey is equal. An
+enricher uses the supplied TargetResolutionView (`resolved`, `absent` or
+`ambiguous`) and never guesses identity from a title or path resemblance.
+
+Every Section uses the exact `document_kind`, `reader_goal` and
+`artifact_kind` tuple from the current profile's unique layout mapping. The
+Provider never returns a collection name; Context resolves the collection from
+that tuple and rejects missing or ambiguous mappings.
+
+## Publication gate
+
+Do not publish until the exact packed artifact passes manifest/schema
+validation, anonymous positive/negative fixtures, no-scope-expansion and
+secret-leak tests, deterministic Bundle reconstruction, exact-version install,
+controlled execution and forward tests. Publishing a new version does not make
+existing workspace pins current; workspace selection must re-resolve it.