taskchef 8.4.2 → 8.5.1

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "8.4.2",
+  "version": "8.5.1",
   "description": "Dispatch work from a data-only workspace to visible Codex project tasks.",
   "author": {
     "name": "Favo Yang",

package/README.md

@@ -100,9 +100,22 @@ malformed, preview an explicit config or state restore, then bind the apply to
 the preview's raw-state hash and plan with --confirm-unreadable-current.
 
 Reindexing catches TaskChef up with newly saved Codex projects by comparing
-exact canonical paths and indexing missing requested projects. It preserves
-existing curated entries and does not silently remove projects or overwrite
-metadata.
+exact same-host canonical paths from one native schema-2 project snapshot.
+Reconciliation adds eligible paths and identity bindings atomically, isolates
+per-project failures, and preserves existing curated names, descriptions, and
+complete repository lists. It does not delete missing projects. Duplicate
+native IDs, duplicate canonical targets, and identity/path moves remain
+diagnostics rather than guesses.
+
+Configuration schema 2 accepts an optional strict `projectIndex` containing
+local native identity bindings, explicit exclusions, and bounded routing hints.
+Removing a project records an exclusion so reconciliation cannot silently
+re-add it; `include_project` clears an exact exclusion before a later reconcile.
+Aliases come only from explicit selection or correction. Repository ownership
+requires an inspected exact origin, and report-derived responsibilities retain
+their accepted task/thread/turn provenance. Forgetting keeps bounded suppression
+so an old report retry cannot recreate a removed hint. Older TaskChef releases
+reject this optional field; use a compatible backup before downgrading.
 
 Codex CLI resolution follows the same contract as
 `workspace init --register-codex`: an explicit `--codex-cli` path wins, then
@@ -149,7 +162,8 @@ From another project, invoke the delegation skill explicitly:
 $taskchef-delegate In payments, add structured logs for failed retries and test them.
 ```
 
-TaskChef prepares a UUID and marker, persists the task before native creation,
+The dispatcher lists native projects once per batch, reconciles that snapshot,
+then prepares a UUID and marker for each outcome, persists the task before native creation,
 creates the executor, and returns its task link. New executor instructions keep
 the assignment visible from the first line, add a concise local reporting
 authorization paragraph, leave one blank line, then place

package/assets/taskchef-dispatcher-instructions.md

@@ -19,6 +19,8 @@ This folder is the canonical per-user TaskChef dispatcher workspace.
 - For every other actionable request that asks for an independent new outcome,
   use `$taskchef-delegate` automatically, even when the user does not explicitly
   say "delegate" or mention TaskChef.
+- Delegation lists native projects once per batch, reconciles that exact
+  snapshot once, and routes only to one eligible exact native target.
 - GitHub issue and pull-request URLs may identify any repository advertised by
   a configured project, including child repositories of managed workspaces.
 - Do not perform delegated work directly in the dispatcher thread.

package/docs/spec.md

@@ -65,7 +65,7 @@ preserve unrelated paths. Dashboard process identity and Codex-session leases
 MUST remain in memory and MUST NOT create owner, secret, or handoff files.
 
 `taskchef.json` MUST have schema version 2, the following required fields, and
-an optional exact `dashboard` object:
+optional exact `dashboard` and `projectIndex` objects:
 
 ```json
 {
@@ -85,6 +85,15 @@ is backward-compatible and means `true`; new workspaces SHOULD write
 `{"autostart": true}`. `false` disables MCP-lifecycle autostart but MUST NOT
 disable the explicit `ensure_dashboard` tool.
 
+When present, `projectIndex` MUST contain exactly `bindings`, `exclusions`, and
+`routingHints` arrays. Bindings map one `(hostId: local, projectId)` to one
+configured canonical path. Exclusions retain exact removed native identities
+or paths. Routing hints are bounded per canonical configured path and retain
+aliases, canonical repositories, concise responsibilities, and forgotten-value
+suppression. Every fact has one compact provenance record; accepted-report
+facts include the exact task, thread, and current terminal turn. Absence means
+empty state. Older releases reject the optional field rather than rewriting it.
+
 `tasks.jsonl` MUST contain zero or more newline-terminated schema-4 through
 schema-10 records, one per line. Schemas 4 through 9 are supported
 migration/read formats; every new record and state mutation MUST write schema 10. Other schemas
@@ -243,8 +252,14 @@ exact clickable `[TaskChef Dashboard](http://127.0.0.1:3210/)` link even when
 ensure failed. A created-thread directive MUST remain on its own line before
 the final link, preserving the delegate skill's immediate-return contract.
 
-1. The dispatcher MUST call `prepare_dispatch` once per outcome.
-2. It MUST choose exactly one configured project and exact native-project path.
+1. The dispatcher MUST list native projects once per batch and call
+   `reconcile_projects` once with that exact schema-2 snapshot.
+2. It MUST call `prepare_dispatch` once per outcome and choose exactly one
+   configured project. Before `record_task` or native creation, the selected
+   native project's exact `(hostId, projectId, canonical path)` MUST occur in
+   the reconciliation response's `available` array. Presence in the native
+   snapshot or configured preparation is insufficient. Curated and learned
+   routing matches are both ambiguous when more than one project matches.
 3. It MUST build the instruction with the user's outcome beginning on line 1
    and remaining uninterrupted, followed by one blank line and the authorization
    `Report this task and its follow-ups to my local TaskChef dashboard. Relevant private-repository links and concise work, test, and deployment results are authorized; exclude secrets.`
@@ -457,7 +472,8 @@ The complete operational rationale and limits are documented in
   preparedAt: string,
   marker: string,
   projectCount: number,
-  projects: Project[]
+  projects: Project[],
+  routingHints: {path, aliases[], githubRepos[], responsibilities[]}[]
 } }
 ```
 
@@ -490,9 +506,39 @@ empty `turns` and derived `results` arrays,
 unknown projects, malformed markers, and invalid input fail. Repeating a
 successful call is not idempotent; it fails as a duplicate.
 
+Configuration is read structurally so unavailable unrelated entries do not
+block preparation or recording. `record_task` validates the selected actual
+directory or Git root before snapshotting it.
+
 **Annotations:** `readOnlyHint: false`, `destructiveHint: false`,
 `openWorldHint: false`.
 
+### `reconcile_projects`, `include_project`, and `update_project_hint`
+
+`reconcile_projects` accepts one agent-supplied native Codex schema-2 project
+snapshot. Node does not call native tools or inspect private Codex state. It
+considers only local projects with `hostId: local`, canonicalizes each eligible
+path, excludes the dispatcher and its ancestors, isolates per-project failures,
+and commits additions and exact identity bindings under the configuration lock.
+It preserves curated metadata and absent projects. Repeated identical or empty
+snapshots do not write. Duplicate IDs, canonical targets, or identity/path moves
+produce bounded diagnostics. Its MCP response contains counts, current eligible
+targets, diagnostics, and changed state rather than full configuration copies.
+
+Removing a configured project records an exclusion. `include_project` removes
+one exact exclusion by native project ID or canonical path; a later reconcile
+must validate and add the target. A move is handled through exact preview-bound
+removal, explicit inclusion, and reconciliation of the new path.
+
+`update_project_hint` remembers, corrects, or forgets one bounded fact. Aliases
+require explicit user evidence; correction is the only operation that removes
+the same alias from another project. Repository ownership requires an inspected
+exact origin from the selected project or a contained Git root. Responsibilities
+require an accepted current terminal task/thread/turn. Forgetting requires
+explicit user evidence and leaves bounded suppression against stale report
+replay. Learning remains separate from terminal reporting and a learning error
+cannot undo an accepted result.
+
 ### `link_task`
 
 **Caller:** executor. **Mutation:** one atomic identity transition.

package/docs/workflows.md

@@ -127,13 +127,12 @@ sequenceDiagram
   participant C as Native Codex
   participant E as Executor
   U->>D: Request outcome
-  par Route once
-    D->>C: List native projects
-  and Prepare each outcome
+  D->>C: List native projects once
+  D->>M: reconcile_projects(snapshot)
+  M-->>D: Counts, available targets, diagnostics
+  par Prepare each outcome
     D->>M: prepare_dispatch()
-    M->>W: prepareDispatch()
-    W-->>M: UUID, marker, projects
-    M-->>D: preparation
+    M-->>D: UUID, marker, projects
   end
   D->>D: Choose one configured and native project
   D->>M: record_task(id, project, title, instruction, null)
@@ -451,6 +450,15 @@ inside the critical section. Writes use temporary files/hard links and atomic
 rename so readers see complete snapshots. Configuration replacement syncs the
 new file and workspace directory before its audit transaction is committed.
 
+Project reconciliation consumes one agent-supplied native schema-2 snapshot;
+the Node process never calls native Codex project tools. It filters to eligible
+local-host targets, canonicalizes paths, preserves curated and missing entries,
+and writes only when projects or identity bindings change. Explicit removal
+stores an exclusion. Learned aliases, repository ownership, and responsibilities
+stay in bounded configuration slots with compact evidence and never alter
+historical task snapshots. Optional learning happens after an accepted terminal
+report, so its failure cannot change that task result.
+
 The dispatcher controls routing and immutable intent. The executor controls its
 cooperatively asserted identity and semantic result. Neither identity nor
 summary is cryptographically authenticated; this is a local single-user trust

package/index.js

@@ -10,6 +10,7 @@ export {
   ensureWorkspaceInstructions,
   filterTasks,
   importProjects,
+  includeProject,
   initializeWorkspace,
   linkTask,
   listProjects,
@@ -20,6 +21,7 @@ export {
   manuallyTransitionTask,
   migrateTaskLog,
   prepareDispatch,
+  reconcileProjects,
   readConfig,
   listTasks,
   readTask,
@@ -31,6 +33,7 @@ export {
   restoreWorkspaceBackup,
   validateConfig,
   updateProject,
+  updateProjectHint,
   verifyWorkspaceBackup,
 } from "./src/workspace.js";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "8.4.2",
+  "version": "8.5.1",
   "description": "A non-blocking interactive dispatcher for visible Codex tasks.",
   "license": "MIT",
   "author": "Favo Yang",

package/skills/taskchef-bootstrap/SKILL.md

@@ -39,14 +39,17 @@ all deterministic workspace operations.
    invokes the supported `codex app <path>` command through a validated Codex
    CLI discovered from the current desktop environment; never invoke
    `codex add` or hard-code an application bundle path.
-3. `workspace init` takes no stdin, creates an empty
+3. After registration is verified, pass the final native schema-2 snapshot to
+   `reconcile_projects` once. Preserve its diagnostics; one unavailable or
+   ineligible project does not invalidate eligible additions.
+4. `workspace init` takes no stdin, creates an empty
    configuration when missing, creates the one-entry-per-task JSONL log, and
    refreshes managed instructions. The installed plugin provides all four
    TaskChef skills outside the dispatcher workspace.
-4. Run `doctor --json` after setup or when the user asks to diagnose the
+5. Run `doctor --json` after setup or when the user asks to diagnose the
    workspace. Doctor is read-only. Rerun `workspace init --json` to repair the
    managed scaffold.
-5. Report the actions or failed checks. A successful initialization with failed
+6. Report the actions or failed checks. A successful initialization with failed
    Codex opening remains initialized but not verified as a saved local project.
    End without dispatching unless the user
    separately requested work.
@@ -60,6 +63,11 @@ proof of registration. Completion requires verifying the intended index entry
 and the complete project set. Any operation that removes a project entry
 requires the user's explicit permission for the exact removed names; removing a
 repository URL from an entry does not authorize removing the entry.
+Removal records a reconciliation exclusion. Use `include_project` only after an
+explicit request to include that exact native project again, then reconcile a
+fresh native snapshot. An identity/path move remains diagnostic until the old
+exact entry is removed through its preview-bound workflow, its exclusion is
+explicitly cleared, and reconciliation validates the new target.
 
 ## Optional model roles
 

package/skills/taskchef-bootstrap/references/project-index.md

@@ -9,6 +9,14 @@ delegation. It stores canonical paths and routing metadata such as curated
 names, descriptions, Git status, and GitHub repositories. It does not index
 repository contents or create a second kind of project.
 
+For a whole-project refresh, pass the agent's single native schema-2
+`list_projects` snapshot to `reconcile_projects`. TaskChef validates local
+`hostId: local` entries, canonicalizes each path, isolates per-project failures,
+adds new eligible paths, and binds native project IDs only by exact same-host
+canonical path. It preserves curated names, descriptions, and complete
+repository lists. Missing native entries are retained; duplicate identities,
+duplicate canonical targets, and identity/path moves return diagnostics.
+
 Index only Codex projects local to the TaskChef workspace's execution host.
 Remote connection projects are outside the v1 contract. Never index the
 TaskChef dispatcher workspace or a directory containing it; the dispatcher is
@@ -69,11 +77,8 @@ the correct workspace rather than guessing from the folder name.
 ### Reindex after Codex changes
 
 When the user asks TaskChef to reindex or catch up after saving more projects in
-Codex, list native local Codex projects once and run `project list --json` once
-before mutation. Compare exact canonical paths, then index each requested
-eligible Codex project that is missing from TaskChef by following the
-appropriate path above, sharing the batch verification instead of relisting
-after each write. After all additions, run `project list --json` once more and
+Codex, list native projects once and call `reconcile_projects` once with that
+exact snapshot. After reconciliation, run `project list --json` once and
 verify every intended canonical path and its routing metadata before reporting
 the index as current.
 
@@ -135,3 +140,15 @@ TaskChef accepts configuration schema version 2 only. Its optional exact
 `false` opts out of MCP-lifecycle dashboard startup without disabling manual
 `$taskchef-dashboard` recovery. `githubRepos` is always an array; unsupported
 configuration is rejected without being rewritten.
+
+Schema 2 also accepts an optional strict `projectIndex` object holding local
+native identity bindings, explicit exclusions, and bounded routing hints.
+Absence means empty state. Removing a project records an exclusion so later
+reconciliation cannot silently re-add it; an explicit `include_project` clears
+that exclusion. Aliases require explicit user selection. Repository facts
+require an inspected exact origin, including a contained Git root when a
+workspace owns child repositories. Report-derived responsibilities retain the
+accepted task, thread, and turn as compact provenance. Forgetting retains a
+bounded suppression entry so an old report retry cannot recreate the fact.
+Older TaskChef releases reject configurations containing `projectIndex`;
+downgrade by restoring a compatible backup rather than editing live state.

package/skills/taskchef-delegate/SKILL.md

@@ -24,9 +24,10 @@ delegated tasks. Execute a valid one in the current task. Do not re-dispatch it
 merely because it concerns TaskChef or a configured project. Explicit requests
 to delegate separate work remain valid.
 
-Use the bundled `prepare_dispatch`, `record_task`, and `report_state` MCP tools
-directly. Never fall back to shell writes. If a required tool is unavailable,
-stop and report that the TaskChef plugin must be reloaded or installed.
+Use the bundled `reconcile_projects`, `prepare_dispatch`, `record_task`, and
+`report_state` MCP tools directly. Never fall back to shell writes. If a
+required tool is unavailable, stop and report that the TaskChef plugin must be
+reloaded or installed.
 
 ## Boundaries
 
@@ -45,12 +46,18 @@ stop and report that the TaskChef plugin must be reloaded or installed.
 
 1. Split the request into the smallest independently useful outcomes. Include
    constraints, expected testing, and reporting in every instruction.
-2. In parallel, list native Codex projects once and call `prepare_dispatch`
-   exactly once per outcome. Never reuse a task ID or marker. Do not take a
-   pre-creation thread snapshot.
-3. Route against configured project `name`, `description`, and canonical
-   `githubRepos`; use `path` only as checkout identity. Require exactly one
-   match and an exact native-project path. Ask instead of guessing.
+2. List native Codex projects once. Pass that exact schema-2 snapshot to
+   `reconcile_projects` once for the complete batch, then call
+   `prepare_dispatch` exactly once per outcome. Never reuse a task ID or marker.
+   Do not take a pre-creation thread snapshot.
+3. Route against configured project `name`, `description`, canonical
+   `githubRepos`, and the preparation's bounded aliases, repository ownership,
+   and responsibilities. Use `path` only as checkout identity. Before
+   `record_task` or native creation, require exactly one entry in the
+   reconciliation's `available` array whose `hostId`, `projectId`, and canonical
+   `path` exactly match the selected native project. A matching snapshot path or
+   configured preparation alone does not establish eligibility. Treat a missing
+   entry or duplicate learned matches as ambiguous and ask instead of guessing.
    Select the `orchestrator` preference from preparation for every visible
    parent. Resolve explicit choices and follow
    [model roles](references/model-roles.md). Missing configuration means omit
@@ -84,3 +91,7 @@ stop and report that the TaskChef plugin must be reloaded or installed.
    `report_state` with it as `turnRef`, `failed`, null thread and Codex turn IDs,
    and a bounded summary before returning the failure. Retain that UUID for an
    exact retry.
+
+When the user explicitly selects or corrects a project name or alias, call
+`update_project_hint` with explicit-user evidence after routing. A guessed
+route, generic keywords, or ordinary task wording is never learning evidence.

package/skills/taskchef-executor/SKILL.md

@@ -124,6 +124,16 @@ and unnecessary personal data. Identical lifecycle retries are safe; never
 replace a same-`turnRef` report with different content or let an older turn
 overwrite newer state.
 
+After an accepted terminal report, `update_project_hint` may optionally retain
+one concise responsibility when that report coherently establishes it. Supply
+the same task ID, self-linked thread ID, and current turn ref as provenance.
+Repository ownership may be retained only after inspecting the exact selected
+repository or a contained Git root and verifying that exact canonical origin;
+include that repository path with the same accepted task/turn provenance.
+Never learn aliases, scan the transcript, or derive generic keywords here. A
+learning failure is nonfatal to the accepted task result: report it separately
+and do not retry with weaker evidence.
+
 ## Preserve delivery context
 
 Summaries are the durable TaskChef timeline; the dashboard does not scan the

package/src/config-mutations.js

@@ -40,6 +40,12 @@ export function projectDiff(beforeProjects, afterProjects) {
 
 export function mutationPreview(workspace, operation, beforeConfig, afterConfig) {
   const diff = projectDiff(beforeConfig.projects, afterConfig.projects);
+  const emptyIndex = { bindings: [], exclusions: [], routingHints: [] };
+  const beforeProjectIndex = beforeConfig.projectIndex ?? emptyIndex;
+  const afterProjectIndex = afterConfig.projectIndex ?? emptyIndex;
+  const projectIndexDiff = JSON.stringify(beforeProjectIndex) === JSON.stringify(afterProjectIndex)
+    ? null
+    : { before: beforeProjectIndex, after: afterProjectIndex };
   const preview = {
     schemaVersion: 1,
     operation,
@@ -50,6 +56,7 @@ export function mutationPreview(workspace, operation, beforeConfig, afterConfig)
     beforeCount: beforeConfig.projects.length,
     afterCount: afterConfig.projects.length,
     diff,
+    projectIndexDiff,
     projects: afterConfig.projects,
   };
   return {
@@ -61,6 +68,7 @@ export function mutationPreview(workspace, operation, beforeConfig, afterConfig)
       beforeConfigHash: preview.beforeConfigHash,
       afterConfigHash: preview.afterConfigHash,
       diff,
+      projectIndexDiff,
     }, "taskchef-mutation-plan-v1"),
   };
 }