@archme/cli 0.14.3 → 0.14.4

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:
@@ -21602,7 +21620,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 +23277,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.4",
   "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:98116f43f35fb99d4ea06e08440b17a5bfe1705f0c35542f22ac63134763ad43"
 }