@archme/cli 0.14.3 → 0.14.5

package/SKILL.md

@@ -166,10 +166,10 @@ code + writes a proposal, exactly like a build sub-agent, and never touches the
 user's code). Logging reuses the
 proposals surface, not a bespoke mechanism: a prose-only proposal (empty graph
 delta, `body` naming what's wrong, where by file:line/symbol, and why) under the
-project's standing **"Bugs" folder**, `stage: 'backlog'` so it parks until a human
-triages. The daemon injects the Bugs folder id for you; a manual scan
-finds-or-creates it (`search_proposals({ kind: 'folder', text: 'Bugs' })`, else
-`create_proposal({ kind: 'folder', title: 'Bugs' })`). Dedup by searching the
+project's standing **"Bugs found by ArchMe" folder**, `stage: 'backlog'` so it parks
+until a human triages. The daemon injects the folder id for you; a manual scan
+finds-or-creates it (`search_proposals({ kind: 'folder', text: 'Bugs found by ArchMe' })`,
+else `create_proposal({ kind: 'folder', title: 'Bugs found by ArchMe' })`). Dedup by searching the
 folder by title — the same standing bug is re-noticed on every commit. Keep the
 bar high (a few per run at most, code-review-worthy only); logging a bug is
 **orthogonal** to your architecture task — still call

package/dist/cli.js

@@ -15165,6 +15165,21 @@ var init_componentOrganization = __esm({
   }
 });
 
+// ../shared/componentDescription.ts
+var COMPONENT_DESCRIPTION_GUIDANCE;
+var init_componentDescription = __esm({
+  "../shared/componentDescription.ts"() {
+    COMPONENT_DESCRIPTION_GUIDANCE = `Component description:
+- **Say what the component is for, in general terms.** One to three sentences on its job in the system: why it exists, not how it works.
+  - Good: "Keeps each order's payment status in step with Stripe."
+  - Bad: "Receives the Stripe webhook, verifies the signature, looks up the order by payment intent, updates its status, retries on a conflict and emits order.paid."
+- **It is not a sequence.** Steps, their order, triggers, retries, timings and branches belong in a story's \`sequence\`. A change to how a flow runs is a sequence edit, never a description edit.
+- **It is not a data contract.** Fields, parameters, return shapes and columns belong in \`schema\`. A change to the data is a schema edit.
+- **Other detail stays out of the graph.** Caveats, derivations, constraints and DDL live in the code, which the component's anchors link to.
+- **Edit a description only when the component's job changes.** A fix or an internal change leaves it alone, and never rewrite an existing description just to restyle it: every edit lands in someone's diff.`;
+  }
+});
+
 // ../shared/scanPrompts.ts
 function buildStoryCoverageGate(opts) {
   const preWrite = opts.noChangeSignal ? `
@@ -15246,6 +15261,7 @@ var init_scanPrompts = __esm({
     init_sequenceWording();
     init_leafEndpoints();
     init_componentOrganization();
+    init_componentDescription();
     BUILD_METHODOLOGY = `You are a build sub-agent. You are part of a multi-agent system that builds a comprehensive visual architecture of a codebase \u2014 components, connections, and user stories that trace data flow end-to-end. Your role is to translate research findings into actual architecture: creating components backed by real code references, wiring connections between them, and building story sequence diagrams that trace how data flows through the system.
 
 # Rules
@@ -15320,6 +15336,8 @@ Component kind:
 
 ${COMPONENT_ORGANIZATION_GUIDANCE}
 
+${COMPONENT_DESCRIPTION_GUIDANCE}
+
 Component schema:
 - Defines the data contract for interface children (input/output components)
 - Compact format: { field: type, field?: type, field!: type, nested: { ... }, array: type[], ... }
@@ -15335,14 +15353,14 @@ Component schema:
   - "{ user: { id: string, name?: string }, roles: string[] }" - nested object and array
   - "{ auth: token, ... }" - allow additional fields
 - MUST be this compact STRING \u2014 never a JSON object. A whole-schema trailing "[]" ("{ ... }[]") means "an array of that shape".
-- SHAPE ONLY \u2014 no comments or prose. The string must START with "{" and END with "}" (or "}[]"). Do NOT append a "// ..." comment, and do NOT wrap it in prose (e.g. "TypeName (path): { ... }. Note: ..."). Any explanation \u2014 how a key is derived, what a field encodes, caveats \u2014 goes in the component description or context, never in schema. A schema with a trailing comment or surrounding prose is unparseable and is rejected on write (the ONE exception is schemaKind: "unstructured" \u2014 see below).
+- SHAPE ONLY \u2014 no comments or prose. The string must START with "{" and END with "}" (or "}[]"). Do NOT append a "// ..." comment, and do NOT wrap it in prose (e.g. "TypeName (path): { ... }. Note: ..."). Any explanation \u2014 how a key is derived, what a field encodes, caveats \u2014 stays out of schema and out of the description: the code holds it. A schema with a trailing comment or surrounding prose is unparseable and is rejected on write (the ONE exception is schemaKind: "unstructured" \u2014 see below).
 
 Data-store (table) schema:
 - For a persisted store (a DB table/collection), set schemaKind: "table" and schemaName (e.g. "cards") on the component, and tag key columns inline:
   - @pk : primary-key column (e.g. "id: uuid @pk")
   - @fk(target) : foreign-key column referencing target (e.g. "user_id?: uuid @fk(auth.users.id)")
 - Example: schemaKind: "table", schemaName: "cards", schema: "{ id: uuid @pk, user_id?: uuid @fk(auth.users.id), text: text, created_at: timestamptz }"
-- Keep DDL, RLS policies, and indexes OUT of schema \u2014 those are code (the component's anchored migration) or belong in the component description/context. The graph holds the column shape + keys only.
+- Keep DDL, RLS policies, and indexes OUT of schema \u2014 those are code (the component's anchored migration). The graph holds the column shape + keys only.
 
 Unstructured (freeform) schema:
 - STRONGLY PREFER "params" (a contract) or "table" (a store) whenever the data has ANY real field shape \u2014 decompose it into fields with types rather than dumping prose. Use schemaKind: "unstructured" ONLY for data that has no field shape to capture: binary blobs, uploaded/attached files, images/media, raw byte buffers, encoded/encrypted payloads, or a genuinely opaque third-party payload whose shape you can't or shouldn't enumerate.
@@ -15350,7 +15368,7 @@ Unstructured (freeform) schema:
 
 Pre-existing unparseable schema:
 - Legacy components can carry a schema that predates the shape-only rule \u2014 DDL ("id uuid PK, org_id uuid, ..."), a signature ("(a, b) -> c"), a JSON object, or prose. It is a capture defect, not a contract, and echoing it back rejects your whole write.
-- When a component you are ALREADY touching has one, repair it FIRST as a separate phase: "structural" write (set enables_change naming the diff edit it unblocks), then apply your diff edits on top. Decompose it into params/table fields and move the prose \u2014 constraints, CHECK enums, derivations, return types \u2014 into the component description.
+- When a component you are ALREADY touching has one, repair it FIRST as a separate phase: "structural" write (set enables_change naming the diff edit it unblocks), then apply your diff edits on top. Decompose it into params/table fields and drop the prose \u2014 constraints, CHECK enums, derivations, return types \u2014 which the code already holds.
 - Scope it to the components this change already touches. Do NOT go hunting for malformed schemas elsewhere in the graph; an unrelated backfill is rejected on the diff path.
 
 Component annotations:
@@ -15402,14 +15420,15 @@ var init_agentFeedback = __esm({
 
 // ../shared/bugReport.ts
 function buildBugReportGuidance(bugsFolderId) {
-  const folderMechanic = bugsFolderId ? `Bugs live under the project's standing "Bugs" folder, id \`${bugsFolderId}\`. Pass that id to the bug-validation sub-agent so it files each confirmed bug with \`create_proposal({ kind: 'proposal', parent_id: '${bugsFolderId}', stage: 'backlog', title: '<concise>', body: '<what/where/why>', about: { component: '<root.\u2026 path>' } })\`.` : `Bugs live under a standing "Bugs" folder. Have the bug-validation sub-agent resolve it once with \`search_proposals({ kind: 'folder', text: 'Bugs' })\`, create it with \`create_proposal({ kind: 'folder', title: 'Bugs' })\` if none exists, then file each confirmed bug with \`create_proposal({ kind: 'proposal', parent_id: '<Bugs folder id>', stage: 'backlog', title: '<concise>', body: '<what/where/why>', about: { component: '<root.\u2026 path>' } })\`.`;
+  const folderMechanic = bugsFolderId ? `Bugs live under the project's standing "${BUGS_FOLDER_TITLE}" folder, id \`${bugsFolderId}\`. Pass that id to the bug-validation sub-agent so it files each confirmed bug with \`create_proposal({ kind: 'proposal', parent_id: '${bugsFolderId}', stage: 'backlog', title: '<concise>', body: '<what/where/why>', about: { component: '<root.\u2026 path>' } })\`.` : `Bugs live under a standing "${BUGS_FOLDER_TITLE}" folder. Have the bug-validation sub-agent resolve it once with \`search_proposals({ kind: 'folder', text: '${BUGS_FOLDER_TITLE}' })\`, create it with \`create_proposal({ kind: 'folder', title: '${BUGS_FOLDER_TITLE}' })\` if none exists, then file each confirmed bug with \`create_proposal({ kind: 'proposal', parent_id: '<folder id>', stage: 'backlog', title: '<concise>', body: '<what/where/why>', about: { component: '<root.\u2026 path>' } })\`.`;
   return `${BUG_REPORT_CORE}
 
 ${folderMechanic}`;
 }
-var BUG_REPORT_CORE;
+var BUGS_FOLDER_TITLE, BUG_REPORT_CORE;
 var init_bugReport = __esm({
   "../shared/bugReport.ts"() {
+    BUGS_FOLDER_TITLE = "Bugs found by ArchMe";
     BUG_REPORT_CORE = "**Bugs you happen to notice.** Don't hunt for bugs \u2014 stay on the architecture task \u2014 but don't ignore an obvious, real one that surfaces while you read the code (a null-deref, a missing `await`, an unhandled error path, a broken invariant). Have any sub-agents you dispatch report a suspect back to you (a one-line `possible bug: <what> at <file:line>`) rather than filing it themselves. When suspects come back, dispatch ONE bug-validation sub-agent \u2014 it reads code and calls `create_proposal`, exactly like the build sub-agent, and never modifies the user's code \u2014 and have it: verify each suspect against the code, and for every one it confirms as a real defect, FILE it itself as a prose-only proposal (`create_proposal` with `kind: 'proposal'`, `stage: 'backlog'`, an empty graph delta, and a one-paragraph `body`: what is wrong, where by file:line or symbol, and why), `about` the component it lives in (`{ component: '<root.\u2026 path>' }` \u2014 find_components_for_paths maps the file to it), else the user story whose flow it breaks (`{ story: '<id>' }`). It skips anything it can't confirm, and searches the folder by title first to skip anything already logged. Keep the bar high \u2014 obvious, confirmed defects only, a few per run at most, never speculation, style, or a design opinion; record, never fix. Logging a bug is orthogonal to your architecture task and does NOT replace your completion signal \u2014 still call `update_architecture` or `report_no_change` exactly as you otherwise would.";
   }
 });
@@ -16014,17 +16033,17 @@ async function ensureBugsFolder(client, projectId) {
     return createdId;
   } catch (err4) {
     console.warn(
-      `[bugs-folder] could not resolve/create the "Bugs" folder for project ${projectId}; bug filing falls back to agent find-or-create:`,
+      `[bugs-folder] could not resolve/create the "${BUGS_FOLDER_TITLE}" folder for project ${projectId}; bug filing falls back to agent find-or-create:`,
       err4 instanceof Error ? err4.message : err4
     );
     return null;
   }
 }
-var BUGS_FOLDER_TITLE, BUGS_FOLDER_DESCRIPTION, cache;
+var BUGS_FOLDER_DESCRIPTION, cache;
 var init_bugsFolder = __esm({
   "src/daemon/bugsFolder.ts"() {
     "use strict";
-    BUGS_FOLDER_TITLE = "Bugs";
+    init_bugReport();
     BUGS_FOLDER_DESCRIPTION = "Bugs noticed by scan/diff agents in the code while updating the architecture. Prose-only proposals; humans triage.";
     cache = /* @__PURE__ */ new Map();
   }
@@ -21602,7 +21621,7 @@ ${PHASE_GUIDANCE}
 You MUST exit with one of two positive signals \u2014 never exit silently:
 
 - **Architectural change.** Call \`update_architecture\` (one or more times) with your edits. The write itself is the signal.
-- **No change.** If after reading the diff and the affected stories/components you determine nothing in the diagram needs to update, call \`report_no_change\` with a one-line \`reason\` (e.g. "doc-only diff", "test-only change covered by existing story"). This is REQUIRED \u2014 exiting without calling either tool is treated as a tool-surface failure and the job is retried.
+- **No change.** If after reading the diff and the affected stories/components you determine nothing in the diagram needs to update, call \`report_no_change\` with a one-line \`reason\` (e.g. "doc-only diff", "test-only change covered by existing story"). If the only edit you would make is to a component's \`description\`, that is no change either: call \`report_no_change\` instead of writing it. This is REQUIRED \u2014 exiting without calling either tool is treated as a tool-surface failure and the job is retried.
 
 ${walkthroughSection}## Feedback
 
@@ -23259,7 +23278,7 @@ Rules:
 A data-shape change with unchanged topology is still an architectural change \u2014 the same components can talk in the same order while the shape of the data on the wire changes. If this change adds, removes, or retypes a **DB column**, a **function/RPC parameter**, or a **response/return field**, update the \`schema\` of the affected storage component (table, RPC, queue, any persistence layer) and the **input/output interface children** the data flows through. Compact format: \`{ field: type, field?: type, field!: generated, arr: type[], ... }\`. For a **persisted table**, set \`schemaKind: "table"\` + \`schemaName\` on the component and tag key columns inline (\`id: uuid @pk\`, \`user_id?: uuid @fk(auth.users.id)\`); keep DDL, RLS policies, and indexes OUT of \`schema\` \u2014 those are code (the anchored migration). Match the code exactly \u2014 do NOT invent fields the code doesn't have; a \`schema\` more complete than the code can prove is over-claiming.
 
 ## Behaviour at a step
-A behaviour change with unchanged participants is still an architectural change: the same components talk in the same order, but what a step does or guarantees has changed (the caller's real IP now reaches the backend, a failed call is now retried, a limit is now enforced). Show it in the \`sequence\` of the story that draws that step \u2014 reword that arrow, or add a short Note at that step when no arrow can carry it (see Sequence wording). A component \`description\` edit on its own barely shows in review, so it does not stand in for the sequence edit.
+A behaviour change with unchanged participants is still an architectural change: the same components talk in the same order, but what a step does or guarantees has changed (the caller's real IP now reaches the backend, a failed call is now retried, a limit is now enforced). Show it in the \`sequence\` of the story that draws that step \u2014 reword that arrow, or add a short Note at that step when no arrow can carry it (see Sequence wording). A component \`description\` says what the component is for, not what its steps do (see Component description), so editing one does not stand in for the sequence edit.
 
 ## Draft Story Guidance
 \`draft: true\` is a transient build mechanic, not a deliverable: it skips sequence validation while a story is being assembled, and a parent's draft flag propagates to all descendants (suppressing \`autoCreateConnectionsFromStories\`). Feature-group parent stories that have real, sequenced children are NOT drafts. You may set it mid-run to defer validation while assembling a story, but finish the run with zero drafts you created or touched: give each a real sequence and set \`draft: false\`, or remove it. Pre-existing drafts you didn't touch are not yours to sweep.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archme/cli",
-  "version": "0.14.3",
+  "version": "0.14.5",
   "description": "Map your codebase into a living architecture diagram: run `archme init` in a repo to scan it, `archme daemon start` to keep it current on every commit.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",

package/sandbox-image.json

@@ -1,4 +1,4 @@
 {
   "image": "ghcr.io/architectme/archme-job",
-  "digest": "sha256:acd28e9e721e85bd167408354c33f94274abf486813eada75a65961ed9f2a36e"
+  "digest": "sha256:e8eb13bfe54b189ce4db730b977aa9089e32f0030276da2c1d8d50c94a15776e"
 }