Summary

• Problem: No deterministic way to bind a chat conversation to a registered codebase — users had to rely on the AI inferring the project, which is non-deterministic and error-prone.
• Why it matters: Project-scoped conversations need the correct codebase_id and cwd for workflows, tool filtering, and env-var injection to work. Without explicit binding, the orchestrator may operate without codebase context or against the wrong project.
• What changed: Added /setproject <name> as a deterministic slash command — adds a resolveCodebaseName 4-tier fuzzy resolver, a handleSetProject handler, dispatch registration, and a /help entry.
• What did not change: No schema migrations, no new DB tables, no web UI changes, isolation_env_id is not cleared on bind (users have existing worktree commands for that).

UX Journey

Before

User                      Archon                      AI
────                      ──────                      ──
sends "work on my-app" ──▶ orchestrator sees text
                            routes to AI ────────────▶ maybe infers project
                            receives reply ◀─────────── non-deterministic
sees reply ◀───────────── platform send
(conversation may or may not be project-scoped)

After

User                      Archon
────                      ──────
sends "/setproject my-app" ──▶ deterministic command detected
                               resolveCodebaseName("my-app", codebases)
                               4-tier: exact → case-insensitive → prefix → substring
                               updateConversation(convId, { codebase_id, cwd })
sees "Project set to **my-app**\nWorking directory: /path" ◀──
(conversation is now project-scoped; all subsequent messages use that context)

Architecture Diagram

Before

handleMessage
  │
  ├── deterministicCommands: [help, status, reset, workflow,
  │                           register-project, update-project,
  │                           remove-project, commands, init, worktree]
  │
  └── (no setproject handler)

After

handleMessage
  │
  ├── deterministicCommands: [help, status, reset, workflow,
  │                           register-project, update-project,
  │   [~]                     remove-project, setproject,      ← new
  │                           commands, init, worktree]
  │
  ├── [+] resolveCodebaseName(name, codebases)   orchestrator-agent.ts
  │         tier1: exact
  │         tier2: case-insensitive
  │         tier3: prefix (startsWith)
  │         tier4: substring (includes)
  │
  ├── [+] handleSetProject(message, conversationId)
  │         → codebaseDb.listCodebases()
  │         → resolveCodebaseName(...)
  │         → db.updateConversation({ codebase_id, cwd })
  │         → "Project set to **name**"
  │
  └── command-handler.ts /help text [~] +1 line under Projects

Connection inventory:

Label Snapshot

• Risk: risk: low
• Size: size: S
• Scope: core
• Module: core:orchestrator, core:command-handler

Change Metadata

• Change type: feature
• Primary scope: core

Linked Issue

• Closes feat: /setproject command to bind codebase to conversation #1044
• Related refactor(orchestrator): retire the /invoke-workflow text-scan router → one composable run-management primitive + per-adapter project binding #1886 (project-binding primitive, server half)

Validation Evidence (required)

bun run validate

check:bundled      ✅  (36 commands, 20 workflows — up to date)
check:bundled-skill ✅  (23 files across 2 skills — up to date)
check:bundled-schema ✅  (up to date)
type-check         ✅  No errors (all 10 packages)
lint               ✅  0 errors, 0 warnings (--max-warnings 0)
format:check       ✅  All files formatted
tests              ✅  All pass — 0 failed
  @archon/core       310 pass (incl. 8 new /setproject tests)
  @archon/workflows  436 pass
  @archon/adapters   205 pass
  @archon/providers   61 pass
  @archon/isolation   36 pass
  + all other packages green

• Evidence provided: full bun run validate output, all 7 checks EXIT=0
• No commands skipped.

Security Impact (required)

• New permissions/capabilities? No — reads existing codebases (already accessible to the conversation), writes codebase_id/cwd on the same conversation row the user already owns.
• New external network calls? No
• Secrets/tokens handling changed? No
• File system access scope changed? No

Compatibility / Migration

• Backward compatible? Yes — purely additive; /setproject is a new command that didn't exist before.
• Config/env changes? No
• Database migration needed? No — updateConversation writes to existing columns (codebase_id, cwd) already present in the schema.

Human Verification (required)

What was personally validated beyond CI:

• Verified scenarios:
  • /setproject my-app (exact match) → updateConversation called with correct codebase_id + cwd
  • /setproject MY-APP (case-insensitive) → resolves to canonical-cased codebase
  • /setproject my-w (prefix) → resolves to my-website
  • /setproject api (substring) → resolves to archon-my-api
  • /setproject app with app-backend + app-frontend registered → ambiguity message, no DB write
  • /setproject nonexistent → not-found message listing registered projects
  • /setproject (no args) → usage message, no DB write
  • /setproject with no registered codebases → not-found message with /register-project hint
• Edge cases checked: multi-word quoted names (/setproject "my app"), ambiguity at each resolution tier
• What was not verified: live end-to-end via curl against a running server (unit tests cover all paths; the dispatch path is identical to update-project and remove-project which are already live-tested in the codebase)

Side Effects / Blast Radius (required)

• Affected subsystems/workflows: @archon/core only — orchestrator dispatch and command-handler help text.
• Potential unintended effects: Substring matching could bind to an unintended project if a search string is very short (e.g., /setproject a with many projects starting with "a"). This is the same trade-off made by resolveWorkflowName and is mitigated by the ambiguity check — multiple matches at any tier return an error instead of silently picking one.
• Guardrails: Ambiguity detection throws per-tier; the error message lists all candidates so the user can disambiguate with a more specific name.

Rollback Plan (required)

• Fast rollback command/path: Revert the single commit (git revert bd651c1d) — the change is contained to 3 files, all additive.
• Feature flags or config toggles: None — the command is always available once merged.
• Observable failure symptoms: /setproject returns an error message to the user (never panics); worst case is a no-op if updateConversation fails (logged as project.setproject_completed absent from logs).

Risks and Mitigations

• Risk: Substring tier binds to unexpected project on very short input (e.g., /setproject e).
  • Mitigation: Ambiguity detection catches the multi-match case and returns a candidate list. Single-match substring bind is intentional (same policy as workflow name resolution). Users can always rebind with a more specific name.

Summary by CodeRabbit

• New Features

  • Introduced /setproject <name> command to bind conversations to registered projects with flexible name matching.

• Documentation

  • Updated command reference to include the new project-binding command.