@c4a/context 0.6.1-beta.3 → 0.6.1-beta.4

package/docs/reference/project-api.md

@@ -49,10 +49,11 @@ knowledge/codegraph/module-a/...
 knowledge/codegraph/module-b/...
 ```
 
-For prose Views, omit `containment` when the page is an independent collection
-entry. The CLI then derives `knowledge/<collection>/<slug>.md`. Set
-`containment` only when the approved structure intentionally places the page
-under a parent path; it is not a required source/module wrapper.
+For prose Views, provide a stable filename `slug` and omit `path`; the CLI
+derives the path. Omit `containment` when the page is an independent collection
+entry, producing `knowledge/<collection>/<slug>.md`. Set `containment` only
+when the approved structure intentionally places the page under a parent path;
+it is not a required source/module wrapper.
 
 The registry stores this as one date entry containing several `modules` entries,
 and materializes each module at `sources/repo/<date>/<module>`.
@@ -179,7 +180,10 @@ with the next declared command in `workflow.current.commands`.
 Each command item declares its effect and availability. The current route's
 `gate` identifies the decision and authority boundary. Write commands are bound
 to the workflow revision; after one succeeds, rerun status instead of reusing
-the old command.
+the old command. An external command also declares
+`execution.target: agent-host`; execute it as a top-level Agent-host action so
+network and credential-store access are not lost inside a restricted child
+sandbox.
 
 ### `allSources("repo")`
 
@@ -245,6 +249,10 @@ context review approve-all <collection> --managed --format json
 context review approve-all --all --managed --format json
 ```
 
+The default JSON result reports counts and change totals without listing every
+candidate id or materialized path. Add `--verbose` only when debugging requires
+the complete candidate and page details.
+
 Managed structure confirmation and Review use only the revision-bound commands
 returned by `workflow.current`. Source boundaries and unread source bodies,
 external operations, payload validation, deterministic close, and verification
@@ -374,15 +382,56 @@ context run align:file:<source-name>:architecture --view structure-summary --inp
 context run align:file:<source-name>:architecture --stage --input <structure.yaml> --format json
 ```
 
+When `workflow.current.batch` is present, several independent document slots
+can be prepared in one Agent pass and validated or staged through one command:
+
+```yaml
+schema: context.prose.structure-batch.v1
+items:
+  - phase_id: align:file:<source-a>:architecture
+    input: .tmp/agent-payloads/<source-a>-structure.yaml
+  - phase_id: align:file:<source-b>:architecture
+    input: .tmp/agent-payloads/<source-b>-structure.yaml
+```
+
+```bash
+context run --batch-input .tmp/agent-payloads/prose-structure-batch.yaml --validate --format json
+context run --batch-input .tmp/agent-payloads/prose-structure-batch.yaml --stage --managed --format json
+```
+
+Batch preflight validates every payload before writing. Stage writes ready
+slots serially; it does not merge documents or decide their semantic shape.
+
+Align results expose a recommended `payload_target.path` under
+`.tmp/agent-payloads/`. Agents should use it for transient structure inputs and
+may remove the file after a successful stage. The CLI continues to accept an
+explicit alternative path; this is an authoring convention, not validation.
+
+For the ordinary path, `read-plan` is a complete authoring packet: it includes
+the payload contract, a budgeted canonical source-ref map, exact source-body
+resources, and a direct `--stage` command. Read the bodies, author the payload,
+and run that stage command. Request `source-index` only when the packet reports
+omitted refs, and request `existing-knowledge` only when reusing or checking an
+approved identity. The separate schema and validate views are optional
+diagnostic tools, not required lifecycle steps.
+
 `--validate`, `--stage`, and `--confirm` are mutually exclusive operations. An
 `--input` without an operation is rejected unless the selected view explicitly
 consumes that input. Deterministic boundary repairs run internally before the
-result is returned. Successful validation returns a stage command with the
+result is returned. `self_healed` includes input/output Section counts, the
+number of original Sections split, and structural reason codes. Stage performs validation before writing and returns the
+same diagnostics on failure; in managed mode, a valid stage also confirms the
+structure. Successful standalone validation returns a stage command with the
 same file path. JSON run output keeps `next_action` first;
 schema and full reports stay behind explicit Views, while `--verbose` restores
 the full phase result and repeated contracts. Long diagnostics return a compact
 first page plus an exact diagnostics continuation command.
 
+Validation returns `state: ready | repair-required | invalid`. Only `ready`
+sets `valid: true` and may proceed to stage. `error_free: true` with
+`state: repair-required` means no error diagnostic remains, but a declared
+confirmation blocker still requires repair; it is not a successful result.
+
 `existing-knowledge` is the authoring-time lookup for approved identities. It
 returns stable NodeRefs, ViewRefs, titles, tags, collections, and section counts
 without exposing workspace storage paths. `--query` performs deterministic
@@ -414,7 +463,20 @@ After capture, the capture phase itself exposes collection-neutral `read-plan`,
 Status selects `route.document.classification-required` until every captured
 target has an evidence-backed, user-confirmed align declaration. Align then
 adds `schema` and `structure-summary` for structure work. Agents should not
-inspect `sources/` or `.tmp` directly.
+scan `sources/` or `.tmp` to invent evidence. They may read only the exact
+source-body files selected as required resources by the current Route; those
+files carry stable content digests and must be read in full before a receipt is
+reported. Read all required direct paths, then execute the Route's single
+`resources.after_read.command`; the CLI writes and carries the merged receipt
+set without requiring Agent-authored JSON. That acknowledgement response
+already contains the re-evaluated `workflow.current`, so no additional status
+command is needed.
+
+Generated Context Views use the same content-addressed rule. Materialization
+returns a receipt-set path and an exact post-read command. Read the complete
+file, then execute that command; unchanged content remains current across
+workflow revisions, while write and external commands still require the exact
+current revision.
 
 Compile `read-plan`, `blockers`, and `diagnostics` Views are workspace-read-only
 and may run concurrently. Compile `--validate`, compile `--stage`, structure
@@ -451,9 +513,9 @@ compile:file:<source-name>:architecture
 compile:lark:<source-name>:architecture
 ```
 
-Compile requires confirmed `unapproved/structure.yaml`. It freezes the current
-structure for the compile round; if the user wants to change nodes, section
-ownership, or relationships, return to the align/structure gate.
+Compile requires confirmed CLI-managed lifecycle structure. It freezes the
+current structure for the compile round; if the user wants to change nodes,
+section ownership, or relationships, return to the align/structure gate.
 
 Common commands:
 
@@ -537,7 +599,7 @@ package from a larger monorepo source.
 Use `context source inspect <date>/<module>` to list detected module/package
 boundaries before choosing the source. Use `context run <phase-id> --dry-run
 --format json` to check the resolved modules, file counts, symbol counts, and
-candidate estimate before writing `unapproved/entities.jsonl`. The dry-run
+candidate estimate before writing the ignored lifecycle candidate ledger. The dry-run
 preview also includes `knowledgeTree` and `knowledgePathExamples`, which show
 where approved Markdown will land after review apply.
 Its module and total summaries distinguish `discoveredFiles`, `analyzedFiles`,
@@ -619,7 +681,8 @@ structure slots and every declared `pendingStructureTargets` item in the round;
 codegraph waits for every pending extract phase in the confirmed module round.
 Candidate count/hash therefore describes the complete current batch rather than
 one page, source slot, or module. Deterministic close later merges all active
-slots into `knowledge/structure.yaml`.
+slots into `knowledge/structure.yaml`, retains only their source, collection,
+and consumed snapshot hash as `source_inputs`, then removes the lifecycle slots.
 
 `status.structureBatch` lists unclassified, configuration-required, pending,
 and active structure slots together with the execution policy for the round.

package/docs/reference/template-variables.md

@@ -91,13 +91,13 @@ Read node_modules/@c4a/context/docs/reference/template-variables.md.
 |---|---|---|
 | `packageName` | string | Package name from `kbPackage()` / `llmsPackage()`. |
 | `packageKind` | string | `kb` or `llms`. |
-| `knowledgeNamespace` | string | KB knowledge namespace; defaults to the package name and may be explicitly overridden. Empty for non-KB packages. |
-| `namespacedKnowledge` | boolean | Whether the KB package has a knowledge namespace. |
+| `knowledgeNamespace` | string | Legacy configured namespace when an older workspace still declares one; otherwise empty. It does not change output paths. |
+| `namespacedKnowledge` | boolean | Always `false`; retained so older templates remain renderable. |
 | `skillsRoot` | string | Skills root, currently `skills`. |
-| `wikisRoot` | string | Final wikis root, such as `wikis/component-lib-kb` or `wikis/platform/component-lib`. |
-| `guidesRoot` | string | Final guides root, such as `guides/component-lib-kb` or `guides/platform/component-lib`. |
-| `rulesRoot` | string | Final rules root, such as `rules/component-lib-kb` or `rules/platform/component-lib`. |
-| `featsRoot` | string | Final feats root, such as `feats/component-lib-kb` or `feats/platform/component-lib`. |
+| `wikisRoot` | string | Final wikis root: `wikis`. |
+| `guidesRoot` | string | Final guides root: `guides`. |
+| `rulesRoot` | string | Final rules root: `rules`. |
+| `featsRoot` | string | Final feats root: `feats`. |
 | `skillName` | string | Author-maintained name of the Skill currently being rendered. Empty outside a `skills/<name>/...` template. |
 | `skillPath` | string | Final package-relative `SKILL.md` path for the Skill currently being rendered. Empty outside a Skill template. |
 | `knowledgeCount` | number | Selected approved Markdown file count. |
@@ -139,7 +139,7 @@ Each item contains:
 | `internal_collection` | Alias for `internalCollection`. |
 | `collection` | Internal approved collection; alias for `internalCollection`. |
 | `okf_root` | OKF output root, for example `wikis`, `guides`, `rules`, or `feats`. |
-| `okf_root_path` | Final package-relative OKF root; for KB packages it includes the distribution namespace. |
+| `okf_root_path` | Final flat package-relative OKF root. |
 | `node_ref` | Stable NodeRef from approved frontmatter, for example `entity/button`. |
 | `view_ref` | Stable ViewRef from approved frontmatter, for example `architecture:entity/button`. |
 | `pathWithinCollection` | Path below the OKF root, for example `component-lib/symbol/button.md`. |
@@ -177,7 +177,7 @@ Each group contains:
 | `internalCollection` | Internal approved collection; alias for `collection`. |
 | `internal_collection` | Alias for `internalCollection`. |
 | `okf_root` | OKF output root for this group, for example `wikis`, `guides`, `rules`, or `feats`. |
-| `okf_root_path` | Final package-relative OKF root; for KB packages it includes the distribution namespace. |
+| `okf_root_path` | Final flat package-relative OKF root. |
 | `title` | Display title; defaults to `name`, or the OKF root title for a root group. |
 | `count` | Number of selected pages in this group. |
 | `hasIndex` | Whether the active package navigation policy generates `indexPath`. |
@@ -236,6 +236,7 @@ non-root directory gets its own index only when it contains more than 50
 descendant knowledge pages. Configure this with
 `kbPackage({ navigation: { foldDirectoryIndexes, maxInlineEntries } })`.
 
-The output is only a starter. Edit
-`src/package-templates/kb/wikis/index.md` to add project-specific reading
-paths, API entry points, or task-focused navigation before `context build`.
+The output is only a starter. Edit the files under
+`src/package-templates/kb/` when the package needs different reading paths or
+navigation before `context build`. An unchanged generated starter must instead
+be explicitly accepted through the current package-template Review Route.

package/index.d.ts

@@ -19,6 +19,7 @@ export type PackageTemplateInput = string | {
     vars?: Record<string, TemplateVarValue>;
 };
 export type PackageDistributionDefinition = {
+    /** @deprecated Accepted for older workspaces; package output roots are flat. */
     knowledgeNamespace: string;
 };
 export type BasePackageDefinition = {

package/index.js

@@ -7088,9 +7088,9 @@ var sourceSnapshotResource = (sourceDefinition, sourceType) => ({
   sourceType,
   path: `sources/${sourceType}/${getSourceName(sourceDefinition)}/manifest.json`
 });
-var unapprovedStructureResource = (collection, status) => ({
-  kind: "unapproved.structure",
-  path: "unapproved/structure.yaml",
+var lifecycleStructureResource = (collection, status) => ({
+  kind: "lifecycle.structure",
+  path: ".tmp/context-runtime/lifecycle/structure.yaml",
   profileCollection: collection,
   ...status === undefined ? {} : { status }
 });
@@ -7150,7 +7150,7 @@ var alignProse = (definition) => {
         kind: "source",
         source: definition.source
       }],
-      writes: [unapprovedStructureResource(definition.collection, "draft")],
+      writes: [lifecycleStructureResource(definition.collection, "draft")],
       source: definition.source,
       collection: definition.collection
     };
@@ -7160,7 +7160,7 @@ var alignProse = (definition) => {
     kind: "phase.align.prose",
     id: `align:${sourceType}:${sourceId}:${definition.collection}`,
     reads: [sourceSnapshotResource(definition.source, sourceType)],
-    writes: [unapprovedStructureResource(definition.collection, "draft")],
+    writes: [lifecycleStructureResource(definition.collection, "draft")],
     source: definition.source,
     sourceType,
     collection: definition.collection
@@ -7176,12 +7176,12 @@ var compileProse = (definition) => {
       reads: [{
         kind: "source",
         source: definition.source
-      }, unapprovedStructureResource(definition.collection, "confirmed")],
+      }, lifecycleStructureResource(definition.collection, "confirmed")],
       writes: [
-        unapprovedStructureResource(definition.collection, "frozen"),
+        lifecycleStructureResource(definition.collection, "frozen"),
         {
-          kind: "unapproved.entities",
-          path: "unapproved/entities.jsonl",
+          kind: "lifecycle.candidates",
+          path: ".tmp/context-runtime/lifecycle/candidates.jsonl",
           status: "draft"
         }
       ],
@@ -7196,13 +7196,13 @@ var compileProse = (definition) => {
     id: `compile:${sourceType}:${sourceId}:${definition.collection}`,
     reads: [
       sourceSnapshotResource(definition.source, sourceType),
-      unapprovedStructureResource(definition.collection, "confirmed")
+      lifecycleStructureResource(definition.collection, "confirmed")
     ],
     writes: [
-      unapprovedStructureResource(definition.collection, "frozen"),
+      lifecycleStructureResource(definition.collection, "frozen"),
       {
-        kind: "unapproved.entities",
-        path: "unapproved/entities.jsonl",
+        kind: "lifecycle.candidates",
+        path: ".tmp/context-runtime/lifecycle/candidates.jsonl",
         status: "draft"
       }
     ],
@@ -7234,8 +7234,8 @@ var extractTs = (definition) => {
       source: sourceDefinition
     }],
     writes: [{
-      kind: "unapproved.entities",
-      path: "unapproved/entities.jsonl",
+      kind: "lifecycle.candidates",
+      path: ".tmp/context-runtime/lifecycle/candidates.jsonl",
       collection: definition.collection,
       status: "draft"
     }],
@@ -7247,7 +7247,7 @@ var extractTs = (definition) => {
     exportedOnly: definition.exportedOnly ?? mode === "exports",
     out: {
       kind: "codegraph-entities",
-      candidateFile: "unapproved/entities.jsonl",
+      candidateFile: ".tmp/context-runtime/lifecycle/candidates.jsonl",
       approvedPagesDir: `knowledge/${definition.collection}`,
       initialStatus: "draft"
     }
@@ -7267,8 +7267,8 @@ var reviewValidity = (definition) => {
       kind: "phase.review.validity",
       id: "review:all:validity",
       reads: [{
-        kind: "unapproved.entities",
-        path: "unapproved/entities.jsonl",
+        kind: "lifecycle.candidates",
+        path: ".tmp/context-runtime/lifecycle/candidates.jsonl",
         status: "draft"
       }],
       writes: [
@@ -7281,8 +7281,12 @@ var reviewValidity = (definition) => {
           path: "knowledge"
         },
         {
-          kind: "unapproved.entities",
-          path: "unapproved/entities.jsonl",
+          kind: "knowledge.decisions",
+          path: "knowledge/decisions.json"
+        },
+        {
+          kind: "lifecycle.candidates",
+          path: ".tmp/context-runtime/lifecycle/candidates.jsonl",
           status: "rejected"
         }
       ],
@@ -7297,8 +7301,8 @@ var reviewValidity = (definition) => {
     kind: "phase.review.validity",
     id: `review:${definition.collection}:validity`,
     reads: [{
-      kind: "unapproved.entities",
-      path: "unapproved/entities.jsonl",
+      kind: "lifecycle.candidates",
+      path: ".tmp/context-runtime/lifecycle/candidates.jsonl",
       collection: definition.collection,
       status: "draft"
     }],
@@ -7314,8 +7318,12 @@ var reviewValidity = (definition) => {
         status: "approved"
       },
       {
-        kind: "unapproved.entities",
-        path: "unapproved/entities.jsonl",
+        kind: "knowledge.decisions",
+        path: "knowledge/decisions.json"
+      },
+      {
+        kind: "lifecycle.candidates",
+        path: ".tmp/context-runtime/lifecycle/candidates.jsonl",
         collection: definition.collection,
         status: "rejected"
       }
@@ -11772,22 +11780,8 @@ function assertUniquePhaseIds(phases) {
     firstById.set(phase.id, { index, kind: phase.kind });
   }
 }
-function assertUniquePackageKnowledgeNamespaces(packages) {
-  const firstByNamespace = new Map;
-  for (const [index, pkg] of packages.entries()) {
-    const namespace = pkg.kind === "package.kb" ? pkg.distribution?.knowledgeNamespace : undefined;
-    if (namespace === undefined)
-      continue;
-    const first = firstByNamespace.get(namespace);
-    if (first !== undefined) {
-      throw new TypeError(`Duplicate package knowledge namespace ${JSON.stringify(namespace)}: packages[${first.index}] (${first.name}) conflicts with packages[${index}] (${pkg.name}). Every distributable knowledge package namespace must be unique.`);
-    }
-    firstByNamespace.set(namespace, { index, name: pkg.name });
-  }
-}
 var defineProject = (project) => {
   assertUniquePhaseIds(project.phases);
-  assertUniquePackageKnowledgeNamespaces(project.packages);
   return {
     kind: "context.project",
     project
@@ -11926,15 +11920,12 @@ var createPackageDefinitionBase = (kind, definition) => {
 };
 var kbPackage = (definition) => {
   const base = createPackageDefinitionBase("kb", definition);
-  const distribution = normalizePackageDistribution(definition.distribution ?? { knowledgeNamespace: definition.name });
-  if (distribution === undefined) {
-    throw new TypeError("KB package distribution must resolve to a knowledge namespace.");
-  }
+  const distribution = normalizePackageDistribution(definition.distribution);
   return {
     kind: "package.kb",
     ...base,
     navigation: normalizePackageNavigation(definition.navigation),
-    distribution
+    ...distribution === undefined ? {} : { distribution }
   };
 };
 var llmsPackage = (definition) => ({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context",
-  "version": "0.6.1-beta.3",
+  "version": "0.6.1-beta.4",
   "type": "module",
   "description": "Context SDK — project-local configuration and workspace primitives",
   "license": "MIT",

package/phases.d.ts

@@ -1,4 +1,4 @@
-import { type EntityStatus, type FileCaptureProcessorDefinition, type KnowledgeCollection, type MarkdownTransform, type PackageKind, type PackageSelectDefinition, type DocumentMainlineCollection } from "./contracts.js";
+import { type FileCaptureProcessorDefinition, type KnowledgeCollection, type MarkdownTransform, type PackageKind, type PackageSelectDefinition, type DocumentMainlineCollection } from "./contracts.js";
 import { DOCUMENT_COMPILE_ACTION_SCHEMA_VERSION } from "./documentEvidence.js";
 import type { DocumentSourceDefinition, DocumentSourceType, FileSourceDefinition, FileSourceReference, LarkSourceDefinition, LarkSourceReference, RepoProjectSourceDefinition, SourceCollectionReference, SourceDefinition } from "./sources.js";
 export type PhaseResourceReference = {
@@ -10,13 +10,13 @@ export type PhaseResourceReference = {
     sourceType: DocumentSourceType;
     path: string;
 } | {
-    kind: "unapproved.entities";
+    kind: "lifecycle.candidates";
     path: string;
     collection?: KnowledgeCollection;
-    status?: EntityStatus;
+    status?: "draft" | "rejected";
 } | {
-    kind: "unapproved.structure";
-    path: "unapproved/structure.yaml";
+    kind: "lifecycle.structure";
+    path: ".tmp/context-runtime/lifecycle/structure.yaml";
     profileCollection?: DocumentMainlineCollection;
     status?: "draft" | "confirmed" | "frozen";
 } | {
@@ -28,6 +28,9 @@ export type PhaseResourceReference = {
     kind: "knowledge.approved";
     path: "knowledge";
     select?: PackageSelectDefinition;
+} | {
+    kind: "knowledge.decisions";
+    path: "knowledge/decisions.json";
 } | {
     kind: "package.template";
     path: string;

package/templates/package-templates/kb/AGENTS.md

@@ -12,21 +12,18 @@ Use the Markdown files in this package as source-linked product and code
 knowledge. Prefer cited facts from the included knowledge pages over memory.
 
 The bundled knowledge-query Skill teaches agents how to navigate OKF indexes
-and cite copied OKF root directories, starting with
-`{{wikisRoot}}/`. Customize template files before build when the package needs
-product-specific skills or routing rules.
+and cite copied OKF root directories, starting with `{{wikisRoot}}/`.
 
 Selected OKF root directories such as `{{wikisRoot}}/`, `{{guidesRoot}}/`,
-`{{rulesRoot}}/`, and `{{featsRoot}}/` follow the C4A OKF Profile: OKF fields and C4A extension fields stay
-at the top level, and no `context` or `schema` field is emitted. Root mapping:
+`{{rulesRoot}}/`, and `{{featsRoot}}/` follow an OKF-compatible Context profile:
+OKF fields and Context extension fields stay at the top level, and no `context`
+or `schema` field is emitted. Root mapping:
 `{{wikisRoot}}/` maps from structured `codegraph`, `business`, and `product` knowledge;
 `{{guidesRoot}}/` maps from `architecture`, `sop`, `faq`, `decision`, and `incident`;
 `{{rulesRoot}}/` maps from `standards` and `test`; `{{featsRoot}}/` maps from `feats`. Treat
-`{{wikisRoot}}/` as the entity-and-relationship layer; guides and rules may explain or
-constrain that layer. Customize
-the logical `wikis/index.md` template before build to describe the package scope and query guidance;
-other selected OKF root indexes are generated unless this template supplies
-them.
+`{{wikisRoot}}/` as the entity-and-relationship layer; guides and rules may
+explain or constrain that layer. Other selected OKF root indexes are generated
+unless the template supplies them.
 
 ## Included Knowledge