ai4kanban 0.7.1 → 0.8.1

package/README.md

@@ -65,17 +65,12 @@ akb skill install    # add it, or bring an older copy up to date
 That writes one file into `.claude/skills/kanban/` (Claude Code) and
 `.agents/skills/kanban/` (Codex): `SKILL.md`, a short note telling a coding agent the board
 is here and that `akb` owns it. The board app does the same thing from a button:
-**Configuration → Setup**.
+**Configuration → General**.
 
 Nothing else is copied in. The flows ship inside the command (`akb guide`), so a newer
-command is newer flows in every project at once — and the command itself stays where npm put
-it, so a project's git history never carries 350 kB of it.
-
-An agent that finds no `akb` on the PATH doesn't stop: the note's first section says what to
-run instead — the copy in this project where there is one, and otherwise `npx --yes
-ai4kanban@<the version that wrote the note>`, pinned so the rules match the board. A run
-started from the app or the CLI is told the same thing in its own words, and `akb skill`
-says it to you at the moment the note lands.
+command is newer flows in every project at once, and a project's git history never carries
+350 kB of it. An agent that finds no `akb` on the PATH doesn't stop: the note names what to
+run instead, pinned to the version that wrote it so the rules match the board.
 
 ## Update
 
@@ -86,15 +81,11 @@ npm install -g ai4kanban@latest   # a newer command
 akb update                        # a repaired board, from the project root
 ```
 
-`akb update` refreshes a skill folder that is already there — it never adds one, since not
-having it is an ordinary state now — adds whatever an older release never wrote to the
-board, clears out what it no longer writes, and prints which version you moved from and to
-with a link to everything that changed in between. Your cards, config, and memory are never
-touched.
-
-It can't do the first line to itself — replacing the file that is running is how you get
-half a command — so it checks npm and names that line when it is behind, rather than
-reporting success a release late.
+`akb update` refreshes a skill folder that is already there — it never adds one — adds
+whatever an older release never wrote to the board, clears out what it no longer writes, and
+prints which version you moved from and to with a link to everything that changed in between.
+Your cards, config, and memory are never touched. It can't do the first line to itself, so it
+checks npm and names that line when it is behind.
 
 ## Put an agent to work
 
@@ -103,8 +94,10 @@ card can be built from a terminal, over ssh, or from a script, without a chat se
 without a browser.
 
 ```bash
-akb implement 12              # build the card
-akb refine 12                 # sharpen it until it is ready to build
+akb implement 12              # build the card, then review what was built
+akb review 12                 # judge the delivery in flight on it again
+akb refine 12                 # sharpen it; defaults to standard QA
+akb refine 12 --effort lightweight --print  # use the chosen effort inline
 akb create "add dark mode"    # write the card(s) for it
 akb propose                   # write the next tasks
 akb archive 12                # finish it
@@ -118,11 +111,10 @@ point at, and the command that closes the job.
 akb implement 12 --print      # the steps, for whoever is asking
 ```
 
-That is the mode for an agent already in a session: it does the job in the conversation
-it is already in, rather than paying for a second agent to do the job it is sitting there
-to do. Start a run when you want the work to happen on its own. `akb help runs` carries
-the whole rule, beside the commands it applies to. An agent working inside a run the board
-started always gets the printed flow, so a run can't spawn a copy of itself.
+That is the mode for an agent already in a session: it does the job where it is, rather than
+paying for a second agent to do it. Start a run when you want the work to happen on its own.
+An agent working inside a run always gets the printed flow, so a run can't spawn a copy of
+itself. `akb help runs` carries the whole rule.
 
 The run keeps working after the command returns. Watch it, or stop it, from anywhere —
 including from the board app, which drives its buttons through these same commands:
@@ -168,31 +160,19 @@ akb chat 12                   # the conversation so far
 akb chat 12 --clear           # forget it and start fresh
 ```
 
-Before opening a fresh conversation, `akb chat` ensures this repo has the kanban skill. The
-first prompt is only the skill invocation and your message: `/kanban …` for Claude Code,
-`$kanban …` for Codex, and `Use the kanban skill: …` for an agent without direct skill-call
-syntax. There is no second chat flow or copied board snapshot; the skill reads the current
-board when it needs it.
-
-The reply arrives as it is written, and the next message lands in the same session — the
-agent still has everything said before, so you can ask a follow-up without explaining your
-project again. Every message is its own command, so the conversation is picked up from any
-terminal and survives closing one. The board's conversation and each card's are separate,
-and both live under `docs/kanban/.chats/`, on your machine and out of git.
-
-From there, chat behaves exactly like using the kanban skill in your coding agent. The skill
-prints the board-specific flow and does the work in the conversation by default; ask for a
-background run when you want another agent to take it independently. If you explicitly say
-which way, that wins.
-
-A change to a card a run is already working on is refused, and the refusal names the card
-and what that run is doing — the same rule that keeps two runs off one card.
+Chat is the kanban skill in a persistent agent session — the first prompt is only the skill
+invocation and your message, and the skill reads the current board itself. It prints the
+board-specific flow and does the work in the conversation by default; ask for a background run
+when you want another agent to take it independently.
 
-A chat is still not a run: it never shows in `akb runs`, never holds a card, and never keeps
-a run off the card it is about.
+Every message is its own command, so a conversation is picked up from any terminal and
+survives closing one. The board's conversation and each card's are separate, both under
+`docs/kanban/.chats/`, on your machine and out of git.
 
-Only an agent whose command can take a second message into its own session can hold a
-conversation. On any other one, chat says so and names the agents that can.
+A chat is not a run: it never shows in `akb runs` and never holds a card. A change to a card a
+run is already working on is refused, and the refusal names the card and what that run is
+doing. Only an agent whose command can take a second message into its own session can hold a
+conversation; on any other, chat says so and names the agents that can.
 
 ## The manual
 
@@ -205,19 +185,17 @@ The flows are `akb guide`:
 ```bash
 akb guide                     # every flow, one line each
 akb guide board               # how the board works: card format, layout, memory
-akb guide refine              # one card, vague to ready
+akb guide qa-loop             # settle one card's planning gaps
+akb guide qa-lightweight      # short check for clear, localized work
 akb guide plan-release        # fill a release from its goal
 ```
 
-A printed flow already carries the ones its action needs, in full, so this is for the
-rest.
+A printed flow already carries the ones its action needs, in full, so this is for the rest.
 
-A run that writes or changes a card is followed by `akb refine` on that card, started as a
-run of its own once the first one ends — so `akb create "…"`, `akb revise`, `akb resolve`,
-`akb propose` and `akb plan-release` all come back with their cards refined. Archiving or
-rejecting a card does the same for every card it was blocking that now has nothing left in
-its way. Each one is an ordinary run: it shows in `akb runs`, has its own log, and
-`akb stop` ends it.
+A run that writes or changes a card is followed by `akb refine` on that card, as a run of its
+own — so `akb create`, `akb revise`, `akb resolve`, `akb propose` and `akb plan-release` all
+come back with their cards refined. Archiving or rejecting a card does the same for every card
+it was blocking that now has nothing left in its way.
 
 ## What it won't do
 

package/bin/ai4kanban.mjs

@@ -188,6 +188,13 @@ async function placeSkill(root, mode) {
   const result = installSkill(root, mode === 'update' ? 'present' : undefined, PROGRAM)
   for (const w of result.wrote) did.push(`${w.refreshed ? 'refreshed' : 'wrote'} ${w.path}/ — ${w.files} (${w.agent})`)
   for (const s of result.skipped) notes.push(`${s.path} — ${s.why}`)
+  // The commit guard (#324), which goes in wherever the skill does. The FIRST write says
+  // so, so a user who ran `akb update` for something else learns it is there before a
+  // commit refuses; a rewrite of the board's own copy is silent, the way a refresh is.
+  if (result.hook?.wrote && !result.hook.wrote.refreshed) {
+    did.push(`wrote ${result.hook.wrote.path} — refuses a commit on the branch a delivery is landing on (\`--no-verify\` gets past it)`)
+  }
+  if (result.hook?.note) notes.push(result.hook.note)
   // A project that has one agent's folder but not the other's. Update never writes a folder
   // that isn't there — a plugin install keeps the skill in a read-only cache, and a board
   // installed today has no folder at all until someone asks for one. Say the line that adds
@@ -227,14 +234,36 @@ function rescueSkillConfig(root, skillDir) {
 
 // ---- the board -------------------------------------------------------------
 
+// Run one board move against `root`.
+//
+// `--dir` is not optional here, even though the process already runs in that folder: with
+// nothing named, the rules WALK UP from the working directory to the nearest docs/kanban/
+// and work on that one. In a folder with no board of its own — every folder an install is
+// pointed at — the nearest board can be anywhere above it, up to the user's home. Naming
+// the folder is what keeps `install --dir X` from repairing somebody else's board and
+// leaving X untouched.
 function runKanban(rulesFile, root, args) {
-  const result = spawnSync(process.execPath, [rulesFile, ...args], {
+  const [move, ...rest] = args
+  const result = spawnSync(process.execPath, [rulesFile, move, '--dir', root, ...rest], {
     cwd: root,
     stdio: 'inherit',
   })
   if (result.status !== 0) fail(`\`kanban.mjs ${args.join(' ')}\` failed — nothing else was changed`)
 }
 
+// The nearest board strictly ABOVE `root`, when there is one. A second board underneath an
+// existing one is legal and occasionally meant, but it is almost never what someone who ran
+// `install` in a subfolder wanted, so it is said out loud.
+function boardAbove(root) {
+  let at = path.dirname(path.resolve(root))
+  for (;;) {
+    if (fs.existsSync(path.join(at, 'docs', 'kanban'))) return at
+    const up = path.dirname(at)
+    if (up === at) return null
+    at = up
+  }
+}
+
 // The repair steps an update has to run on a board written by an older version. Each one is
 // mechanical; anything with a choice in it becomes a note instead.
 async function repairBoard(rulesFile, root) {
@@ -332,12 +361,17 @@ function checkModules(board) {
 function cmdInstall(root, tracks) {
   say(`ai4kanban ${VERSION} — installing into ${root}`)
   say('')
+  const above = fs.existsSync(path.join(root, 'docs', 'kanban')) ? null : boardAbove(root)
+  if (above) {
+    notes.push(`there is already a board at ${above} — this makes a second one, and commands run here will find this one`)
+  }
   runKanban(builtRules(), root, ['init', ...tracks])
   sayNotes()
   say('')
   // Say what landed, so nobody goes looking for the flows in the repo. They ship with the
   // command; a project holds its own board and nothing else.
-  say('That is the board. Nothing was written outside docs/kanban/.')
+  say('That is the board, under docs/kanban/. The one line written outside it is `.akb/` in')
+  say('.gitignore, which keeps the folders a delivery works in out of git.')
   say('')
   say('To drive this board from your coding agent, add the skill — from the button in the')
   say('board UI (Configuration → Agent setup), or here:')
@@ -370,6 +404,7 @@ async function cmdSkill(root, mode) {
     say(`ai4kanban ${VERSION} — the coding agent skill in ${root}`)
     say('')
     for (const folder of state.folders) say(`  ${folder.path}/ — ${sayFolder(folder)} (${folder.agent})`)
+    await sayHookState(root)
     say('')
     if (!state.installed) say(`Not installed. \`${PROGRAM} skill install\` writes it, and so does the board UI's button.`)
     else if (state.outdated) say(`Older than this command. \`${PROGRAM} skill install\` brings it up to date.`)
@@ -411,6 +446,16 @@ async function sayPathState() {
   say(`    ${GET_LINE}`)
 }
 
+// Where the commit guard stands (#324), said next to the folders an agent reads. A project
+// that is not a git repository has no hook to have, and gets no line about one.
+async function sayHookState(root) {
+  const { readCommitHook, sayCommitHook } = await rules()
+  if (typeof readCommitHook !== 'function' || typeof sayCommitHook !== 'function') return
+  const hook = readCommitHook(root)
+  if (hook.state === 'no-git') return
+  say(`  ${hook.path} — ${sayCommitHook(hook.state)}`)
+}
+
 function sayFolder(folder) {
   if (folder.state === 'absent') return 'not installed'
   if (folder.state === 'linked') return 'a symlink into a source checkout — never written over'
@@ -534,7 +579,8 @@ ${INTRO}
   akb install [--tracks a,b,c]   scaffold docs/kanban/ — the board, and nothing else
   akb skill                      whether a coding agent can drive this board
   akb skill install              add the skill: SKILL.md into .claude/skills/kanban/
-                                 and .agents/skills/kanban/
+                                 and .agents/skills/kanban/, plus the commit guard in
+                                 .git/hooks/pre-commit
   akb skill refresh              rewrite a skill that is already here, and write none
                                  that isn't — how the note learns a new spelling of the
                                  command
@@ -568,8 +614,8 @@ Put an agent to work on the board:
   akb agent                      which agent runs them, and how it is set up
 
 A run keeps working after the command returns. Add \`--print\` to any of the first four and
-nothing starts: it prints what to do instead, filled in for this board — which is how an
-agent already in a session does the job itself rather than starting a second one.
+nothing starts: it prints what to do instead, filled in for this board — which is how the
+agent you are already talking to does the job itself rather than starting a run of its own.
 
 \`akb help runs\` is the whole of it — every command a coding agent may call, and when.
 \`akb agent\` is where you pick the agent, its model and its key.
@@ -626,6 +672,10 @@ async function cmdBoard(args) {
 // command line is the command's own.
 const RUN_COMMANDS = new Set([
   'implement',
+  // The two runs a delivery makes after its build (#302). The board starts each itself;
+  // typed by hand they put a stopped delivery back in motion.
+  'review',
+  'correct',
   'run',
   'refine',
   'resolve',
@@ -633,6 +683,9 @@ const RUN_COMMANDS = new Set([
   'create',
   'propose',
   'plan-release',
+  // Write a closed version's changelog into its summary file (#232) — the run the board
+  // UI's close starts, and the one a terminal close names.
+  'changelog',
   // Finish setting the board up (#173) — the steps that read the repo and think, as one
   // run. It is a run like the rest: the board UI's button starts exactly this.
   'setup',
@@ -647,7 +700,19 @@ const RUN_COMMANDS = new Set([
   'log',
   'stop',
   'resume',
+  // End the DELIVERY in flight on a card and hand the card back (#301). `stop` ends one
+  // run of it; this ends the job.
+  'cancel',
+  // Throw a delivery's worktree and branch away (#303). Cancel leaves them where they are;
+  // this is the only thing that removes one.
+  'discard',
+  // Sign off the tree a delivery would land (#308), on a board that requires it. It ends
+  // nothing and starts nothing — it lets a delivery already waiting carry on.
+  'approve',
   'agent',
+  // Which account this MACHINE is signed in to Cloud as (#326). Like `guide`, it needs no
+  // board: the sign-in belongs to the machine, not to any one project.
+  'cloud',
   // The board's flows, shipped with this command rather than copied into each project.
   'guide',
   // What a started run's watcher is spawned as. Never typed by a person.