@c4a/context 0.6.0-beta.5 → 0.6.0-beta.7

package/docs/reference/project-api.md

@@ -19,41 +19,110 @@ declaration list. Put heavy logic in imported transform files.
 
 ## Sources
 
-A source is a stable knowledge boundary, not only a display label. By default,
-`context source add repo/file/lark` uses today's local date (`YYYYMMDD`) as the
-source name. Do not derive the name from filenames, directory names, or document
-content. If today's date already exists, pass an explicit date name. The source
-name becomes a stable identity in source references, phase ids, and package
-naming. Approved knowledge paths are derived from collection, containment, and
-slug. NodeRef/ViewRef are identity fields, not path strings:
+A source is a stable knowledge boundary, not only a display label. Repo, file,
+and Lark sources use a date batch plus a concrete module name; multiple code or
+document modules may share the date. The flattened selector `YYYYMMDD/module`
+is the source identity used by phases, snapshot paths, and source refs.
+Codegraph NodeRef/ViewRef and knowledge paths use the stable module name without
+the date:
 
 ```text
 knowledge/<collection>/<containment>/<slug>.md
-repo:<source-name>#symbol:...
-file:<source-name>/<document>#span:...
-lark:<source-name>/<document>#span:...
-capture:file:<source-name>
-align:lark:<source-name>:architecture
+knowledge/codegraph/<module>/symbol/<slug>.md
+repo:<date>/<module>#symbol:...
+file:<date>/<module>/<document>#span:...
+lark:<date>/<module>/<document>#span:...
+capture:file:<date>/<module>
+align:lark:<date>/<module>:architecture
 dist/<source-name>-kb/...
 ```
 
-Choose the boundary before extraction. In a monorepo, a source can be the whole
-repo/subspace when the user wants one unified knowledge product, or a specific
-package/subdirectory when the user wants a focused package manual. Renaming a
-source later is a source-ref, phase-id, and package-output migration. Approved
-paths are not derived directly from the source name; align/compile derives them
-from collection, containment, and slug. Long term, extraction and structure
-planning can still choose containment such as `product-ui/component-web` for
-child codegraph views:
+Choose the module boundary before extraction. In a monorepo, register each
+confirmed package/subdirectory under the same date batch. A repo root that
+resolves to multiple modules is for inspection; it is not an extraction unit.
+Approved codegraph paths use the stable module name; the date remains only in
+source selectors, phase ids, and evidence refs:
 
 ```text
-knowledge/codegraph/product-ui/component-web/...
-knowledge/codegraph/product-ui/component-lynx/...
+knowledge/codegraph/module-a/...
+knowledge/codegraph/module-b/...
+```
+
+The registry stores this as one date entry containing several `modules` entries,
+and materializes each module at `sources/repo/<date>/<module>`.
+Repo module names are project-wide codegraph identities and therefore cannot be
+reused under another date batch. Refresh an existing module through its original
+date/module selector.
+When a repo module and the Context workspace share the same Git root, the CLI
+normalizes even an absolute `--local` input into a path relative to the
+workspace and stores the package directory as `subpath`. Materialized repo
+links always use relative symlink targets. This keeps the registry and links
+valid when the whole checkout moves. Cross-repository absolute checkout roots
+remain absolute because no shared movable root can be assumed.
+The date entry must be a valid calendar date in `YYYYMMDD` form. Use
+`context source ensure <date>` or `context source inspect <date>` for the whole
+batch, and `<date>/<module>` when targeting one module.
+
+```yaml
+sources:
+  - name: "20260712"
+    modules:
+      - name: module-a
+        local: ../monorepo
+        subpath: packages/module-a
+        git:
+          remote: https://git.example.com/product/monorepo.git
+          ref: <full-commit-sha>
+      - name: module-b
+        local: ../monorepo
+        subpath: packages/module-b
+        git:
+          remote: https://git.example.com/product/monorepo.git
+          ref: <full-commit-sha>
 ```
 
-In the current repo extraction flow, treat multi-module parent sources as
-inspection/planning boundaries. Register the concrete package/subdirectory as
-the source before running extraction.
+File and Lark registries use the same outer shape. Their modules hold local
+document boundaries or remote document identities:
+
+```yaml
+sources:
+  - name: "20260712"
+    modules:
+      - name: local-manual
+        local: ../manual
+      - name: api-guide
+        local: ../api-guide
+```
+
+### Batch source registration
+
+Use one command when a user confirms several source modules together:
+
+```bash
+context source add batch [YYYYMMDD] --input <sources.yaml|json|-> --format json
+```
+
+The payload is a non-empty `sources` array. Every item requires `type`. Repo
+also requires `module` and accepts `local`/`remote`/`ref`. File requires `local`
+and accepts `include`; Lark accepts exactly one of `url`, `docToken`, or
+`wikiToken` plus optional `title`. File/Lark `module` is optional and is derived
+with the same lowercase path-safe rule as the single-source commands. Resolved
+module identities must be unique across the batch.
+
+Source mutations share a project write lock, and every registry file is
+replaced atomically. Never run separate `source add` processes in parallel. A
+batch executes items in order; if a runtime item fails, its error lists the
+completed items and the same payload may be rerun idempotently.
+
+```yaml
+sources:
+  - name: "20260712"
+    modules:
+      - name: user-manual
+        url: https://example.larksuite.com/wiki/example-a
+      - name: migration-guide
+        url: https://example.larksuite.com/wiki/example-b
+```
 
 ### `source(name)`
 
@@ -64,9 +133,49 @@ is a repo, file, or lark source:
 ```ts
 import { source } from "@c4a/context";
 
-const docs = source("20260704");
+const legacyDocs = source("product-docs");
+```
+
+### `source(namespace, module)`
+
+Reference one registered repo module. Use the date batch and module name
+returned by `context source add repo`:
+
+```ts
+const moduleA = source("20260712", "module-a");
+const moduleB = source("20260712", "module-b");
+```
+
+These references resolve to `20260712/module-a` and `20260712/module-b`;
+extraction and verification remain independent.
+
+### `source(namespace, module, { type })`
+
+Reference one file or Lark module under a date batch:
+
+```ts
+const localManual = source("20260712", "local-manual", { type: "file" });
+const userManual = source("20260712", "user-manual", { type: "lark" });
 ```
 
+These references produce module-scoped phase ids and manifest entries without
+treating the date as one document identity. Captured document files remain
+siblings under `sources/file|lark/<date>/` and share the date-level
+`manifest.json`; the logical `date/module` identity does not create another
+directory level.
+
+For a confirmed multi-document request, declare one capture phase per module.
+While any module is uncaptured, `context status --format json` reports either:
+
+- `needs-capture-phase` with `routing.configuration` when a module is not yet
+  declared in `src/index.ts`; or
+- `needs-capture` with every declared command in `routing.command_plan`.
+
+Each command-plan item says whether it is `immediate` or
+`after-human-confirmation`. The `routing.human_gate` object identifies the
+decision type and whether its result lives only in the current conversation or
+is persisted by a later workspace command.
+
 ### `allSources("repo")`
 
 Reference all repo sources as one collection:
@@ -78,7 +187,7 @@ const repoSources = allSources("repo");
 ```
 
 Use `allSources("repo")` only when the project should list every registered
-repo source. Prefer a specific `source("name")` for extraction phases.
+repo module. Prefer a specific `source("date", "module")` for extraction phases.
 
 ## Phases
 
@@ -91,6 +200,20 @@ extraction phases, review gates, close/build, and packages explicitly. The CLI
 then routes work through `context status`, `context run <phase-id>`, `context
 review html/apply`, `context close`, `context verify`, and `context build`.
 
+### Status declaration coverage
+
+`context status --format json` includes a `declarationGraph` and
+`configurationGaps` for document workflows. Each row reports capture, align,
+compile, and Review coverage for a canonical source plus collection. Gaps are
+non-blocking before structure confirmation. Once a structure is confirmed,
+compile routing is exact: phase selection uses canonical source plus collection,
+and candidate progress remains bound to the current `structure_digest`. A
+compile phase from another collection is never used as fallback.
+
+Use `context status --format json --view summary` when only the current state,
+target, counts, diagnostics, and recommended command are needed. The full view
+retains source, phase, package, and lifecycle inventories.
+
 ### `captureFile`
 
 Capture a registered file source into a committed normalized document snapshot.
@@ -127,11 +250,12 @@ Phase id:
 capture:file:<source-name>
 ```
 
-Register the source first with `context source add file --local <path>`.
+Register the source first with
+`context source add file [YYYYMMDD] --module <module> --local <path>`.
 The first registration requires `--local`; the registry may later keep `local`
-only as a refresh hint while committed snapshots remain verifiable. If the
-default date source name already exists, pass an explicit date name:
-`context source add file 20260703 --local <path>`.
+only as a refresh hint while committed snapshots remain verifiable. Multiple
+file modules may share one date. When `--module` is omitted, the CLI derives it
+from the local file or directory name.
 
 ### `captureLark`
 
@@ -148,12 +272,21 @@ Phase id:
 capture:lark:<source-name>
 ```
 
-Register the source first with `context source add lark` and exactly one
-identity flag: `--url`, `--doc-token`, or `--wiki-token`. Capture reads the
+Register each source with
+`context source add lark [YYYYMMDD] --module <module>` and exactly one identity
+flag: `--url`, `--doc-token`, or `--wiki-token`. Multiple documents may share
+one date batch; when `--module` is omitted, the CLI derives an opaque,
+credential-safe module id. Capture reads the
 remote document through the CLI runner, writes normalized snapshot files under
-`sources/lark/<source-name>/`, and does not write access credentials into the
-workspace. Multi-document Lark organization goes through `alignProse`; the
-current workflow does not provide a one-step Lark stage shortcut.
+`sources/lark/<date>/` as sibling document files tracked by one date-level `manifest.json`, and does not write access credentials into the
+workspace.
+
+Use a typed document reference in project declarations:
+
+```ts
+const handbook = source("20260712", "user-manual", { type: "lark" });
+const localDocs = source("20260712", "local-manual", { type: "file" });
+```
 
 ### `alignProse`
 
@@ -185,6 +318,30 @@ context run align:file:<source-name>:architecture --view structure-summary --inp
 context run align:file:<source-name>:architecture --stage --input <structure.yaml> --format json
 ```
 
+`--validate`, `--stage`, `--confirm`, and `--repair` are mutually exclusive
+operations. An `--input` without an operation is rejected unless the selected
+view explicitly consumes that input. Successful validation returns a stage
+command with the same file path. JSON run output keeps `next_action` first and
+omits repeated contracts outside `read-plan`/`schema`; add `--verbose` for the
+full phase reads/writes, source metadata, and contracts.
+
+Align and compile evidence results include `semantic_rules`. Its `required`
+array is the rule subset selected for the current judgment, with a selection
+reason and content digest for each rule. `handle`, `digest`, and
+`rules_version` are stable cache checks: reuse a loaded ruleset only while its
+content remains in the active context and both handle and digest still match.
+After context compaction, reload the returned required subset; a handle alone
+does not imply that the rule text is still available.
+
+Document evidence boundaries are deterministic rather than semantic.
+`source-index` and `chunks` mark Markdown AST blocks with
+`boundary_role: "markdown-ast-block"` and `section_candidate: true`.
+`span-text`/`span-detail` mark each returned page as
+`range_role: "transport-page"` and `section_candidate: false`; pagination line
+ranges are never structure boundaries. Structure validation blocks repeated
+fixed-width line grids that cut through AST blocks and reports sections that
+cross multiple heading paths, without classifying document topics.
+
 Evidence views include `read-plan`, `source-index`, `span-detail`,
 `span-text`, `schema`, and `structure-summary`. Additional diagnostic views may
 be present, but the default path is compact index first, then exact source spans.
@@ -232,6 +389,12 @@ context run compile:file:<source-name>:architecture --validate --input <compile-
 context run compile:file:<source-name>:architecture --stage --input <compile-actions.yaml> --format json
 ```
 
+Compile remains one View per write for evidence isolation. After staging, follow
+`continue_compile_batch` to prepare the next View. Only the final View returns
+the human Review action, so one confirmed structure produces one review
+payload. `context close` is blocked while a planned View is unprepared, still
+draft, or rejected without a structure revision.
+
 Compile action payloads use `schema_version: "context.compile-actions.v1"`.
 By default, actions should omit body content and let the CLI mirror cited source
 spans into `verbatim` sections. Explicit reader-visible content is not accepted
@@ -256,7 +419,7 @@ Options:
 
 | Field | Meaning |
 |---|---|
-| `source` | `source("name")` |
+| `source` | `source("date", "module")` for one repo module |
 | `collection` | Code extraction uses `"codegraph"` |
 | `include` | Optional glob list inside the selected source; default is `["src/**/*.{ts,tsx}"]` |
 | `mode` | `"exports"` (default) traces public exports from automatic or configured entries; `"scan"` uses every file matched by `include` as an entry root |
@@ -293,13 +456,13 @@ TypeScript extraction reads the selected module's `tsconfig.json` or
 tracing and internal dependency relations, so aliases such as `@/*` resolve to
 their source files.
 
-In monorepos, make the package/subdirectory the source boundary. Register the
-chosen package path with `context source add repo --local <package-dir>` and
-reference the CLI-returned date source name with `source("<source-name>")`.
+In monorepos, make each package/subdirectory a module boundary. Register the
+chosen package path with `context source add repo [YYYYMMDD] --module <module> --local <package-dir>` and
+reference it with `source("<date>", "<module>")`.
 Do not use `include` to choose a
 package from a larger monorepo source.
 
-Use `context source inspect <source-name>` to list detected module/package
+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
@@ -323,13 +486,35 @@ Codegraph extraction has two execution policies:
   result returns `next_action.human_gate=false` and the Agent continues.
 - `context run <phase-id> --auto-promote` is the explicit CI/CD path. It is valid
   only for `phase.extract.ts` codegraph phases, applies deterministic code deltas
-  without Review, then runs project verification. Verification errors make the
-  command fail; JSON output reports applied/materialized/removed counts.
+  without Review, refreshes deterministic close when approved knowledge changed,
+  then runs project verification. Close or verification errors make the command
+  fail; JSON output reports applied/materialized/removed counts plus a `close`
+  state of `refreshed`, `current`, or `not-required`. Package build remains a
+  separate pipeline step; existing package outputs are reported stale.
 
 This policy never auto-promotes architecture, business, decision, test, or
 other semantic knowledge. Agents must follow the returned
 `next_action.human_gate` instead of assuming every extraction requires Review.
 
+Approved codegraph sections use the local evidence form
+`src-N#symbol:<file>:<symbol>:<kind>@<digest>`. The file segment makes reverse
+lookup exact when multiple files contain the same symbol name, kind, and digest;
+the complete ref remains opaque to agents. New pages keep only top-level
+`candidate_fingerprint` and do not emit `code_origin`.
+
+Projects created by the beta.5 protocol can upgrade approved pages without a
+second human decision. Rerun every declared codegraph extraction phase to write
+the current file-aware symbol index, then run:
+
+```bash
+context review migrate-codegraph-refs
+context verify
+```
+
+Migration resolves each legacy ref against the trusted index and its existing
+origin metadata, removes `code_origin`, preserves the approved body and review
+state, and rolls back all page writes if final verification fails.
+
 ### `reviewValidity`
 
 Declare the review step for a collection:
@@ -353,10 +538,16 @@ review:all:validity
 
 The review HTML and apply flow are CLI-owned.
 
-This phase marks a human review gate when current candidates exist. Agents should open `context review html
-<collection> --open` or `context review html --all --open` and wait for the
-user-copied payload; they should not run the phase as an automatic approval step
-or synthesize a payload themselves.
+This phase marks a human review gate when current candidates exist. Agents
+should run `context review html <collection> --open --format json` or `context
+review html --all --open --format json`, confirm the returned `opened` field,
+and wait for the user-copied payload. They should not run the phase as an
+automatic approval step or synthesize a payload themselves.
+
+The gate is batch-scoped: prose waits for every planned View in the confirmed
+structure, and 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 or module.
 
 If the user explicitly asks for an automated or quick approval/rejection path,
 use the scoped quick commands instead of hand-writing a payload:
@@ -375,9 +566,9 @@ default human review gate.
 Use only when the typed factories cannot express a project-specific workflow:
 
 ```ts
-const sample = source("sample");
+const sample = source("20260712", "sample");
 
-customPhase("custom:sample:review", async (ctx) => {
+customPhase("custom:20260712/sample:review", async (ctx) => {
   await ctx.ensureSources({ source: sample });
   await ctx.extract.ts(extractTs({ source: sample, collection: "codegraph" }));
   await ctx.review.html(reviewValidity({ collection: "codegraph" }));