Merge pull request 'Architecture: the general scope and the new-project sequence (for M2.5)' (#104) from arch-general into main

Reviewed-on: dongar/nisse#104
Reviewed-by: Don Garrett <dgarrett@acm.org>

docs/Architecture.md

@@ -138,8 +138,15 @@ Everything in this part is used by every agent.
 |---|---|---|---|
 | **Duty** | A standing responsibility that produces work items | Watching for issues assigned to it (D1) | Scheduled checks, log monitoring, alert intake |
 | **Work item** | One effort, opened and eventually closed | A bug, feature or new project | Diagnosing a failure; making one change |
-| **Scope** | What a work item operates on; context that outlives it | A repository | A site and service |
+| **Scope** | What a work item operates on; context that outlives it | A repository, or `general` | A site and service, or `general` |
 
+- **`general` is the scope of conversation not (yet) about a project:** feasibility,
+  hardware, how something works. Each conversation is its own item, one per thread
+  (L5), so unrelated chats stay out of each other's context. It has no repository,
+  no build VM and no execution, so its context is the conversation and agent memory
+  (L6). It closes after a day idle, with a summary in its log; a later reply in its
+  thread starts a new item linked to it. If it turns into work, the work moves to a
+  project's item (D1).
 - **Sources of work items:** duties, the operator (always), and other agents. A
   request from another agent is an issue assigned to the receiving agent, and
   carries no authority of its own: the receiver applies its own rules.
@@ -277,9 +284,10 @@ thread is how the agent knows which item a message is about.
   ambiguous, so the agent asks which item rather than guessing. Any other message
   starts a new conversation, and the agent offers to continue an existing item if
   it clearly belongs there.
-- **Any conversation about work is a work item from its first message,** however
+- **Every conversation is a work item from its first message,** in the `general`
-  vague ("I'm having trouble with X…"). It may end with a project, an issue, or
+  scope until it is about a project (L1), however vague ("I'm having trouble with
-  just an answer.
+  X…"). Chit-chat is simply answered in its thread; only work gets a Gitea issue
+  (D1). It may end with a project, an issue, or just an answer.
 
 **What the operator says** is plain language, plus a small command vocabulary that
 works in every state: `status`, `stop`, `abandon`, `approve [rev-N]`, `go`, and
@@ -562,9 +570,10 @@ Work arrives as Gitea issues or conversation, and leaves as reviewed PRs.
   item's record. Only issues filed or assigned by allowlisted operators count (L11).
 - **Unassigned issues are backlog,** never work, though the agent will discuss them.
 - **Open Gitea dependencies make an issue blocked** (L1).
-- **Work that starts in conversation gets a record:** the agent opens an issue,
+- **Work that starts in conversation gets a record** once it is work on a project,
-  assigned to itself, that carries the work item's ID from the moment it is
+  not at its first message: the transcript already keeps the conversation. The
-  created. Intake ignores any issue carrying an ID, so a record is never taken for
+  agent opens an issue, assigned to itself, that carries the work item's ID from
+  the moment it is created. Intake ignores any issue carrying an ID, so a record is never taken for
   new work, even before the agent has stored the link. This is the only time the
   agent assigns itself.
 
@@ -588,12 +597,29 @@ mean, how it fits, its first step. Labels steer what happens next:
 - **A bug:** reproduce (ideally as a failing test), fix, verify, PR.
 - **A feature:** agree the design in conversation, write a build plan if it's longer
   than about one PR (D2), work through it as milestones (D4).
-- **A new project:** a conversation, however vague. If it becomes a project, the
+- **A new project** starts as a `general` conversation, however vague. Nothing
-  agent lists what it needs provisioned (a repository with protection and its own
+  needs Gitea before the repository exists: drafts live in the conversation (a
-  write access, a build VM, and its project entry, D8), which the operator
+  Markdown file in the thread if long).
-  provides (later `nisse-ops`, O6). It then opens a tracking issue ("implement the
+  1. **The proposal:** a name, what it's for, and the decisions provisioning
-  build plan") as the record, and the architecture lands in one or more PRs, then
+     depends on (toolchain, so the build VM template; services; secrets; egress).
-  the plan's milestones.
+     The operator agrees as to a restatement.
+  2. **A provisioning checklist** in the thread: a repository with protection, the
+     agent as a collaborator with write access, a build VM, and the project entry
+     (D8), given as configuration to add. The operator provides them (later
+     `nisse-ops`, O6).
+  3. **Verified, not assumed:** when the operator says done, the agent checks the
+     repository, a push to a branch, that protection refuses it on the default
+     branch (D4), and the build VM.
+  4. **The record:** a tracking issue ("implement the build plan") whose body is
+     what was decided, distilled, linking the conversation's item. The raw
+     conversation isn't carried into the project's context: it holds ideas that
+     were dropped, and the documents are what gets reviewed and what later work
+     reads.
+  5. **The architecture lands in one or more PRs,** treated as `design`, then the
+     plan's milestones.
+
+  `general` never gets a build VM: an experiment that needs one (does a library
+  parse this format?) is a reason to start the project for real.
 - **Progress** goes on the record issue: facts posted by the harness, prose by the
   agent when there's something to say.
 - **Finishing:** the last PR closes the issue on merge ("Closes #N"; earlier ones say
@@ -918,8 +944,6 @@ shared between agents.
 - **More than one active work item:** needs per-item serialisation, an inference
   scheduler and per-item intents. Build VMs and threads already separate workspaces
   and conversations.
-- **Whether pure conversations need an external record** (work on a repository
-  already has its issue).
 - **Stacked PRs:** starting a milestone before the previous one merges, after
   experience with waiting (D4).
 - **Build VM collection:** how long idle, and whether it needs the operator's word.

docs/Development-Plan.md

@@ -184,9 +184,12 @@ between milestones (D2, D4). End-to-end: a two-milestone feature.
 - Deferred: a milestone with no changes that wasn't expected to change code is
   still raised with the operator (D4).
 
-**M2.5 Conversations and new projects.** *Needs discussion.* Work started in
+**M2.5 Conversations and new projects.** *Needs discussion;* the design was agreed
+in this PR (`general` scope, L1, L5; the new-project sequence, D1). Work started in
 conversation, record issues carrying their item's ID, the new-project flow and its
-project entry (D1, D8, #29). End-to-end: a small new project.
+project entry (D1, D8, #29). After M1.4. End-to-end: a small new project, in a
+repository the test operator creates under its own account for the run and
+deletes afterwards.
 
 **M2.6 Roles and capability profiles.** *Pre-approved.* `driver`, `helper`,
 `expert`, `classifier` (L9); escalation triggers; delegation and `ask_expert` on the