@engineeros/connector 0.23.0 → 0.26.0

package/README.md

@@ -28,13 +28,15 @@ Connect a local Codex CLI workspace to EngineerOS through an outbound WebSocket.
 
 ## Agent roles and skills
 
-The selected ACP or Codex agent is the execution engine. EngineerOS chooses a provider-neutral role for each activity and the connector injects only that role's bundled skill:
-
-- `research` uses `codebase-research` with read-only access for questions.
-- `assessment` uses `assessment-editing` to inspect source without changing it and edit only the assigned assessment Markdown document.
-- `planning` uses `change-planning` with read-only access for shaping, specifications, architecture, and design work.
-- `implementation` uses `goal-execution` with workspace-write access only for a registered Goal.
-- `verification` uses `change-verification` with read-only access for artifact review and independent Goal proof.
+The selected ACP or Codex agent is the execution engine. EngineerOS chooses a provider-neutral role for each activity and the connector injects exactly one bundled skill:
+
+- `research` uses `project-research` to answer questions from observed project evidence.
+- `assessment` uses the internal `assessment-maintenance` skill to inspect source without changing it and edit only the assigned assessment Markdown document.
+- `planning` remains read-only and uses one server-selected skill: `product-discovery`, `experience-design`, `solution-design`, `requirements-and-acceptance`, or `delivery-planning`. Product discovery covers both intent discovery and capability shaping; delivery planning covers accepted greenfield slices and brownfield changes.
+- `implementation` uses `implementation` with workspace-write access only for a registered Goal.
+- `verification` uses `independent-verification` with read-only access for artifact review and independent Goal proof.
+
+This is intentionally a small executable catalog. Skills for hypothetical release, quality, or agent-workflow phases are not advertised until EngineerOS has a workflow that can invoke them. Harness-wide access, evidence, clarification, and output rules remain outside skill bodies, so an assignment pays only for the specialized judgment it needs. Direct Codex runs also disable ambient skill instructions; ACP providers receive the selected EngineerOS skill in the assignment prompt rather than the rest of the catalog.
 
 The connector rejects a role whose access does not match the assignment before starting the agent. Role-specific sessions preserve useful context without mixing planning, research, implementation, or verification responsibilities. A shared interaction contract makes the Agent infer the current project situation, lead with the useful outcome, and suggest one concrete next activity only when it genuinely helps. User-visible responses refer neutrally to the Agent; provider and harness details remain operational metadata.
 
@@ -54,7 +56,29 @@ Every backend `422` content-validation response is returned to the stage agent w
 
 Assessment runs start by reporting whether an accepted assessment exists and how stale it is. Every assigned stage still runs against the current repository revision; durable reports do not contain a trustworthy dependency manifest, so the connector never presents an old section as newly inspected. Connector-owned files under `.engineeros` are ignored before drafts or context packs are created and therefore do not pollute repository change scans.
 
-After onboarding, every project prompt is routed to this connection. Copilot, shaping, planning, architecture, and experience generation use the connected agent subscription and workspace context. Interactive prompts run independently from assessments and Goal scheduling. Prompt runs are read-only; only an explicitly registered Goal Run receives workspace-write access. If the connector is offline, EngineerOS asks the user to reconnect instead of silently switching models.
+After onboarding, every project prompt is routed to this connection. Copilot, shaping, planning, architecture, and experience generation use the connected agent subscription and workspace context. Interactive prompts run independently from assessments and Goal scheduling. Prompt runs are read-only; only an explicitly registered Goal Run receives workspace-write access. If the connector is offline, EngineerOS asks the user to reconnect instead of silently switching models.
+
+Greenfield prompts also receive a bounded project-evidence manifest. EngineerOS normalizes uploaded text,
+PDF, DOCX, CSV, workbook, presentation, and image Sources, and the connector materializes normalized Markdown
+and available original attachments under an assignment-specific directory in `.engineeros/context/inputs/`.
+These files are connector-owned, ignored project
+context; the active coding agent reads them as untrusted evidence through ordinary file access. Only the most
+relevant Sources are included in each assignment. Normalized text is capped at one million characters and
+original attachments at 10 MB across the assignment so the WebSocket payload stays bounded; image, workbook,
+and presentation originals receive priority because their normalized text is only a descriptor. The connector
+removes the assignment directory after the Agent finishes.
+
+When material evidence or a user decision is missing, a generation Agent can return structured clarification
+questions instead of an artifact. EngineerOS stores and presents those questions, accepts free-text or newly
+uploaded evidence, and supplies answered clarifications when the same phase is retried. The connector does not
+hold a process or WebSocket request open while waiting for a user.
+
+The complete-product greenfield path performs that question review before each generation stage. After the user
+confirms the answers, connector `0.25.0` validates the Agent's complete structured Markdown bundle and atomically
+stores its files under `.engineeros/design/01-discovery` through `.engineeros/design/06-delivery`. Every stage has
+a manifest and remains directly editable by a human. Later stages read the approved earlier directories as their
+authoritative inputs. The planning Agent remains read-only: the connector, not the Agent process, owns the bounded
+local write, and an existing stage directory must be deleted explicitly before regeneration.
 
 Project prompts use resumable, role- and purpose-specific agent sessions. The connector keeps the external session identifiers in its local configuration, so Copilot and artifact conversations survive connector restarts. Changing the role, purpose, model, or reasoning effort starts a separate session. Goal implementation and verification remain isolated runs.
 
@@ -71,7 +95,7 @@ If a new pairing command is accidentally run from the same folder against the sa
 
 ## Run Goals
 
-Keep the connector online to receive Goals assigned from EngineerOS. Each Goal runs in an isolated worktree below `~/.engineeros/runs`. Cancellation stops the agent. The connector returns changed paths, a bounded diff, and the exact repository ZIP; a human still performs independent attestation.
+Keep the connector online to receive Goals assigned from EngineerOS. Each Goal runs in an isolated worktree below `~/.engineeros/runs` on a durable `engineeros/goal-<run-id>` branch. Cancellation stops the agent. The connector returns changed paths, a bounded diff, and the exact repository ZIP; a human still performs independent attestation. Accepted work fast-forwards into an unchanged clean connected branch, or cherry-picks onto a clean branch that advanced, then refreshes the workspace snapshot. Dirty or conflicting workspaces are never overwritten: the Goal branch remains available for explicit review and merge.
 
 During the writable implementation phase, Codex receives an authenticated EngineerOS MCP server automatically. It can list, read, create, update, reclassify, soft-delete, and materialize project artifacts into canonical Product records through the same repository boundary used by Copilot. The backend accepts those calls only while the assigned Goal is running. Read-only project prompts and the independent verification phase do not receive mutation tools.
 
@@ -79,13 +103,13 @@ During the writable implementation phase, Codex receives an authenticated Engine
 
 The connector keeps a local index for each workspace under `~/.engineeros/context/<connector id>/workspaces/`: file classifications, symbols, document headings, and import relationships for every safe file. Separating indexes by resolved workspace keeps the source checkout and concurrent Goal worktrees from replacing one another. An index is built at onboarding, refreshed incrementally from file digests when EngineerOS triggers a workspace refresh, and re-checked before every assignment.
 
-Every assignment prompt arrives with a bounded, task-ranked Markdown working set. It names the most relevant paths, symbol and heading locations, local dependencies, direct consumers, and candidate tests, followed by a pointer to the durable source map at `.engineeros/context/source-map.md`. The connector ranks from the assignment's focused context query, frozen Goal packet, assessment stage identity, or current project request as appropriate. It never pastes source-file contents into the prompt; the Agent reads deeper through the source map, the listed files, assessment sections, ordinary file tools, or the attached `engineeros_*` MCP tools. Ranking is structural and lexical, using indexed paths, symbols, summaries, and imports; it does not generate or store embeddings.
-
-Context preparation is a launch prerequisite for every role. The connector refreshes the correct workspace index, verifies that the source map exists, and stops before starting an agent with an actionable error when pairing identity, indexing, or map generation is unavailable. Resumed project sessions also receive a bounded `Session Memory` digest of relevant earlier turns in the same session, kept under `~/.engineeros/context/<connector id>/sessions/`, so follow-up prompts build on prior conclusions instead of re-deriving them. Entries carry a derived kind (fix, decision, change, or conclusion), and cross-session recall is stamped with its source session and last-active time.
-
-Every direct Codex assignment — project prompt, assessment, Goal implementation, and independent verification — receives the local read-only context MCP server with `engineeros_search`, `engineeros_outline`, `engineeros_read_symbol`, `engineeros_similar`, `engineeros_blast_radius`, and `engineeros_recall`. Registry-backed ACP adapters receive the same runtime-workspace server through `session/new` and `session/load`. Only a writable Goal implementation receives the authenticated EngineerOS artifact MCP server; project prompts, assessments, and verification never receive mutation tools. Custom ACP commands receive no injected servers because they have no registry MCP contract.
-
-After Goal implementation commits its isolated worktree change, the connector rebuilds context from that exact post-commit workspace before starting the independent verifier. Verification therefore receives the current task-ranked working set plus a bounded `Change Impact` section naming changed files, direct importers, and candidate tests rather than relying on the pre-change index. `engineeros_similar` helps the Agent extend existing functions, classes, and types instead of duplicating them. Stored symbol outlines omit literal constant values, MCP search responses are capped at one hundred files, and the index, source map, prompt context, and session memory remain on the local computer.
+Every assignment prompt arrives with a bounded, task-ranked Markdown working set. It names the most relevant paths, symbol and heading locations, local dependencies, direct consumers, and candidate tests, followed by a pointer to the durable source map at `.engineeros/context/source-map.md`. The connector ranks from the assignment's focused context query, frozen Goal packet, assessment stage identity, or current project request as appropriate. It never pastes source-file contents into the prompt; the Agent reads deeper through the source map, the listed files, assessment sections, ordinary file tools, or the attached `engineeros_*` MCP tools. Ranking is structural and lexical, using indexed paths, symbols, summaries, and imports; it does not generate or store embeddings.
+
+Context preparation is a launch prerequisite for every role. The connector refreshes the correct workspace index, verifies that the source map exists, and stops before starting an agent with an actionable error when pairing identity, indexing, or map generation is unavailable. Resumed project sessions also receive a bounded `Session Memory` digest of relevant earlier turns in the same session, kept under `~/.engineeros/context/<connector id>/sessions/`, so follow-up prompts build on prior conclusions instead of re-deriving them. Entries carry a derived kind (fix, decision, change, or conclusion), and cross-session recall is stamped with its source session and last-active time.
+
+Every direct Codex assignment — project prompt, assessment, Goal implementation, and independent verification — receives the local read-only context MCP server with `engineeros_search`, `engineeros_outline`, `engineeros_read_symbol`, `engineeros_similar`, `engineeros_blast_radius`, and `engineeros_recall`. Registry-backed ACP adapters receive the same runtime-workspace server through `session/new` and `session/load`. Only a writable Goal implementation receives the authenticated EngineerOS artifact MCP server; project prompts, assessments, and verification never receive mutation tools. Custom ACP commands receive no injected servers because they have no registry MCP contract.
+
+After Goal implementation commits its isolated worktree change, the connector rebuilds context from that exact post-commit workspace before starting the independent verifier. Verification therefore receives the current task-ranked working set plus a bounded `Change Impact` section naming changed files, direct importers, and candidate tests rather than relying on the pre-change index. `engineeros_similar` helps the Agent extend existing functions, classes, and types instead of duplicating them. Stored symbol outlines omit literal constant values, MCP search responses are capped at one hundred files, and the index, source map, prompt context, and session memory remain on the local computer.
 
 ## Requirements