@appchy/jarvis 0.1.36 → 0.1.39

package/harness/assets/domains/support.md

@@ -0,0 +1,45 @@
+---
+type: domain
+id: support
+---
+
+# Support — how users get unblocked
+
+## What belongs here
+
+Durable calls about **the stuck user** — what a failure must tell them, what
+diagnostics exist, what self-service looks like, how something is escalated, and what
+we promise about responsiveness.
+
+The reason this is its own domain rather than a corner of operations: operations keeps
+the *system* healthy, and a system can be perfectly healthy while a user is
+completely stuck. An error message that is accurate and useless is not an
+availability problem.
+
+Its neighbours: [`operations/`](../operations/README.md) owns the running system.
+[`product/`](../product/README.md) owns what the behaviour should have been.
+[`design/`](../design/README.md) owns the wording and shape of what they see.
+
+**Often empty in a young repo, and it ships anyway** — see the note in
+[`security/`](../security/README.md).
+
+## Non-goals
+
+- **Whether the system is up.** `operations/`.
+- **What the feature should do.** `product/`.
+- **A single error message's copy.** `design/` owns tone; the rule about what a failure must always disclose belongs here.
+- **One user's ticket.** Not durable direction.
+
+## Rules
+
+<!-- A durable rule lives in the domain that owns its KIND of call. Shape:
+
+     ### <id> — the rule, in one line
+     enforced_by: the check that catches a violation — a command, a test, a lint
+
+     `enforced_by: judgement` is legal where a person really must decide, and is
+     counted separately rather than treated as enforcement. An empty one is a wish.
+
+     This section is EMPTY ON PURPOSE in a fresh repo. Do not seed it with invented
+     rules to make the domain look occupied — an empty domain is a signpost saying
+     where a call will go when you make one. -->

package/harness/assets/epic-template.md

@@ -0,0 +1,85 @@
+---
+type: epic
+created: {{CREATED}}
+updated: {{CREATED}}
+covers: {{COVERS}}
+owner: {{OWNER}}
+continues: {{CONTINUES}}
+---
+
+# {{TITLE}}
+
+<!-- An EPIC is the coherent goal you plan TOGETHER, and the folder that holds
+     the tasks delivering it. It is TEMPORARY by definition — `work.py release`
+     removes this file, because how the work was planned stops being true the
+     moment it ships. The folder stays as the grouping of what shipped; git
+     holds this text.
+
+     EPIC ⟂ FEATURE — the split that stops two overlapping groupings:
+       a FEATURE is permanent (the WHAT: B-nn, AC-nn, state:) and lives in
+       work/product/<feature>.md;
+       an EPIC is temporary (the HOW-NOW: the work moving one or more features
+       in one release). An epic MAY span features — that is precisely why it is
+       not a per-feature slice.
+
+     `covers:` names the feature acceptance criteria this epic moves, each
+     FEATURE-QUALIFIED (`profiles/AC-03`), because the span is the point. An
+     epic with no `covers:` is a lint: work that moves no stated criterion is
+     work nobody can tell is finished.
+
+     `owner:` is the ONE exemption from that, and it is not an escape hatch.
+     Some epics genuinely move no product criterion — a trailer, a test harness,
+     a migration — because nothing a user can do changes. Those answer to an
+     ORG-DOMAIN (`commercial`, `quality`, `operations`, …), and a domain hosts
+     rules rather than `AC-nn`, so there is nothing for `covers:` to name and the
+     lint could only be satisfied by claiming criteria the epic does not move.
+     Naming the domain here IS the stated finish line. It is checked: an `owner:`
+     that resolves to no domain exempts nothing. An epic owned by a FEATURE has
+     criteria available and is still expected to name them. -->
+
+## Goal
+
+<!-- What a user can newly do when this epic lands — one paragraph, product
+     language. Not a task list; the tasks are the folders beside this file. -->
+
+## Plan
+
+<!-- THE DESIGN. Written ONCE, here, for the whole goal — before the tasks are
+     cut — and NOT restated in any task. This is the entire reason the tier
+     exists: a task then EXECUTES, it does not re-analyse the system.
+
+     So the expensive thinking happens here exactly once:
+       - As-found — how the in-scope code works today, `path:line`, confirmed
+         by the blast-radius sweep. The blast-radius grind runs ONCE for the goal, not per task.
+       - Architecture — the target shape, the shared seams every task builds
+         against, and the alternatives weighed.
+       - The rules that constrain it — `work.py rules --task <t>` over
+         the union of the tasks' `code` regions; cite them so no task trips one.
+       - Slices — the task list, in landing order, with what each depends on.
+         Each cuts DOWN through every layer it needs and is shippable alone.
+       - The forward-compat pass (SKILL.md obligation 3) — run for the goal.
+
+     Link `path:line`; never paste code. Budget: As-found ≤40 lines,
+     Architecture ≤80 — the same caps a plan.md had, because this replaced it.
+
+     A task gets its own plan.md ONLY when pickup surfaces a call this document
+     did not settle — and that is a GAP here. Settle it and write it back up, so
+     the next task inherits the answer instead of re-deriving it too. -->
+
+## Governance this implies
+
+<!-- PLAN-THEN-APPLY. `work/product/**`, `work/architecture/**` and
+     `work/quality/**` describe WHAT IS TRUE NOW — never a proposal. So the
+     domain-doc edits this epic will make are STATED HERE and applied when the
+     work lands: with the code, or not at all.
+
+     One line each, naming the owner file and the change. e.g.
+       - product/profiles.md — AC-09..AC-11 added for the org tier
+       - architecture/<system>.md — <id>: a principal is a person
+         OR an organization
+     If this epic implies no governance change, say so explicitly. -->
+
+## Non-goals
+
+<!-- What this epic deliberately leaves for later, so its boundary can't creep
+     into the next release. One line each. -->

package/harness/assets/feature-template.md

@@ -0,0 +1,86 @@
+---
+type: feature
+state: {{STATE}}
+# depends_on: [other-feature]   # optional — an enabler feature this one needs
+                                # first; a bare <feature>, existence-lint only
+log:
+  - {{DATE}} {{STATE}} (created)
+---
+
+<!-- Naming: title this feature's folder as the OUTCOME the user gets, in plain
+     language — not the implementation, not a codename. If state is `idea`,
+     name it as the user's PROBLEM instead (e.g. `slow-onboarding`, not
+     `add-quickstart-wizard`) — rename once it graduates past idea. Granularity:
+     one feature = the smallest thing you'd ship and tell a user about on its
+     own; needs "and" three times or several pieces must ship together first →
+     split it or call it what it is, an epic, and give each shippable slice its
+     own `<feature>.md`.
+
+     `state`: idea | defined | building | shipped | retired — the durable
+     lifecycle, EVIDENCE-DERIVED (see SKILL.md §Feature state), not a mood:
+       idea      — the feature exists but has open product questions
+       defined   — Problem + Stories + Behaviour + Acceptance criteria complete
+       building  — at least one in-progress task targets it (owner: link)
+       shipped   — every in-scope AC has passing evidence + a release reference
+       retired   — a durable product rule says the behaviour is gone
+
+     `log`: the state TIMELINE — append one dated line per state transition,
+     newest last, with the evidence in parentheses (the task that flipped it,
+     the founder review, the release ref). Re-openings are transitions too:
+     adding new B-/AC- items to a defined/shipped feature appends a line
+     (e.g. `2026-08-02 defined (re-opened: AC-08 added)`) so the current
+     standing is always visible. Never rewrite old lines.
+
+     THIS FILE IS THE DURABLE SOURCE OF TRUTH for what the app should do. It is
+     independent of the code: if the code disagrees, the code is what's wrong
+     (SKILL.md §The spec may say the code is wrong). Product language only —
+     no file paths, no code. -->
+
+## Problem
+
+<!-- What's wrong, or what's needed — in product language. No file paths, no code. -->
+
+## Stories
+
+<!-- The value/context lens — NOT the container. A user story frames actor +
+     goal + value; a job story frames situation + motivation + outcome. Pick
+     whichever fits; each story points at the behaviour rules / acceptance
+     criteria it frames (by id). One or a few — this is intent, not a backlog. -->
+
+As a <role>, I want <capability>, so that <outcome>.  → B-01, AC-01
+<!-- or: When <situation>, I want <motivation>, so I can <outcome>.  → B-02 -->
+
+## Behaviour
+
+<!-- B-nn: observable rules — what the app DOES, phrased as observable outcomes
+     independent of how it's built. These are the durable "what it should do"
+     that buggy code cannot redefine. A wireframe (this feature's own
+     wireframes/ folder, via the artifact-design skill) is linked here once one
+     exists — link it, don't restate it. IDs are unique within THIS feature. -->
+
+- B-01: <an observable rule>
+
+## Acceptance criteria
+
+<!-- AC-nn: checkable conditions that bound "done" — observable input/condition
+     → observable output, including failure and edge behaviour. Plain IDed
+     bullets by default; use Given/When/Then ONLY where a gnarly multi-branch
+     rule genuinely earns it (ceremony everywhere ossifies — Cucumber's own
+     warning). These are the TRACE UNIT: a task's `owner:` cites the AC ids it
+     implements, and a test declares them with `covers("<feature>/AC-nn")` or a
+     Playwright `{ tag: ["@<feature>/AC-nn"] }` — never a comment, which would go on
+     claiming a criterion after the test is renamed or deleted. IDs unique within
+     this feature; never reuse an id after it ships. -->
+
+- [ ] AC-01: <observable condition → observable outcome (+ failure/edge)>
+
+## Non-goals
+
+<!-- What this feature explicitly does NOT do — bounds the spec so scope can't
+     silently creep. One line each. Omit the heading only if genuinely none. -->
+
+- <a thing this feature deliberately doesn't do>
+
+<!-- No `tasks:` list — which tasks serve this feature is always a query over
+     task.md's `owner:` field, never hand-maintained. Links out (roadmap
+     placement, tests, shipped release) go inline where relevant, as pointers. -->

package/harness/assets/handoff-template.md

@@ -0,0 +1,26 @@
+# handoff — {{TITLE}}
+
+<!-- The live session brief — the one file a fresh session reads to know where
+     things stand. HARD CAP 80 lines: when over, move durable facts into
+     plan.md / the owning domain's rules and drop the oldest log entries. -->
+
+**Status:** <one line — where the task is right now. The ONLY home for status.>
+**NEXT:** <one line — the single next action to take.>
+
+## Read order
+
+<!-- The files a cold session reads, in order. e.g.
+     task.md → plan.md → the rules its domain owns → wireframes/ui.md -->
+
+## Log
+
+<!-- Dated, LATEST FIRST. The top line is always the freshest truth.
+     ≤3 lines per entry. Pruning removes from the bottom. -->
+
+- {{CREATED}}  <what happened / what this session set up>
+
+## Decisions
+
+<!-- Small, task-local calls as plain bullets. A durable decision is promoted
+     to the domain that owns it with the next free number, and reduced HERE to a
+     pointer: `<id>: <title>`. Rationale never lives in two places. -->

package/harness/assets/task-template.md

@@ -0,0 +1,38 @@
+---
+priority: {{PRIORITY}}
+depends_on: {{DEPENDS_ON}}
+created: {{CREATED}}
+updated: {{CREATED}}
+# `sessions:` and `completed:` are added automatically by work.py — never written by hand.
+---
+
+# {{TITLE}}
+
+## Problem
+
+<!-- What is wrong, or what is needed. Enough to start cold with no prior
+     conversation — one or two paragraphs. -->
+
+## Context & findings
+
+<!-- Investigation notes: root cause, relevant files as path:line, what was
+     ruled out. Leave empty until investigated. -->
+
+## Acceptance criteria
+
+- [ ] <!-- A concrete, checkable outcome. Tests trace back to these. -->
+
+## Open questions
+
+- <!-- An unknown to resolve when the task is picked up. -->
+
+<!-- There is NO length cap on this file. A brief is read by a session starting
+     cold, and the findings, dead ends and warnings that make that cheap are
+     exactly what a line budget deletes. Say what the next reader needs.
+
+     What a queued brief must NOT become is a competing PLAN: no `## Approach`
+     until one is agreed, no design or analysis until pickup (that lives in the
+     epic's §Plan, or plan.md in the rare case the task owns its own). Once a
+     plan.md exists, an `## Approach` here collapses to a single line:
+     `Approach → plan.md`. The artifact lint catches that by looking for the
+     FILES, which is the failure a length rule was only ever a proxy for. -->

package/harness/assets/version-template.md

@@ -0,0 +1,43 @@
+---
+created: {{CREATED}}
+updated: {{CREATED}}
+order: {{ORDER}}
+outcome: {{OUTCOME}}
+start: {{START}}
+end: {{END}}
+target: {{TARGET}}
+---
+
+# {{TITLE}}
+
+<!-- A VERSION IS A RELEASE. One rule follows from that and it is enforced: it
+     states a user-visible `outcome:` — one line on what someone can newly DO when
+     it ships. If you cannot say that, this is an epic, not a release.
+
+     KEEP IT SMALL. A cut should finish in days, not months. Several may be open
+     at once and the sequencing is yours; what the harness will not do is let a
+     version close with unfinished work in it, so a cut that grows past what you
+     can finish is a cut that never closes.
+
+     Its EPICS are the folders beside this file — each the coherent goal it
+     planned together. They are removed at release; this file is the permanent
+     record. -->
+
+## Goal
+
+<!-- The capability this release delivers — one or two paragraphs. The
+     user-facing "what's new" the version answers, not a task list. Expands the
+     one-line `outcome:` above; never contradicts it. -->
+
+## Scope
+
+<!-- The tasks committed to this cut. Use the README backlog table for the
+     live list — this section is for the narrative reasoning (why these slices
+     together make a coherent release). LINK the feature stories this cut
+     serves (work/product/**.md §Stories) — version stories.md is
+     retired; behaviour is owned per-feature, referenced here, never restated. -->
+
+## Release notes
+
+<!-- The shipping summary the user reads when the version ships. Drafted as the
+     cut is decided; finalised at `work.py release`. -->

package/harness/harness/__init__.py

@@ -0,0 +1,7 @@
+"""The /work harness, split by noun — one module per command noun.
+
+The CLI entry is `work.py`, which only dispatches. `tree`, `frontmatter`,
+`model` and `registry` are the reusable layer; `lint`, `align` and `generate`
+produce the derived facts; the rest are one module per command noun.
+Governed by `work/architecture/harness.md`.
+"""