Add CI gates, close out cycle 0006, and refine guidance

.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Run tests
+        run: npm test

.gitignore

@@ -3,3 +3,4 @@ dist/
 __pycache__/
 *.pyc
 .DS_Store
+.obsidian/

README.md

@@ -71,6 +71,7 @@ docs/
     legends/                        named domains
     retro/<cycle>/<task>.md         retrospectives
     graveyard/                      rejected ideas
+    guide.md                        operator advice and non-doctrinal practice notes
     process.md                      how cycles run
     release.md                      how releases work
   design/
@@ -246,18 +247,28 @@ in one sentence, the cycle is too big. Split it.
    localization, or agent-facing explainability, witness those paths
    too.
 
-5. **PR -> main** - review until merge.
-
-6. **Close** - merge. Retro in `docs/method/retro/<cycle>/`.
+5. **Close** - write the retro and witness packet on the branch.
 
    - Drift check (mandatory). Undocumented drift is the only true
      failure mode.
    - New debt to `bad-code/`.
    - Cool ideas to `cool-ideas/`.
    - Backlog maintenance.
 
+   Closing the cycle packet does not mean `main` has accepted it yet.
+   Review-stage visibility is not yet a repo-native METHOD query.
+   Branch and PR context carry that state for now.
+
+6. **PR / review** - review the full cycle packet until merge or
+   rejection.
+
+7. **Ship sync on `main`** - after merge, update repo-level ship
+   surfaces such as `docs/BEARING.md`, `CHANGELOG.md`, and release
+   notes when the cycle changes them.
+
    Releases happen when externally meaningful behavior changes. Not
-   every cycle is a release. Update CHANGELOG and README regardless.
+   every cycle is a release. Ship sync only happens on merged `main`
+   state, not branch-local closeout state.
 
 ### Disagreement at playback
 
@@ -279,10 +290,12 @@ does the witness answer the playback questions or not?
 
 ### Outcomes
 
-- **Hill met** - merge, close.
-- **Partial** - merge what is honest. Retro explains the gap.
+- **Hill met** - close the packet, review it, merge it, then ship sync.
+- **Partial** - close the packet honestly, merge only what is honest,
+  and let the retro explain the gap.
 - **Not met** - cycle still concludes. Write the retro. A failed
-  cycle with a good retro beats a successful one with no learnings.
+  cycle with a good retro beats a successful one with no learnings. A
+  failed cycle does not need to merge to end honestly.
 
 Every cycle ends with a retro. Success is not required.
 
@@ -299,7 +312,7 @@ ceremonies. The mechanism is passive legibility.
 If you can answer these questions by reading the repo, you do not need
 a standup:
 
-- What is everyone working on? -> `method status`
+- What is actively open in this workspace? -> `method status`
 - What is committed? -> each design doc names its sponsors and hill
 - What is next? -> `ls docs/method/backlog/asap/`
 - What failed and why? -> `ls docs/method/retro/`
@@ -308,6 +321,10 @@ a standup:
 If any of these are unclear, the docs are incomplete. Fix the docs,
 not the process.
 
+Review state is not yet part of METHOD's repo-native coordination
+surface. For now it rides on branch and PR context outside the core
+filesystem queries.
+
 ### BEARING.md
 
 A single living document at `docs/BEARING.md`. One page, updated at
@@ -322,9 +339,9 @@ cycle boundaries - not mid-cycle. It answers three questions:
 `BEARING.md` is a signpost, not a status report. It summarizes
 direction; it does not create commitments, replace backlog items, or
 record decisions that belong in design docs, retros, or the backlog.
-It is written by whoever closes a cycle. On a solo project, that is
-you. On a team, it is whoever merged last. No scheduling, no rotation,
-no process. It updates as a side effect of doing the work.
+It is updated during ship sync after merge. On a solo project, that is
+usually you. On a team, it is whoever merges last or owns the ship
+sync. No scheduling, no rotation, no process.
 
 If the bearing drifts without anyone noticing, that is the signal to
 talk - not a meeting, just a conversation. The drift itself is the
@@ -360,8 +377,9 @@ to resurrect something, you must address the note.
 idea -> inbox/ -> cool-ideas/ -> up-next/ -> asap/
   -> design/<cycle>/  (committed)
   -> RED -> GREEN -> playback (witness)
-  -> retro/<cycle>/
-  -> release (when meaningful)
+  -> retro/<cycle>/   (cycle packet closed)
+  -> PR/review -> main
+  -> ship sync (BEARING / CHANGELOG / release when meaningful)
       - or ->
   -> graveyard/
 ```
@@ -396,6 +414,18 @@ Core commands:
 | `method drift [cycle]` | Check active cycle playback questions against test descriptions. |
 | `method status` | Summarize backlog lanes, active cycles, and legend load. |
 
+Repo-local CI currently uses GitHub Actions as a host adapter through
+`.github/workflows/ci.yml`. The first cut stays narrow and explicit:
+
+```bash
+npm ci
+npm run build
+npm test
+```
+
+The workflow currently runs on `ubuntu-24.04` for Node `22`.
+That is repo truth for this host, not METHOD doctrine for every forge.
+
 METHOD may be used alongside other tools, but they are sidecars, not
 doctrine. If a repo uses GitHub pull requests and review bots, an
 operator may use a tool like Draft Punks Doghouse to inspect live

docs/design/0006-ci-gates/ci-gates.md

@@ -0,0 +1,122 @@
+# CI Gates
+
+Source backlog item: `docs/method/backlog/asap/PROCESS_ci-gates.md`
+Legend: PROCESS
+
+## Sponsors
+
+- Human: I can push a branch or open a PR and get automatic proof that
+  METHOD still builds and its tests still pass, without relying on
+  memory or local-only verification.
+- Agent: I can point to one committed CI workflow whose trigger
+  surface, runtime, install mode, and commands match the repo's actual
+  truth surfaces exactly.
+
+## Hill
+
+METHOD ships a minimal CI gate for this repo, implemented as a
+GitHub Actions workflow that runs install, build, and tests on `push`
+and `pull_request`, and documents that contract clearly in repo-visible
+files.
+
+## Playback Questions
+
+### Human
+
+- [ ] Can I inspect the repo and see which automated checks guard
+      pushes and PRs, without reading chat history or relying on
+      remembered local commands?
+- [ ] If CI fails, does the workflow name the failing step clearly
+      enough that I can reproduce it locally with the same commands?
+
+### Agent
+
+- [ ] Are the workflow triggers, Node version, dependency-install
+      strategy, and executed commands explicit in committed files rather
+      than hidden in GitHub settings or tool defaults?
+- [ ] Does the first cut stay narrow and deterministic by running only
+      the repo's current truth surfaces (`npm ci`, `npm run build`,
+      `npm test`) with stable exit behavior?
+
+## Accessibility and Assistive Reading
+
+- Linear truth / reduced-complexity posture: the workflow and docs
+  should read as plain text from top to bottom. Step names should be
+  concise and action-shaped so a failure is understandable without
+  badges, color, or GitHub UI chrome.
+- Non-visual or alternate-reading expectations: the repo should state
+  the CI commands and workflow path directly in prose so a screen-reader
+  user, terminal-only operator, or agent can reconstruct the contract
+  without parsing screenshots or badges.
+
+## Localization and Directionality
+
+- Locale / wording / formatting assumptions: first cut may use English
+  workflow names and status wording. Localization of CI messages is not
+  part of this cycle.
+- Logical direction / layout assumptions: the contract should rely on
+  textual step order and command names, not left/right layout or other
+  direction-bound presentation.
+
+## Agent Inspectability and Explainability
+
+- What must be explicit and deterministic for agents: the workflow file
+  path, triggers, Node version, cache/install behavior, and executed
+  commands must all be committed in the repo. There should be no hidden
+  logic in branch settings, local shell aliases, or chat-only policy.
+- What must be attributable, evidenced, or governed: playback and
+  closeout must be able to point to the workflow file, the commands it
+  runs, and the local reproduction path. This cycle may note required
+  GitHub settings, but it does not rely on hidden branch-protection
+  state as proof.
+
+## Non-goals
+
+- [ ] Adding linting, formatting, or broader quality gates beyond the
+      current build/test truth surfaces.
+- [ ] Adding release, publish, or package-version automation.
+- [ ] Adding a multi-OS or multi-version matrix. First cut should keep
+      one explicit supported runtime.
+- [ ] Generalizing CI across every forge or turning GitHub Actions into
+      METHOD doctrine. This cycle is a repo-local adapter for this repo.
+- [ ] Hardening CodeRabbit config or broader PR-review workflow policy.
+      Those remain separate backlog items.
+
+## Decisions To Make
+
+- Which Node version the workflow should run in for the first cut.
+  Final choice: run Node `22` only and align the repo support floor to
+  that decision.
+- Whether the workflow should run any METHOD-specific smoke command
+  beyond build/test, or whether `npm run build` and `npm test` are the
+  full first-cut contract.
+- How much of the CI policy should be documented in `README.md` and
+  `docs/BEARING.md` versus left implicit in the workflow file itself.
+
+## Backlog Context
+
+METHOD should not rely on a human remembering to run tests before
+push or merge. Add a minimal CI workflow that runs the repo's actual
+truth surfaces on `push` and `pull_request`: build, test, and any
+required docs or status checks that are supposed to stay green.
+
+Session context:
+
+- During PR review of the `drift-detector` cycle, CodeRabbit called out
+  the absence of CI as a contradiction: the repo claims strict review
+  and drift discipline, but there is no automated gate for `npm test`
+  or `npm run build`.
+- That critique is right. METHOD should make the passing state
+  reproducible and machine-checked, not dependent on operator memory.
+- This repo already has a `package-lock.json`, so the first cut can use
+  `npm ci` for deterministic dependency installation rather than
+  open-ended install behavior.
+
+What this surfaced:
+
+- CI is infrastructure truth, not optional decoration.
+- The first cut can stay narrow: build plus tests.
+- Later cycles can add stronger checks, but the repo should stop
+  pretending manual verification is enough for merge safety.
+- METHOD itself should stay forge-agnostic, but this repo can still use
+  GitHub Actions as its current host adapter.

docs/method/backlog/inbox/PROCESS_retro-conversational-closeout.md

@@ -0,0 +1,34 @@
+# Retro conversational closeout
+
+METHOD's `close` flow currently handles the mechanical part of a retro:
+create the retro doc, create `witness/`, and record the outcome. It
+does not yet help the human sponsor actually think through the
+retrospective or capture their side of the playback honestly.
+
+Add CLI tooling for the retro stage that prompts the human user for
+their input instead of dropping them into a blank markdown skeleton.
+The strongest version would not just ask one-shot questions; it would
+support a conversational back-and-forth with the agent so the retro can
+feel like a real structured retrospective rather than form fill.
+
+Questions this should answer:
+
+- What parts of the retro should be prompted versus still hand-written?
+- Should the CLI gather both sponsor viewpoints explicitly: human and
+  agent?
+- How should the tool preserve honesty instead of steering the user
+  toward "hill met" boilerplate?
+- What should happen when the conversation surfaces new debt, cool
+  ideas, or backlog maintenance actions?
+- Should the output be direct markdown, a draft witness artifact, or a
+  staged review step before files are written?
+- How much of this belongs in METHOD doctrine versus repo-local CLI UX?
+
+What this surfaced:
+
+- The current closeout flow is mechanically correct but emotionally a
+  little abrupt.
+- Retro quality depends too much on the operator being willing to write
+  from scratch after the command has already declared the cycle closed.
+- A structured human/agent exchange could make retros more honest and
+  more useful without turning METHOD into meeting theater.

docs/method/backlog/up-next/PROCESS_git-branch-workflow-policy.md

@@ -0,0 +1,48 @@
+# Git branch workflow policy
+
+METHOD should define a git branch naming and workflow policy that is
+clear enough for humans and agents to follow without improvising. Right
+now the repo has doctrine for cycles, backlog lanes, retros, and
+witnesses, but branch creation, branch naming, local `main` hygiene,
+push policy, and PR expectations are still implicit.
+
+Session context:
+
+- Recent work in `method` exposed repeated uncertainty around branch
+  handling: whether to work directly on `main`, when to branch for a
+  cycle, how to name PR branches versus cycle branches, whether backlog
+  triage belongs on a side branch, and when local `main` should be
+  synced or left alone.
+- External tool defaults also pushed their own assumptions into the
+  repo, such as draft PRs, title prefixes, and PR-oriented workflow
+  conventions that did not actually come from METHOD.
+- At the same time, the repo has a clear stance that METHOD is not a
+  GitHub workflow or a PR cockpit. So whatever policy exists should be
+  forge-agnostic at the core, with forge-aware adapters.
+
+Questions this policy should answer:
+
+- When should work happen directly on `main`, and when should it happen
+  on a branch?
+- Should active cycles default to branches named after the cycle, such
+  as `0006-ci-gates`, or is that optional?
+- What naming forms are valid for maintenance branches, backlog triage,
+  review follow-up, or one-off operator work?
+- What is the expected lifecycle for local `main` after PR merges?
+- When is a PR required, preferred, or unnecessary?
+- How should agents avoid silently importing external workflow
+  conventions that the repo did not choose?
+- How should this policy relate to optional sidecars like Draft Punks
+  Doghouse without making METHOD itself a forge-specific system?
+
+What this surfaced:
+
+- METHOD needs branch/workflow doctrine, not just filesystem doctrine.
+- The policy should distinguish cycle branches, temporary operator
+  branches, and direct-maintenance cases.
+- The policy should remain forge-agnostic at the core, even if a repo
+  uses GitHub or tools like Doghouse in practice.
+- A likely rule from recent practice: close the cycle packet on the
+  branch before review (design, tests, playback, retro, witness), then
+  do repo-level ship sync such as `BEARING.md` and `CHANGELOG.md` on
+  `main` after merge.