@c4a/context-cli 0.6.2 → 0.6.3

package/docs/context-debug-event-v1.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://context4.ai/schemas/context-debug-event-v1.schema.json",
+  "title": "Context debug event v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "trace_id", "sequence", "at", "kind", "data"],
+  "properties": {
+    "schema": { "const": "context.debug.event.v1" },
+    "trace_id": { "type": "string", "minLength": 1 },
+    "sequence": { "type": "integer", "minimum": 1 },
+    "at": { "type": "string", "format": "date-time" },
+    "kind": {
+      "enum": [
+        "debug.enabled",
+        "debug.disabled",
+        "cli.invoked",
+        "cli.completed",
+        "agent-graph.evaluated",
+        "workflow.action-started",
+        "workflow.action-completed",
+        "workflow.stopped"
+      ]
+    },
+    "invocation_id": { "type": "string", "minLength": 1 },
+    "parent_invocation_id": { "type": "string", "minLength": 1 },
+    "data": { "type": "object" }
+  }
+}

package/docs/context-debug-replay-v1.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://context4.ai/schemas/context-debug-replay-v1.schema.json",
+  "title": "Context debug replay v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "generated_at", "events", "transitions"],
+  "properties": {
+    "schema": { "const": "context.debug.replay.v1" },
+    "generated_at": { "type": "string", "format": "date-time" },
+    "trace_id": { "type": "string" },
+    "events": {
+      "type": "array",
+      "items": { "$ref": "./context-debug-event-v1.schema.json" }
+    },
+    "transitions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["sequence", "at", "current"],
+        "properties": {
+          "sequence": { "type": "integer", "minimum": 1 },
+          "at": { "type": "string", "format": "date-time" },
+          "invocation_id": { "type": "string" },
+          "previous": { "type": "object" },
+          "current": { "type": "object" },
+          "selected_route": { "type": "object" }
+        }
+      }
+    }
+  }
+}

package/docs/debug-tracing.md

@@ -0,0 +1,86 @@
+# Workspace debug tracing
+
+Context debug tracing is an explicit, workspace-local observation mode. It is
+disabled by default. It does not change Agent Graph facts, route selection,
+human gates, command eligibility, lifecycle writes, or command exit status.
+
+Enable it while initializing a workspace:
+
+```bash
+context init context --debug
+```
+
+Or enable it later:
+
+```bash
+context debug enable
+```
+
+Both forms set `package.json` `context.debug` to `true`. Disabling tracing
+removes that property but keeps the existing trace for inspection:
+
+```bash
+context debug disable
+```
+
+## Files
+
+Tracing writes only below the ignored workspace `.tmp` directory:
+
+```text
+.tmp/context-runtime/debug/
+├── events.jsonl
+├── state.json
+└── replay.json
+```
+
+- `events.jsonl` is the append-only source of truth. Each line conforms to
+  [`context.debug.event.v1`](./context-debug-event-v1.schema.json).
+- `state.json` owns the trace id, monotonic sequence, and last observed graph
+  state. It is recorder state, not workflow state.
+- `replay.json` is a disposable projection produced by `context debug export`
+  and conforms to [`context.debug.replay.v1`](./context-debug-replay-v1.schema.json).
+
+No command stdout, source body, knowledge page, or resource body is copied into
+the trace. Sensitive option values are redacted. Command receipts contain only
+status, duration, byte counts, and hashes already available to the managed
+runner.
+
+## Event model
+
+The event stream records:
+
+- CLI invocation and completion, including parent invocation identity for
+  managed child commands;
+- Agent Graph evaluation revision, status, selected route, alternatives, and
+  whether the observable graph position changed;
+- managed workflow action start and completion with deterministic receipts;
+- the reason and graph position at which a managed loop stopped.
+
+`trace_id` groups the workspace-local debug history, `sequence` defines replay order,
+`invocation_id` groups work performed by one CLI process, and
+`parent_invocation_id` connects managed child commands to their runner. A UI
+can animate `agent-graph.evaluated` events whose `data.transition.changed` is
+true, then associate intervening command and action events by sequence and
+invocation identity.
+
+## Inspect and export
+
+```bash
+context debug status --format json
+context debug export --format json
+```
+
+Status returns configuration, event counts, and relative trace paths. Export
+mechanically derives a replay document containing the complete event stream and
+its changed graph transitions. A custom export path must remain below the
+workspace `.tmp` directory:
+
+```bash
+context debug export --output .tmp/analysis/replay.json --format json
+```
+
+Recorder failures are intentionally non-fatal. They can make a trace
+incomplete, but they cannot alter the command being observed. Consumers should
+therefore validate monotonic `sequence` values before presenting a replay as
+complete.

package/docs/quickstart.md

@@ -75,7 +75,7 @@ The CLI performs mechanical work such as source registration, capture,
 validation, review application, verify, close, and build. The agent performs
 semantic judgment only when the workflow asks for it.
 
-When the user explicitly requests fully managed operation, the Agent may use
+When the user explicitly requests fully managed operation, the Agent starts with
 `context run --managed --until blocked-or-complete --format json` to collapse
 consecutive deterministic routes. The CLI re-evaluates every revision and
 stops before semantic reads, configuration, missing authority, diagnostics, or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context-cli",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "type": "module",
   "description": "Local CLI for capturing, compiling, and governing knowledge workspaces",
   "license": "MIT",
@@ -16,12 +16,15 @@
     "claude-code",
     "claude-plugin"
   ],
+  "engines": {
+    "node": ">=20"
+  },
   "bin": {
-    "context": "cli.js"
+    "context": "dist/cli.js"
   },
   "dependencies": {
-    "@c4a/agent-graph": "0.2.3",
-    "@c4a/context": "0.6.2",
+    "@c4a/agent-graph": "0.2.4",
+    "@c4a/context": "0.6.3",
     "commander": "^11.0.0",
     "fast-xml-parser": "^5.10.1",
     "handlebars": "^4.7.8",

package/plugins/VERSION

@@ -1 +1 @@
-0.6.2
+0.6.3

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "context",
   "description": "Maintain a project-local knowledge workspace through init and next-step agent guidance.",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "author": {
     "name": "c4a"
   },

package/plugins/claude/commands/continue.md

@@ -7,31 +7,36 @@ allowed-tools: Bash(context:*), Bash(bun:*), Bash(cd *)
 ## Your Task
 
 Use this as the conversational entry for an existing Context workspace. There
-is no `context continue` CLI primitive. Start with:
+is no `context continue` CLI primitive. Without explicit fully managed
+authority, start with:
 
 ```bash
 context status --format json
 ```
 
-Use `context status --managed --format json` only when the user explicitly
-requested fully managed operation in this conversation. Never persist or reuse
-that authority in another conversation. While the request remains active, use
-`--managed` for every status evaluation; stop using it when the conversation
-ends or the user revokes it.
+If the user explicitly asks to enable debugging, first run
+`context debug enable`. It sets `package.json` `context.debug=true` and records
+subsequent CLI and Agent Graph events only below `.tmp/context-runtime/debug/`.
+Do not enable it proactively; tracing is not workflow authority or evidence.
 
-If the user is starting a new workspace or a new batch from a raw repository
-root, do not run `context status` first. Use the public Context init entry or
-`context init` to create the workspace, complete the init setup command, then
-return here from the initialized workspace.
-
-For an explicitly managed conversation, the CLI can collapse consecutive
-mechanical routes:
+When the user explicitly requests fully managed operation in this conversation,
+start with the managed loop instead of a manual status/action cycle:
 
 ```bash
 context run --managed --until blocked-or-complete --format json
 ```
 
-Pass an additional `--authority` only when the user explicitly granted that
+Never persist or reuse that authority in another conversation. While the
+request remains active, use `--managed` for every resumed status evaluation;
+stop using it when the conversation ends or the user revokes it.
+
+If the user is starting a new workspace or a new batch from a raw repository
+root, do not run `context status` first. Use the public Context init entry or
+`context init` to create the workspace, complete the init setup command, then
+return here from the initialized workspace.
+
+The managed loop is the default entry for an explicitly managed conversation,
+not an optional optimization. Pass an additional `--authority` only when the user explicitly granted that
 non-managed authority in this conversation. This loop executes only one
 revision-bound command at a time and re-evaluates after every receipt. It stops
 before read-only interpretation, project configuration, unresolved authority,

package/plugins/claude/commands/init.md

@@ -1,6 +1,6 @@
 ---
 description: "Initialize a Context knowledge workspace."
-argument-hint: "[project-dir] [--name <name>] [--language en|zh-CN]"
+argument-hint: "[project-dir] [--name <name>] [--language en|zh-CN] [--debug]"
 allowed-tools: Bash(context:*), Bash(bun:*), Bash(cd *)
 ---
 
@@ -18,6 +18,8 @@ Chinese conversation and `en` for an English conversation. This explicit CLI
 value controls generated workspace instructions and starter templates. Never
 substitute `.` when `project-dir` was omitted; the default is `context/`. Use
 `--dev` only for an explicitly requested local-link test.
+Add `--debug` only when the user explicitly asks to trace this workspace. Debug
+mode is otherwise off by default.
 
 If init reports `init-target-nonempty`, explain that existing files would share
 the workspace root. Run the returned `--allow-nonempty` command only after

package/plugins/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "Maintain a project-local knowledge workspace through init and next-step agent guidance.",
   "author": {
     "name": "c4a"
@@ -18,7 +18,7 @@
   "skills": "./skills/",
   "interface": {
     "displayName": "C4A Context",
-    "shortDescription": "Initialize and advance a local, source-linked project knowledge workspace.\nv0.6.2",
+    "shortDescription": "Initialize and advance a local, source-linked project knowledge workspace.\nv0.6.3",
     "longDescription": "Create a Context workspace and use agent-guided next steps to register sources, run extraction, review candidates, build package outputs, and verify health without silently mutating source repositories.",
     "developerName": "c4a",
     "category": "Productivity",

package/plugins/codex/skills/continue/SKILL.md

@@ -19,31 +19,36 @@ Public Context entry for agents that expose skills instead of slash commands.
 ## Workflow
 
 Use this as the conversational entry for an existing Context workspace. There
-is no `context continue` CLI primitive. Start with:
+is no `context continue` CLI primitive. Without explicit fully managed
+authority, start with:
 
 ```bash
 context status --format json
 ```
 
-Use `context status --managed --format json` only when the user explicitly
-requested fully managed operation in this conversation. Never persist or reuse
-that authority in another conversation. While the request remains active, use
-`--managed` for every status evaluation; stop using it when the conversation
-ends or the user revokes it.
+If the user explicitly asks to enable debugging, first run
+`context debug enable`. It sets `package.json` `context.debug=true` and records
+subsequent CLI and Agent Graph events only below `.tmp/context-runtime/debug/`.
+Do not enable it proactively; tracing is not workflow authority or evidence.
 
-If the user is starting a new workspace or a new batch from a raw repository
-root, do not run `context status` first. Use the public Context init entry or
-`context init` to create the workspace, complete the init setup command, then
-return here from the initialized workspace.
-
-For an explicitly managed conversation, the CLI can collapse consecutive
-mechanical routes:
+When the user explicitly requests fully managed operation in this conversation,
+start with the managed loop instead of a manual status/action cycle:
 
 ```bash
 context run --managed --until blocked-or-complete --format json
 ```
 
-Pass an additional `--authority` only when the user explicitly granted that
+Never persist or reuse that authority in another conversation. While the
+request remains active, use `--managed` for every resumed status evaluation;
+stop using it when the conversation ends or the user revokes it.
+
+If the user is starting a new workspace or a new batch from a raw repository
+root, do not run `context status` first. Use the public Context init entry or
+`context init` to create the workspace, complete the init setup command, then
+return here from the initialized workspace.
+
+The managed loop is the default entry for an explicitly managed conversation,
+not an optional optimization. Pass an additional `--authority` only when the user explicitly granted that
 non-managed authority in this conversation. This loop executes only one
 revision-bound command at a time and re-evaluates after every receipt. It stops
 before read-only interpretation, project configuration, unresolved authority,

package/plugins/codex/skills/init/SKILL.md

@@ -30,6 +30,8 @@ Chinese conversation and `en` for an English conversation. This explicit CLI
 value controls generated workspace instructions and starter templates. Never
 substitute `.` when `project-dir` was omitted; the default is `context/`. Use
 `--dev` only for an explicitly requested local-link test.
+Add `--debug` only when the user explicitly asks to trace this workspace. Debug
+mode is otherwise off by default.
 
 If init reports `init-target-nonempty`, explain that existing files would share
 the workspace root. Run the returned `--allow-nonempty` command only after

package/plugins/cursor/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "context",
   "displayName": "C4A Context",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "Maintain a project-local knowledge workspace through init and next-step agent guidance.",
   "author": {
     "name": "Context4AI",

package/plugins/cursor/commands/context-continue.md

@@ -11,31 +11,36 @@ Continue the Context workflow from the current workspace state.
 ## Workflow
 
 Use this as the conversational entry for an existing Context workspace. There
-is no `context continue` CLI primitive. Start with:
+is no `context continue` CLI primitive. Without explicit fully managed
+authority, start with:
 
 ```bash
 context status --format json
 ```
 
-Use `context status --managed --format json` only when the user explicitly
-requested fully managed operation in this conversation. Never persist or reuse
-that authority in another conversation. While the request remains active, use
-`--managed` for every status evaluation; stop using it when the conversation
-ends or the user revokes it.
+If the user explicitly asks to enable debugging, first run
+`context debug enable`. It sets `package.json` `context.debug=true` and records
+subsequent CLI and Agent Graph events only below `.tmp/context-runtime/debug/`.
+Do not enable it proactively; tracing is not workflow authority or evidence.
 
-If the user is starting a new workspace or a new batch from a raw repository
-root, do not run `context status` first. Use the public Context init entry or
-`context init` to create the workspace, complete the init setup command, then
-return here from the initialized workspace.
-
-For an explicitly managed conversation, the CLI can collapse consecutive
-mechanical routes:
+When the user explicitly requests fully managed operation in this conversation,
+start with the managed loop instead of a manual status/action cycle:
 
 ```bash
 context run --managed --until blocked-or-complete --format json
 ```
 
-Pass an additional `--authority` only when the user explicitly granted that
+Never persist or reuse that authority in another conversation. While the
+request remains active, use `--managed` for every resumed status evaluation;
+stop using it when the conversation ends or the user revokes it.
+
+If the user is starting a new workspace or a new batch from a raw repository
+root, do not run `context status` first. Use the public Context init entry or
+`context init` to create the workspace, complete the init setup command, then
+return here from the initialized workspace.
+
+The managed loop is the default entry for an explicitly managed conversation,
+not an optional optimization. Pass an additional `--authority` only when the user explicitly granted that
 non-managed authority in this conversation. This loop executes only one
 revision-bound command at a time and re-evaluates after every receipt. It stops
 before read-only interpretation, project configuration, unresolved authority,

package/plugins/cursor/commands/context-init.md

@@ -1,6 +1,6 @@
 ---
 description: "Initialize a Context knowledge workspace."
-argument-hint: "[project-dir] [--name <name>] [--language en|zh-CN]"
+argument-hint: "[project-dir] [--name <name>] [--language en|zh-CN] [--debug]"
 allowed-tools: Bash(context:*), Bash(bun:*), Bash(cd *)
 ---
 
@@ -22,6 +22,8 @@ Chinese conversation and `en` for an English conversation. This explicit CLI
 value controls generated workspace instructions and starter templates. Never
 substitute `.` when `project-dir` was omitted; the default is `context/`. Use
 `--dev` only for an explicitly requested local-link test.
+Add `--debug` only when the user explicitly asks to trace this workspace. Debug
+mode is otherwise off by default.
 
 If init reports `init-target-nonempty`, explain that existing files would share
 the workspace root. Run the returned `--allow-nonempty` command only after

package/plugins/skills/context-continue/SKILL.md

@@ -19,31 +19,36 @@ Public Context entry for agents that expose skills instead of slash commands.
 ## Workflow
 
 Use this as the conversational entry for an existing Context workspace. There
-is no `context continue` CLI primitive. Start with:
+is no `context continue` CLI primitive. Without explicit fully managed
+authority, start with:
 
 ```bash
 context status --format json
 ```
 
-Use `context status --managed --format json` only when the user explicitly
-requested fully managed operation in this conversation. Never persist or reuse
-that authority in another conversation. While the request remains active, use
-`--managed` for every status evaluation; stop using it when the conversation
-ends or the user revokes it.
+If the user explicitly asks to enable debugging, first run
+`context debug enable`. It sets `package.json` `context.debug=true` and records
+subsequent CLI and Agent Graph events only below `.tmp/context-runtime/debug/`.
+Do not enable it proactively; tracing is not workflow authority or evidence.
 
-If the user is starting a new workspace or a new batch from a raw repository
-root, do not run `context status` first. Use the public Context init entry or
-`context init` to create the workspace, complete the init setup command, then
-return here from the initialized workspace.
-
-For an explicitly managed conversation, the CLI can collapse consecutive
-mechanical routes:
+When the user explicitly requests fully managed operation in this conversation,
+start with the managed loop instead of a manual status/action cycle:
 
 ```bash
 context run --managed --until blocked-or-complete --format json
 ```
 
-Pass an additional `--authority` only when the user explicitly granted that
+Never persist or reuse that authority in another conversation. While the
+request remains active, use `--managed` for every resumed status evaluation;
+stop using it when the conversation ends or the user revokes it.
+
+If the user is starting a new workspace or a new batch from a raw repository
+root, do not run `context status` first. Use the public Context init entry or
+`context init` to create the workspace, complete the init setup command, then
+return here from the initialized workspace.
+
+The managed loop is the default entry for an explicitly managed conversation,
+not an optional optimization. Pass an additional `--authority` only when the user explicitly granted that
 non-managed authority in this conversation. This loop executes only one
 revision-bound command at a time and re-evaluates after every receipt. It stops
 before read-only interpretation, project configuration, unresolved authority,

package/plugins/skills/context-init/SKILL.md

@@ -30,6 +30,8 @@ Chinese conversation and `en` for an English conversation. This explicit CLI
 value controls generated workspace instructions and starter templates. Never
 substitute `.` when `project-dir` was omitted; the default is `context/`. Use
 `--dev` only for an explicitly requested local-link test.
+Add `--debug` only when the user explicitly asks to trace this workspace. Debug
+mode is otherwise off by default.
 
 If init reports `init-target-nonempty`, explain that existing files would share
 the workspace root. Run the returned `--allow-nonempty` command only after

package/providers/context/actions/inspect-repository-recovery.yaml

@@ -0,0 +1,6 @@
+schema: agent-graph.action.v1
+id: inspect-repository-recovery
+description: Group missing repository modules by physical checkout and show recovery choices.
+runner: command
+effect: read
+command: context source recovery-plan --format json

package/providers/context/actions/reconcile-review-identities.yaml

@@ -0,0 +1,5 @@
+schema: agent-graph.action.v1
+id: reconcile-review-identities
+runner: host
+effect: write
+handler: context.review.preserve-approved-identities

package/providers/context/actions/repair-verification.yaml

@@ -1,5 +1,5 @@
 schema: agent-graph.action.v1
 id: repair-verification
-runner: command
-effect: read
-command: context verify --format json
+runner: host
+effect: external
+handler: context.verification.repair-next

package/providers/context/actions/restore-repository-sources.yaml

@@ -0,0 +1,7 @@
+schema: agent-graph.action.v1
+id: restore-repository-sources
+description: Restore registered repository sources from user-confirmed local paths or explicit clones.
+runner: command
+effect: external
+command: context source restore --input - --format json
+inputSchema: schemas/repository-source-recovery.schema.json

package/providers/context/codes.yaml

@@ -18,7 +18,7 @@ codes:
   - { code: route.evidence.decision-required, kind: route-reason, summary: A source-evidence change needs an explicit maintenance decision., document: resources/procedures/evidence-maintenance.md }
   - { code: route.evidence.maintenance-required, kind: route-reason, summary: Apply the selected evidence-maintenance action., document: resources/procedures/evidence-maintenance.md }
   - { code: route.source.boundary-required, kind: route-reason, summary: No knowledge source boundary has been registered., document: resources/procedures/source-boundary.md }
-  - { code: route.source.repository-not-ready, kind: route-reason, summary: A registered repository source is not ready locally., document: resources/procedures/source-boundary.md }
+  - { code: route.source.repository-not-ready, kind: route-reason, summary: A registered repository checkout or local source link must be restored., document: resources/procedures/repository-source-recovery.md }
   - { code: route.capture.configuration-required, kind: route-reason, summary: Registered document sources are missing capture declarations., document: resources/procedures/project-configuration.md }
   - { code: route.capture.permission-required, kind: route-reason, summary: External document capture requires source-read permission., document: resources/procedures/document-capture.md }
   - { code: route.capture.pending-target, kind: route-reason, summary: Capture the next declared document target., document: resources/procedures/document-capture.md }
@@ -31,6 +31,7 @@ codes:
   - { code: route.structure.confirmation-required, kind: route-reason, summary: A staged structure is waiting for confirmation., document: resources/procedures/prose-align.md }
   - { code: route.structure.confirm, kind: route-reason, summary: Persist the confirmed structure slot., document: resources/procedures/prose-align.md }
   - { code: route.compile.pending-target, kind: route-reason, summary: Compile the next planned source-bound knowledge view., document: resources/procedures/prose-compile.md }
+  - { code: route.review.identity-conflict, kind: route-reason, summary: Preserve approved ViewRef and path identity before Review., document: resources/procedures/knowledge-review.md }
   - { code: route.review.decision-required, kind: route-reason, summary: The complete current candidate batch needs one review decision set., document: resources/procedures/knowledge-review.md }
   - { code: route.review.apply-managed, kind: route-reason, summary: Apply the current candidate batch under explicit session-managed authority., document: resources/procedures/knowledge-review.md }
   - { code: route.close.projection-stale, kind: route-reason, summary: Rebuild the deterministic approved structure projection., document: resources/procedures/close-and-build.md }