@theodo/bernard 0.1.0-beta.0 → 0.1.0-beta.1

package/README.md

@@ -1,7 +1,7 @@
 # Bernard the taktician
 
 <p align="center">
-  <img src="docs/assets/bernard.svg" alt="Bernard the taktician, the hermit crab" width="180">
+  <img src="./docs/assets/bernard.svg" alt="Bernard the taktician, the hermit crab" width="180">
 </p>
 
 An agentic factory that takes a feature from its specification to pull requests ready for your team's review, for new builds and legacy migrations alike. Coding agents do the work, a fresh session for each step, along a pipeline that a state machine drives. By default, humans validate the specification and the plan, and review the pull requests. Each of these gates can instead decide on its own and log its decision, so a project goes fully autonomous once its quality holds.
@@ -25,7 +25,7 @@ Bernard keeps the two apart. The core holds the generic know-how, shared and ver
 1. **Legacy analysis** (migrations only). Automatic. It feeds the PRD.
 2. **PRD.** The factory drafts it, and the product manager reviews it in a pull request, like code.
 3. **Plan.** How to migrate the feature, or how to build it. Built in conversation with the developer, who validates it.
-4. **Tickets → implementation → validation → review → PR → green CI.** Automatic: the factory splits the plan into tickets, the smallest units it implements, and delivers each one along a graph of steps the project can reshape. Then the team reviews the PR, acts on its review and merges it. Each ticket starts from the feature's own branch, `feat/<feature>-<slug>`, named by its first step, and its PR targets it; the team merges the feature branch once its tickets are in. A ticket that depends on one not merged yet starts from its branch, so its PR stacks on the other.
+4. **Tickets → implementation → validation → review → PR → green CI.** Automatic: the factory splits the plan into tickets, the smallest units it implements, and delivers each one along a graph of steps the project can reshape. The factory opens one pull request per feature, from the feature's own branch, `feat/<feature>-<slug>`, named by its first step, to the base branch. A ticket whose graph has no gate after `pull-request` merges itself into the feature branch, with no PR of its own, so the change is reviewed once, in the feature's PR. A graph with a gate keeps the ticket's PR to the feature branch: the team reviews it, acts on its review and merges it, and a ticket that depends on one not merged yet starts from its branch, so its PR stacks on the other. The team merges the feature's PR once its tickets are in.
 
 A project chooses the steps before the tickets, and the policy of each gate, in [its config](docs/overlay.md#pipeline). [docs/pipeline.md](docs/pipeline.md) draws the default pipeline, a migration's, from the orchestrator's state machines.
 
@@ -36,16 +36,16 @@ What works today:
 - The orchestrator runs the whole pipeline above, and resumes a run from the records it commits in the project's repo.
 - `bernard status` shows the most recently active features and where each ticket stands, read from the records on the project's remote.
 - A run that waits on a human stalls with the command that answers it: `bernard resume --feature <slug>` with `--approve`, `--request-changes "<feedback>"`, `--retry` or `--answer <questionId>=<text>`, and `--ticket <id>` for a ticket. `bernard status` prints the same commands.
-- `bernard view` follows a project's runs live in the browser: each ticket's way through its graph of steps, every attempt and its session's log, and the machines, read from the project's telemetry.
-- The core ships the delivery steps: `implement`, `validate`, `code-review` with its three reviewers, `apply-review` and `pull-request`, which opens the pull request on GitHub and drives its CI green, and a `tickets` step that reports the feature as a single ticket.
+- A tracker port, with a Jira Cloud adapter: `bernard run --feature DATA-12` starts a feature from a Jira issue, and the issues of the feature and its tickets follow the run.
+- `bernard view` follows a project's runs live in the browser: each ticket's way through its graph of steps, every attempt and its session's log, and the machines, read from the project's telemetry. Next to it, under `/docs/`, it serves this documentation as a website, for the version the project pins.
+- The core ships the delivery steps: `implement`, `validate`, `code-review` with its three reviewers, `apply-review` and `pull-request`, which lands the ticket on the feature branch or opens its pull request, keeps the feature's pull request, on GitHub, GitLab or Azure DevOps with `bernard pull-request`, and drives its CI green, and a `tickets` step that reports the feature as a single ticket.
 - `bernard sync` renders the core and an overlay for Claude Code, Pi and GitHub Copilot.
-- `bernard init` writes a starter overlay for the project's forge, GitHub or Azure DevOps, whatever its tracker.
+- `bernard init` writes a starter overlay for the project's forge, GitHub, GitLab or Azure DevOps, whatever its tracker: the forge is `adapters.forge` in its config.
 - `bernard run` runs each step as a Claude Code or GitHub Copilot session, on your machine in a git worktree per ticket, or in a [Coder](https://coder.com/) workspace per ticket. The [demo](demo/README.md) delivers a feature end to end both ways.
 
 What is planned:
 
-- Core skills for the legacy analysis, the PRD and the migration plan, a `tickets` skill that splits the plan into several tickets, and the legacy tracers that map a legacy application ([#28](https://github.com/theodo-group/ai-mod-factory/issues/28)). Until then, a project writes them in its overlay or does them by hand, as the demo does.
-- A forge port, so that the core opens the pull requests on GitHub or Bitbucket ([#26](https://github.com/theodo-group/ai-mod-factory/issues/26)). Until then, the core's `pull-request` step is for GitHub, and a project on Azure DevOps overrides it, as the starter overlay does.
+- Core skills for the legacy analysis, the PRD and the migration plan, a `tickets` skill that splits the plan into several tickets, and the legacy tracers that map a legacy application ([#28](https://github.com/theodo-group/bernard/issues/28)). Until then, a project writes them in its overlay or does them by hand, as the demo does.
 - A Pi driver for `bernard run`.
 
 ## Install
@@ -72,12 +72,12 @@ Then adapt the factory to your project:
 
 ## Decisions
 
-Every structural decision is recorded, with the options it left out, as an ADR (architecture decision record) in [docs/adr/](docs/adr/). [CONTEXT.md](CONTEXT.md) defines the vocabulary, and [CONTRIBUTING.md](CONTRIBUTING.md#how-a-run-fits-together) shows how a run fits together.
+The factory's decisions are recorded, with the criteria and the options they weighed, as ADRs (architecture decision records) in [docs/adr/](docs/adr/). [CONTEXT.md](CONTEXT.md) defines the vocabulary, and [CONTRIBUTING.md](CONTRIBUTING.md#how-a-run-fits-together) shows how a run fits together.
 
 ## Layout
 
 ```
-ai-mod-factory/
+bernard/
 ├── core/                     # skills, agents and shared fragments, in a harness-neutral format
 ├── packages/
 │   ├── contracts/            # Zod schemas: overlay config, pipeline, skill frontmatter, step handoffs
@@ -88,13 +88,14 @@ ai-mod-factory/
 │   ├── harness-copilot/      # GitHub Copilot's native files, and its headless driver
 │   ├── telemetry/            # the telemetry port, and its default adapter: JSON lines on disk
 │   ├── viewer/               # the run viewer's page, and its server on the telemetry port
-│   └── cli/                  # bernard init | sync | pipeline | run | resume | status | view, and the runners
+│   ├── docs/                 # the documentation site: VitePress, on the markdown of this repo
+│   └── cli/                  # bernard init | sync | pipeline | run | resume | status | view, and the adapters
 ├── fixtures/                 # reference projects for the render tests, and a starter overlay per forge
 ├── demo/                     # a feature delivered end to end, on a local Coder or locally
-└── docs/                     # the guides, the pipeline and the ADRs
+└── docs/                     # the guides, the pipeline and the ADRs, which packages/docs renders
 ```
 
-Adapters have no folder of their own yet: the local and the Coder runners live in `packages/cli/src/runners/`, and the JSON lines telemetry next to its port in `packages/telemetry/`.
+The adapters live in `packages/cli/src/adapters/`, one folder per tool: `coder/` and `local/` for the runners, `jira/` for the tracker (ADR-0038). The ports, and the logic their adapters share, stay in `packages/cli/src/runners/` and `packages/cli/src/trackers/`. The JSON lines telemetry sits next to its port in `packages/telemetry/`.
 
 In a project:
 

package/core/README.md

@@ -89,6 +89,6 @@ On Claude Code, the tiers map to `haiku`, `sonnet` and `opus` unless the overlay
 ## Writing rules
 
 - Write in English. Text meant for deliverables is written in `{{project.language}}`.
-- Name no client, no project and no external tool. Tools go behind ports (ADR-0004), and project specifics go into slots. Amended by ADR-0036: the `pull-request` skill names GitHub's tool until the forge port.
+- Name no client, no project and no external tool. Tools go behind ports (ADR-0004), and project specifics go into slots.
 - Use no harness-specific syntax: no `$ARGUMENTS`, no `` !`cmd` `` injection, no `${CLAUDE_*}` variables.
 - Reference a skill's supporting files by their path relative to the skill folder.

package/core/agents/review-quality.md

@@ -2,7 +2,7 @@
 name: review-quality
 description: Quality reviewer of a change, run on a review bundle by the code-review skill. Judges whether the code looks like the codebase it lives in - its shape (module design, coupling, the documented architecture, ADRs and canonical patterns), the letter of the code style, and the code identifiers that denote domain concepts against the glossary's canonical terms - then writes a JSON report.
 tools: [read, grep, find, bash, write]
-model: balanced
+model: deep
 ---
 
 You are `review-quality`. You review one question at three altitudes: does this code look like the codebase it lives in? You judge the shape (module depth, coupling, information hiding, the documented architecture, the ADRs, the canonical patterns), the letter (every code-style rule the change touches), and the names (every code identifier that denotes a domain concept uses the glossary's canonical term).
@@ -23,24 +23,25 @@ Sources to start from: the architecture document, read whole, since structural j
 1. **The documented architecture.** Module and feature layout, layer boundaries, query and mutation patterns, routing, shared types, data access. A divergence is `major`, cited by section.
 2. **ADR conformance.** For every ADR whose subject the change touches, the implementation follows the decision. A violated decision is `major`, cited by file.
 3. **Canonical patterns.** A new file that a documented pattern or a reference implementation covers follows it. A near-duplicate of an existing pattern that ignores it is `major`.
-4. **Module depth and coupling.** A shallow module whose interface is as complex as its implementation; a leaked internal that forces every caller to know how it works; one concept spread across layers that should not know about each other.
+4. **Module depth and coupling.** A shallow module whose interface is as complex as its implementation; a leaked internal that forces every caller to know how it works; one concept spread across layers that should not know about each other. An adapter (code tied to one outside tool, under `src/adapters/<tool>/`) is imported only by the entry point that wires it, never by a capability nor by another adapter.
 5. **Wiring.** A component implemented but never registered where its reference implementation registers one.
+6. **One concept per file.** A file holds one concept, named by the file: its type, its schema and the functions acting on it. Flag an export whose noun does not match its file's (`formatDate` exported from `invoice.ts`), and a file that needs a section comment to separate two ideas. Utils files (small helpers, shared types) are exempt.
 
 ### Letter
 
-6. **Type discipline**, as the code style states it: no escape hatch from the type system, and the immutability and union types the style asks for.
-7. **Comments**, against the code style's rule on them. Narration, restated code, ticket tags and migration trails are the usual offenders; a non-obvious why (a hidden constraint, a subtle invariant, a documented workaround) is not.
-8. **The rest of the code style**, wherever the change touches it.
+7. **Type discipline**, as the code style states it: no escape hatch from the type system, and the immutability and union types the style asks for.
+8. **Comments**, against the code style's rule on them. Narration, restated code, ticket tags and migration trails are the usual offenders; a non-obvious why (a hidden constraint, a subtle invariant, a documented workaround) is not.
+9. **The rest of the code style**, wherever the change touches it.
 
 ### Naming
 
-9. **The canonical term, always.** A variable, function, type, field, file or folder that names a domain concept uses the glossary's term. A term the glossary lists as one to avoid is reported, cited by its entry.
-10. **A rejected name handed down by the plan is still rejected.** When the migration plan or a ticket spells out an identifier the glossary rejects, the code uses the glossary's term anyway: the plan is frozen, and the code is where corrections live.
-11. **Legacy artifact names are not domain terms.** Screen codes, legacy table names and program names name artifacts, not concepts. An identifier built from one is reported.
-12. **A layout position is not a name.** `leftTable`, `bottomBlock` or `panel2` say where something sits today, not what it is.
-13. **One concept, one name.** The same concept travels under a single name across the files of the change, even when two names would each be acceptable alone.
-14. **Vague words.** An identifier built on `data`, `info`, `item`, `result`, `payload`, `manager`, `helper` or `util`, or a function named `handle*` or `process*`, says that something exists, not what it is or does. When the glossary has a term for the concept, the identifier breaks the canonical term (criterion 9): `minor`, cited by the glossary entry. When only a more precise noun or verb fits, `nit`, with the name you propose. A local whose whole scope is three lines or fewer is fine: the reader sees what it holds. A vague word inside a glossary term is canonical, not vague: `stepResult` for a step result is the term `Step result`.
-15. **Abbreviations** that the glossary does not use itself.
+10. **The canonical term, always.** A variable, function, type, field, file or folder that names a domain concept uses the glossary's term. A term the glossary lists as one to avoid is reported, cited by its entry.
+11. **A rejected name handed down by the plan is still rejected.** When the migration plan or a ticket spells out an identifier the glossary rejects, the code uses the glossary's term anyway: the plan is frozen, and the code is where corrections live.
+12. **Legacy artifact names are not domain terms.** Screen codes, legacy table names and program names name artifacts, not concepts. An identifier built from one is reported.
+13. **A layout position is not a name.** `leftTable`, `bottomBlock` or `panel2` say where something sits today, not what it is.
+14. **One concept, one name.** The same concept travels under a single name across the files of the change, even when two names would each be acceptable alone.
+15. **Vague words.** An identifier built on `data`, `info`, `item`, `result`, `payload`, `manager`, `helper` or `util`, or a function named `handle*` or `process*`, says that something exists, not what it is or does. When the glossary has a term for the concept, the identifier breaks the canonical term (criterion 10): `minor`, cited by the glossary entry. When only a more precise noun or verb fits, `nit`, with the name you propose. A local whose whole scope is three lines or fewer is fine: the reader sees what it holds. A vague word inside a glossary term is canonical, not vague: `stepResult` for a step result is the term `Step result`.
+16. **Abbreviations** that the glossary does not use itself.
 {{/slot}}
 
 ## Not a quality finding

package/core/agents/review-security-bugs.md

@@ -2,7 +2,7 @@
 name: review-security-bugs
 description: Security, bug and performance reviewer of a change, run on a review bundle by the code-review skill. Judges server-side input validation, where authorization is enforced, injection, secrets, error leakage and personal data, and hunts concrete failures (absent values, boundaries, dates, numbers, state, error paths, concurrency) and measurable slowness, then writes a JSON report.
 tools: [read, grep, find, bash, write]
-model: balanced
+model: deep
 ---
 
 You are `review-security-bugs`. You review whether a change will leak, misbehave or be slow: its security (server-side input validation, where authorization is enforced, injection, secrets, what errors leak, personal data), its bugs, and its performance. Your categories: `security`, `bug` and `performance`.

package/core/agents/review-tests.md

@@ -2,7 +2,7 @@
 name: review-tests
 description: Test reviewer of a change, run on a review bundle by the code-review skill. Judges whether the tests the change ships are worth anything (tautologies, assertions, titles, exercised scenarios, cases that matter), then writes a JSON report.
 tools: [read, grep, find, bash, write]
-model: balanced
+model: deep
 ---
 
 You are `review-tests`. You review the tests a change ships, against the project's testing strategy: are they worth anything? That is your one dimension, and your category is `tests`.

package/core/coder/template/main.tf

@@ -103,7 +103,8 @@ resource "coder_agent" "main" {
   os   = "linux"
   dir  = "/home/node/work"
   env = {
-    PATH         = "/home/node/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+    # The bernard the project installs in .factory/ comes first: the pull-request skill runs `bernard pull-request`.
+    PATH         = "/home/node/work/.factory/node_modules/.bin:/home/node/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
     GH_TOKEN     = var.github_token
     REPO         = data.coder_parameter.repo.value
     BRANCH       = data.coder_parameter.branch.value
@@ -133,6 +134,17 @@ resource "coder_script" "checkout" {
       tar -xzf /tmp/gh.tar.gz -C /tmp
       mv "/tmp/gh_2.103.3_linux_$arch/bin/gh" "$HOME/.local/bin/gh"
     fi
+    if ! command -v jq >/dev/null; then
+      arch="$(dpkg --print-architecture)"
+      case "$arch" in
+        amd64) sum=b1c22172dd303f3be49e935aa56aa48a8b7a46e0bc838b4997d3bb451495870f ;;
+        arm64) sum=8b85c817833814ddca00a144c33705546355afccf0cf39b188f3cdb48b852309 ;;
+      esac
+      curl -fsSL -o /tmp/jq "https://github.com/jqlang/jq/releases/download/jq-1.8.2/jq-linux-$arch"
+      echo "$sum  /tmp/jq" | sha256sum -c --quiet -
+      chmod +x /tmp/jq
+      mv /tmp/jq "$HOME/.local/bin/jq"
+    fi
     git config --global user.name >/dev/null || git config --global user.name "Bernard the taktician"
     git config --global user.email >/dev/null || git config --global user.email "factory@theodo.com"
     git config --global credential.https://github.com.helper '!f() { [ -n "$GH_TOKEN" ] || exit 0; echo username=x-access-token; echo "password=$GH_TOKEN"; }; f'
@@ -148,6 +160,7 @@ resource "coder_script" "checkout" {
     fi
     cd "$work"
     if [ -f pnpm-lock.yaml ]; then pnpm install --frozen-lockfile --reporter=silent; fi
+    if [ -f .factory/pnpm-lock.yaml ]; then pnpm --dir .factory --ignore-workspace install --frozen-lockfile --reporter=silent; fi
     if [ -n "$${DATABASE_URL:-}" ]; then
       for _ in $(seq 1 60); do (echo > /dev/tcp/db/5432) 2>/dev/null && break; sleep 1; done
     fi

package/core/skills/pull-request/SKILL.md

@@ -1,22 +1,32 @@
 ---
 name: pull-request
-description: Open the ticket's pull request on GitHub, or update it, sync it with its base branch, and wait for its continuous integration to be green, fixing it when it is red, before the human review.
+description: Land the ticket on its feature's branch and keep the feature's pull request, up to date, with its continuous integration green, fixing it when it is red. A graph with a gate after this step keeps the ticket's own pull request for the team to review.
 disable-model-invocation: true
 ---
 
-The ticket's change is validated and reviewed. Leave a pull request that is open, up to date with its base branch and green, for the team to review. This skill is for GitHub, until the forge port (ADR-0027): it uses the forge's command-line tool, signed in in this environment. A project on another forge, or without continuous integration, overrides it.
+The ticket's change is validated and reviewed. One pull request per feature, the feature's branch to the base branch, is what the team reviews (ADR-0041): this skill opens it or updates it, and gets it green. `bernard pull-request` drives it on the forge the project's config names, through the forge's command-line tool, signed in in this environment (ADR-0036). A project without continuous integration overrides this skill.
+
+How the ticket reaches the feature's branch depends on its request:
+
+- `merge` is true (its graph has no gate after this step): the ticket has no pull request. The command merges the feature's branch into the ticket's, then lands the ticket on the feature's branch, and waits for the feature pull request's checks.
+- `merge` is absent (a gate follows): the command opens or updates the ticket's pull request, `branch` to `baseBranch`, which the team merges, and waits for its checks. It opens or updates the feature pull request too.
 
 1. Read `git status` and `git diff`. Group the change into atomic commits that each build: Conventional Commits, the module as scope, the tests with the code they test. Leave `.pipeline/` alone: the orchestrator commits the ticket's record.
-2. Write `pull-request.md` in your `handoffDir`: what the change does and why, with the ticket's path; how it is tested; and, from the last code review's handoff next to it, if any, the review findings left unfixed and each reviewer that reviewed fewer files than it was given, named as a gap in the review. Describe the goal, not a file-by-file changelog, in paragraphs short enough to scan.
-3. Run the driver, with the request's `baseBranch` (the branch the ticket stacks on, when it has dependencies). It reads the title from the first line of `title.md`, in your `handoffDir`: write it there before, as the one line it is, so that no free text goes on the command line. Run it with the longest timeout your shell tool allows: it waits for the checks, nine minutes at most.
+2. Write, in your `handoffDir`, the files the command reads, so that no free text goes on the command line. Describe the goal, not a file-by-file changelog, in lines short enough to scan.
+   - `feature-section.md`: the ticket's section of the feature pull request's description, a few short lines: what the ticket does, with its path; how it is tested; and, from the last code review's handoff next to it, if any, the review findings left unfixed and each reviewer that reviewed fewer files than it was given, named as a gap in the review. No heading above the third level: the description has one section per ticket. Azure DevOps cuts a description at 4,000 characters, whatever the number of tickets: keep the section to a few lines.
+   - `feature-title.md`: the title of the feature pull request, as the one line it is. It comes from the feature's plan and follows Conventional Commits, `<type>(<scope>): <subject>`, with the request's `featureTrackerKey` as the scope when it has one, such as `feat(DATA-12): export invoices as CSV`: the tracker links the pull request by it. The command uses it only to open the pull request, never to change one: a title a human edited stays. Write it every time.
+   - Gate mode only: `pull-request.md`, the ticket's pull request description: what the change does and why, with the ticket's path, how it is tested, and the review gaps as above. And `title.md`, the ticket's pull request title, one line, Conventional Commits with the request's `trackerKey` as the scope when it has one.
+3. Run the command from the root of the working copy, with the longest timeout your shell tool allows: it waits for the checks, nine minutes at most. Its options come from your request: `<plan>` is the path of the feature's plan, in the feature's folder, where the project's plan step wrote it.
 
    ```
-   bash {{harness.skillsDir}}/pull-request/scripts/pr-drive.sh --base '<baseBranch>' run --title-file '<handoffDir>/title.md' --body-file '<handoffDir>/pull-request.md'
+   bernard pull-request --base '<baseBranch>' --handoff-dir '<handoffDir>' --merge --feature-branch '<featureBranch>' --feature-base '<featureBase>' --ticket '<ticket>' --plan '<plan>'
    ```
 
-   It merges the base into the branch (ADR-0036), pushes, opens the pull request or updates its base and description, and waits for the checks of its last commit. It stops at the first action that needs you, with a `RESUME:` prompt: do what it says, then run the same command again. It keeps no state, so running it again is safe.
+   In gate mode, the command drops `--merge`, and reads the ticket's own title and description from the same folder.
+
+   It merges the base into the branch (ADR-0036), pushes it, then either lands it on the feature's branch by a push that is never forced, merging again and trying again when the branch moved meanwhile, or opens or updates the ticket's pull request. It opens the feature's pull request or rewrites the ticket's section of its description, between its `<!-- ticket:<id> -->` markers, and waits for the checks of its last commit. It stops at the first action that needs you, with a `RESUME:` prompt: do what it says, then run the same command again. It keeps no state, so running it again is safe.
 4. The checks are red (exit 4): follow `ci-fixer.md`, next to this file.
 
 Never push to the base branch.
 
-Done when the driver prints `CI_GREEN`: `passed`. A check that fails for a reason outside the code, such as a missing secret or a runner that does not start: `blocked`, naming the check and the reason. A red check still red after your round of fixes, under the stop rule of `ci-fixer.md`: `failed` with `ci-red`, giving the failures as that rule says: nothing copied from a log.
+Done when the command prints `CI_GREEN`: `passed`. A check that fails for a reason outside the code, such as a missing secret or a runner that does not start: `blocked`, naming the check and the reason. A red check still red after your round of fixes, under the stop rule of `ci-fixer.md`: `failed` with `ci-red`, giving the failures as that rule says: nothing copied from a log.

package/core/skills/pull-request/ci-fixer.md

@@ -1,14 +1,14 @@
 # Fixing a red CI
 
-The driver `{{harness.skillsDir}}/pull-request/scripts/pr-drive.sh` hands over when its checks are red (exit 4, `STOP_REASON=CI_RED`). GitHub only (ADR-0027): the tools are `gh` and `git`.
+`bernard pull-request` hands over when its checks are red (exit 4, `STOP_REASON=CI_RED`), with a `FAILED_CHECK=<name> STATE=<state> LINK=<link>` line per failed check, the state in the forge's own words (`TIMED_OUT`, `CANCELLED`, `broken`…). The checks are those of the feature's pull request when the ticket merges itself, of the ticket's pull request otherwise.
 
 ## Each attempt
 
-1. **Diagnose.** `gh pr checks <branch>` lists the failed checks. For each one, read its log with `gh run view <run id> --log-failed`, the run id taken from the check's link. Read the error before changing anything: never run a check again hoping it passes, and never call a failure flaky without evidence.
+1. **Diagnose.** For each failed check, read its log with `bernard pull-request --failed-log '<link>'`. On a forge that cannot serve the log, it prints the link back: read the cause from the check's name and from running the project's checks locally. Read the error before changing anything: never run a check again hoping it passes, and never call a failure flaky without evidence.
 2. **A cause outside the code ends the round.** A missing secret, a runner that does not start, a service the check needs that is down, an expired credential: `blocked`, naming the check and the cause. No fix of yours can change it.
 3. **Fix the cause, not the symptom.** No skipped test, no weakened assertion, no silenced warning.
 4. **Verify locally.** Run the project's checks, under _Checks_ below, and leave nothing red.
-5. **Commit and push.** A commit that follows the project's commit conventions, then run the same `bash {{harness.skillsDir}}/pull-request/scripts/pr-drive.sh` command again: it pushes and waits for the checks of the new commit.
+5. **Commit and land.** A commit on the ticket's branch that follows the project's commit conventions, then run the same `bernard pull-request` command again: it pushes, lands the fix on the feature's branch when the ticket merges itself, and waits for the checks of the new commit.
 
 ## Checks