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

package/docs/guides/agent-guide.md

@@ -46,7 +46,7 @@ node_modules/@c4a/context/docs/reference/package-templates.md
 - `unapproved/entities.jsonl` is the committed draft/rejected/deprecated ledger.
 - `knowledge/` contains approved Markdown.
 - `dist/` contains generated package outputs.
-- file and Lark snapshots live under `sources/file/<source-name>/` and `sources/lark/<source-name>/`.
+- file and Lark documents from one date live as sibling files under `sources/file/<date>/` and `sources/lark/<date>/`; each date directory has one shared `manifest.json`.
 - `.tmp/context-runtime/` contains ignored runtime cache, logs, review HTML, previews, and locks.
 
 Do not create hidden workspace state directories.
@@ -58,7 +58,7 @@ Present only the current workflow surface:
 | Task | Current route |
 |---|---|
 | Register a knowledge boundary | `context source add file/lark/repo ...`, followed by the matching project phase declaration. Source registration is a user-confirmed boundary decision. |
-| Capture document sources | Run the declared `capture:file:<source>` or `capture:lark:<source>` phase only after read permission. Capture writes committed snapshots under `sources/file/<source-name>/` or `sources/lark/<source-name>/`. |
+| Capture document sources | Run the declared `capture:file:<date>/<module>` or `capture:lark:<date>/<module>` phase only after read permission. Capture writes a sibling document file under the matching date directory and updates that directory's single `manifest.json`. |
 | Investigate captured material | Use `context status` and the returned `context run align:<type>:<source>:<collection> --view ...` commands. Evidence views drive reading; raw directory grep is not the workflow. |
 | Confirm prose structure | `alignProse` validates and stages `unapproved/structure.yaml`. Validation does not equal user confirmation; only confirmed lifecycle state may enter prose compile. |
 | Compile source-bound drafts | `compileProse` turns confirmed structure into source-bound draft pages. It does not approve knowledge. |
@@ -80,16 +80,14 @@ user first.
 
 `missing-source` is a human gate. In user-facing language, describe the next
 action as adding a knowledge source, not as filling CLI placeholders. Treat this
-as a source boundary decision. Explain that the CLI uses today's local date
-(`YYYYMMDD`) as the source name by default; do not invent a name from cwd,
-parent directories, monorepo layout, package names, git remotes, filenames, or
-document content. The source name appears in source refs and phase ids. Approved
-paths are derived from collection, containment, and slug. NodeRef/ViewRef are
-identity fields, not path strings:
+as a source boundary decision. Document sources use today's local date as their
+name. Repo sources use the date as a batch and require the confirmed module
+identity. Do not invent semantic date suffixes. The concrete repo selector
+appears in source refs, phase ids, and codegraph paths:
 
 ```text
 knowledge/<collection>/<containment>/<slug>.md
-repo:<source-name>#symbol:...
+repo:<date>/<module>#symbol:...
 file:<source-name>/<document>#span:...
 lark:<source-name>/<document>#span:...
 capture:file:<source-name>
@@ -97,50 +95,102 @@ align:lark:<source-name>:architecture
 dist/<source-name>-kb/
 ```
 
-Approved paths are not derived directly from the source name. Align/compile
-derive them from collection, containment, and slug; extraction and structure
-planning may choose containment that reflects package/module shape when the
-source boundary intentionally covers multiple modules.
+Prose align/compile paths derive from collection, containment, and slug.
+Codegraph paths use the registered date/module grouping before the symbol slug.
 
 Ask what the user wants the source to cover: a single local Markdown/MDX document,
 a local Markdown/MDX directory, an article/documentation repository as a file
-source, a Lark/Feishu document URL or token, a local code repo/package, a remote
-Git repo/package, or a multi-module namespace. If today's date source name
-already exists, ask for an explicit date name; do not auto-append a sequence.
-Approved paths still come from collection, containment, and slug.
+source, a Lark/Feishu document URL or token, a local code repo/package, or a
+remote Git repo/package. Repo sources use today's date as one batch and a
+confirmed `--module` identity; do not create date suffixes for separate
+packages. The CLI rejects non-date or impossible repo batch names. Use
+`context source ensure <date>` / `context source inspect <date>` to operate on
+all registered modules in one batch, or `<date>/<module>` for one module.
+If the user supplies several repo/file/Lark sources in one request, create one
+`context source add batch <date> --input <payload> --format json` payload and
+register them under a single project write lock. Never parallelize mutating
+`source add` commands; on a lock-held error, wait and retry.
 
 Current execution supports repo sources, local Markdown/MDX file sources, and Lark /
 Feishu document sources. Local
-repo/package sources are registered with `context source add repo --local <path>`;
-the materialized `sources/repo/<source-name>` entry is an ignored
-symlink to the selected checkout or subdirectory view. Local Markdown/MDX sources
-are registered with `context source add file --local <path>` plus any
+repo/package sources are registered with `context source add repo [YYYYMMDD] --module <module> --local <path>`;
+the materialized `sources/repo/<date>/<module>` entry is an ignored
+relative symlink to the selected checkout or subdirectory view. If the source
+and Context workspace share a Git root, absolute input is normalized to a
+workspace-relative repo root plus `subpath`; do not rewrite it back to an
+absolute machine path. Local Markdown/MDX sources
+are registered with `context source add file [YYYYMMDD] --module <module> --local <path>` plus any
 needed `--include` patterns, captured with `captureFile`, then planned through
 `alignProse` and compiled with
 `compileProse`. A one-file-to-one-page outcome is a degenerate structure plan,
 not a separate content path. Remote Git operations require explicit user approval before any
 clone/checkout; clone into an ignored local path, checkout the requested commit,
 then register that local checkout. Do not commit cloned source content. Lark /
-Feishu sources are registered as document sources, captured through the Lark
-capture phase, and written as committed snapshots under `sources/lark/<source-name>/`;
+Feishu sources are registered as document modules under a shared date batch,
+captured through the Lark capture phase, and written as committed snapshots
+as a sibling file under `sources/lark/<date>/`, tracked by the date-level `manifest.json`;
 do not fetch or import Lark content with ad hoc scripts.
+If the user requests multiple documents together, register and declare all of
+them before capture. The user's explicit batch request supplies one read scope
+and one mainline collection choice. Follow `routing.command_plan`: run
+`immediate` items directly and run `after-human-confirmation` items only after
+the current conversation contains that confirmation. Do not ask for another
+date name or repeat the collection gate per document.
+
+## Current-step protocol
+
+Treat `context status --format json` `routing` as the complete protocol for the
+current step:
+
+- `human_gate.required` says whether user input is required;
+- `human_gate.kind` says which product decision is being made;
+- `human_gate.confirmation` and `persistence` distinguish conversation-only
+  permission from decisions persisted by a workspace command;
+- `configuration` identifies the exact project file and declaration action when
+  no CLI command is valid yet;
+- `commands_available` reports whether a command plan exists; and
+- `command_plan[].availability` says whether each command runs immediately or
+  only after user confirmation.
+
+Status also returns `declarationGraph` and `configurationGaps`. These expose
+capture, align, compile, and Review coverage for each canonical document source
+and declared align collection. Missing declarations are early warnings while
+structure is still being planned; after confirmation, every collection planned
+by the structure must have an exact compile route for the same source. Do not
+run a compile command from another collection as a fallback. A
+`reviewValidity({ scope: "all" })` declaration covers every collection.
+
+Do not infer permission from the presence of a command. Do not infer a command
+from prose when `commands_available=false`; complete the returned configuration
+action and rerun status instead.
 
 Extraction scope is also a human gate. If no extract phase is declared, explain
 what code area and symbol policy will become draft knowledge, then ask which
 registered source and file/symbol range to ingest. Do not inspect the source
-repository to choose packages or globs on the user's behalf.
-
-For monorepos, one source may conceptually cover the whole repo/subspace or one
-package/subdirectory. Explain that the date source name becomes a source-ref and
-phase-id namespace. A parent date source name can support grouped codegraph NodeRefs
-such as `knowledge/codegraph/product-ui/component-web/...` and
-`knowledge/codegraph/product-ui/component-lynx/...`. In the current executable
-flow, use the whole repo/subspace only for inspection/planning. If the user wants
-a focused package manual and chooses `packages/button`, register that
-subdirectory as its own source and write
-`extractTs({ source: source("button"), ... })`. Do not use
+repository to choose packages or globs on the user's behalf. Status reports
+`needs-extract-phase` with `routing.configuration` until that confirmed scope is
+declared; only a declared phase can advance to `ready-to-extract` and return an
+executable preview or extraction command.
+
+For a fresh mixed-source workspace, capture every confirmed file/Lark source
+first. If repo code is still unprocessed and document structure has not started,
+`context status` prioritizes `ready-to-extract` over document investigation.
+Complete the code extraction and its batch Review before starting prose align.
+Once a document structure draft exists, keep that current human gate and do not
+switch workflows mid-review.
+
+For monorepos, the date is one registration batch and every selected package is
+a module under it. Stable codegraph paths omit that batch date and therefore
+look like `knowledge/codegraph/module-a/...` and
+`knowledge/codegraph/module-b/...`. Date/module remains in phase ids and
+repo source refs. Use the whole repo/subspace
+only for inspection when it contains multiple modules. If the user chooses
+`packages/button`, register it with `--module button` under the same date and
+write `extractTs({ source: source("20260712", "button"), ... })`. Do not use
 `include: ["packages/button/src/**"]` to choose a package from a larger source;
-`include` only filters files inside the selected source.
+`include` only filters files inside the selected source. Repo module names are
+project-wide codegraph identities; refresh an existing module through its
+original date/module selector instead of reusing its name under a later date.
 
 For a non-standard package, configure source-relative `entries` on `extractTs`;
 every entry must match `include`. If the user wants all declarations in the
@@ -150,7 +200,7 @@ file or package manifest field to the source repository solely to make Context
 run.
 
 Follow the source inspection pattern when scope is unclear: run
-`context source inspect <source-name> --format json`, show the candidate package
+`context source inspect <date>/<module> --format json`, show the candidate package
 paths from that CLI output, wait for the user to choose the package path(s), then
 declare sources/phases. If the extraction preview reports modules outside the
 confirmed source boundary, stop before review and repair the source declaration.
@@ -158,7 +208,7 @@ confirmed source boundary, stop before review and repair the source declaration.
 Before running extraction, prefer:
 
 ```bash
-context source inspect <source-name> --format json
+context source inspect <date>/<module> --format json
 context run <extract-phase-id> --dry-run --format json
 ```
 
@@ -166,13 +216,26 @@ After the preview, run codegraph extraction normally unless the user explicitly
 asked for CI/CD automation. The first normal run requires Review for all code
 candidates. Subsequent normal runs require Review only for added, changed, or
 removed symbols; unchanged approved symbols stay approved. Always inspect
-`next_action.human_gate`: open Review only when it is `true`, and continue when
-it is `false`.
+`next_action.human_gate`: `continue-codegraph-batch` means run status and finish
+the remaining confirmed module phases. Open one Review only after
+`pendingExtractPhases` is empty and the returned gate is `true`.
 
 For a non-interactive pipeline, use `context run <extract-phase-id>
 --auto-promote --format json`. This flag applies only to codegraph, applies its
-deterministic deltas, runs verify, and fails the command if verify fails. Never
-use it for semantic knowledge collections.
+deterministic deltas, refreshes deterministic close when needed, runs verify,
+and fails the command if close or verify fails. Read `autoPromotion.close` and
+`autoPromotion.verify` before continuing. Package build remains explicit: when
+the pipeline publishes packages, run `context build` after successful auto
+promotion. Never use auto promotion for semantic knowledge collections.
+
+If verify reports `approved-source-ref-ambiguous` on approved codegraph pages
+created by beta.5, do not send those pages back through Review and do not filter
+approved symbols away. Rerun the declared codegraph extraction phase to refresh
+the trusted file-aware symbol index, then run `context review
+migrate-codegraph-refs` and `context verify`. Tell the user that this preserves
+their decisions and approved content while upgrading evidence metadata. If the
+reported ref already contains `<file>:<symbol>:<kind>`, treat it as a duplicate
+symbol-index defect instead of a legacy migration.
 
 Use the preview `mode`, optional `entries`, `preview.sources[].modules[]`,
 `candidateEstimate`, and `agent_hints`
@@ -185,26 +248,25 @@ Treat `NO_ENTRY_DETECTED` as a configuration failure: choose explicit
 never report an empty extraction as success. Report discovered, AST-analyzed,
 skipped, symbol, and relation counts separately. The extractor follows
 tsconfig/jsconfig `baseUrl` and `paths`, so do not ask users to rewrite `@/`
-imports solely for Context. Explain that approved pages will be written under
-paths derived from collection, containment, and slug:
+imports solely for Context. Explain the concrete output shape:
 
 ```text
-knowledge/<collection>/<containment>/<slug>.md
+knowledge/codegraph/<module>/symbol/<slug>.md
 ```
 
-If the source name, optional module segment, or resulting path shape looks
-wrong, stop and ask whether to rename the source or change the source boundary
-before running extraction. A source that already points at one package/module
-root should not repeat the package name in the path. A source rename after
-extraction is a migration, not a cosmetic change. Do not write ad hoc scripts to
+If the module or resulting path shape looks wrong, stop and repair the
+module registration before running extraction. An extra repeated package
+segment below the module may indicate an over-broad source boundary. Do not write ad hoc scripts to
 count packages, parse `package.json`, or sample `unapproved/entities.jsonl`.
 
 ## Review Rules
 
-- Use `context review html <collection> --open` for visual review. If the
-  browser cannot be opened, provide the emitted `file://` URL to the user.
+- Use `context review html <collection> --open --format json` for visual review.
+  Check `opened`: say the browser opened only when it is `true`; otherwise
+  report `open_error` and provide the emitted `file_url` plus `absolute_path`.
 - Use `context review list <collection>` only for a textual overview.
-- Ask the user to paste the copied JSONL payload into chat. The agent writes
+- Ask the user to paste the copied review decision Payload into chat. Uniform
+  decisions use one JSON line; exceptions add JSONL lines. The agent writes
   that pasted payload to a temporary scratch file and runs `context review apply
   <payload-file>` only after the user has reviewed and provided the payload.
 - Do not synthesize review payloads from HTML, JSON, runtime snapshots, or
@@ -214,7 +276,7 @@ count packages, parse `package.json`, or sample `unapproved/entities.jsonl`.
   `context review approve <candidate-id> --collection <collection>` /
   `context review reject <candidate-id> --collection <collection>` or `--all`.
   These commands still enforce the scoped candidate-id gate.
-- Do not expand compact review JSONL into pretty JSON unless the user asks.
+- Do not expand the compact review decision Payload into pretty JSON unless the user asks.
 - Do not edit approved Markdown by hand as part of review apply.
 
 ## Prose Align And Compile Rules
@@ -225,8 +287,10 @@ product sequence:
 1. investigate material through Context evidence views;
 2. propose a structure draft with nodes, section plans, supported edges, and
    unresolved items;
-3. ask the user to confirm the structure, because confirmation freezes paths,
-   section ownership, relationships, and compile order for this round;
+3. repair validator blockers until `confirmation_ready=true`, stage the
+   structure, open its HTML report, then ask the user to confirm it because
+   confirmation freezes paths, section ownership, relationships, and compile
+   order for this round;
 4. compile source-bound draft pages from confirmed structure;
 5. send compiled drafts through human review, then close and build.
 
@@ -248,9 +312,16 @@ context run align:<type>:<source>:<collection> --stage --input <structure.yaml>
 
 Read source material only through these evidence views. `source-index` gives a
 compact refs-first map when run with `--compact`; use `span-detail` /
-`span-text` only for exact evidence. `structure-summary` is the review surface
-for the structure confirmation gate. Do not inspect `sources/` or `.tmp`
-directly.
+`span-text` only for exact evidence. When validate returns
+`repair_confirmation_blockers`, follow its repair route without asking for
+preliminary approval. `--repair suggested-splits` mechanically handles
+non-contiguous source Sections. For oversized Views, use the returned child
+View and contains-edge suggestions while classifying child Nodes from evidence.
+Stage only after
+`confirmation_ready=true`; stage opens the final `structure-summary` report for
+the structure confirmation gate. Ask a separate structure-design question only
+when evidence supports multiple incompatible semantic choices, and make clear
+that it is not final review. Do not inspect `sources/` or `.tmp` directly.
 
 Compile:
 
@@ -262,6 +333,10 @@ context run compile:<type>:<source>:<collection> --validate --input <compile-act
 context run compile:<type>:<source>:<collection> --stage --input <compile-actions.yaml> --format json
 ```
 
+Compile each confirmed View sequentially, but do not stop for Review after each
+write. Follow `continue_compile_batch` until no planned View remains; then open
+one collection-level Review, apply one Payload, and run close once.
+
 Default compile actions should mirror source spans into `verbatim` body and
 attach summary/kind/source refs. Explicit reader-visible content is not part of
 the current compile action contract; split evidence or return to structure

package/docs/reference/package-templates.md

@@ -182,10 +182,16 @@ Approved Markdown and kb package OKF output are an OKF superset:
 Accepted section `source_ref` forms:
 
 ```text
-src-N#symbol:<symbol-id>:<kind>@<digest>
+src-N#symbol:<file>:<symbol-id>:<kind>@<digest>
 src-N#span:<heading-hint> L<start>-<end>@<span-hash>
 ```
 
+The code symbol form includes the source-relative file so same-name symbols in
+different files resolve to one exact symbol-index row. Consumers should still
+treat the complete `source_ref` as opaque. Codegraph pages keep
+`candidate_fingerprint` at the top level and do not duplicate this evidence in
+`code_origin`.
+
 `#span:` refs retain source snapshot line ranges for human review, diffing, and
 stable re-pinning. They resolve against committed file/lark document snapshots,
 not the code symbol index.