@rsaglobaltech/specgate 0.21.0 → 0.22.1

package/CHANGELOG.md

@@ -8,6 +8,122 @@ The release process is in [`docs/release-process.md`](docs/release-process.md).
 
 ## [Unreleased]
 
+## [0.22.1] — 2026-10-20
+
+Documentation a newcomer can follow, and the CLI's words brought in line with it.
+
+### Changed
+
+- **The documentation, rewritten** after an audit of every page against the
+  CLI and the first real end-to-end run on Jira Cloud and GitHub. Three
+  sources of work (a change, a brief, a Jira ticket) into one lifecycle of
+  four verbs; the recorded journeys run `propose`, `apply` and `archive`;
+  archive comes before the pull request everywhere. New pages: *From a Jira
+  ticket* for a team lead setting it up, and *An existing codebase, with work
+  in Jira* (Maven profiles, a parent POM, Bitbucket and Jenkins).
+- **The `/specgate:draft` agent command runs `propose --from-brief`**, and the
+  MCP write guard names `specgate propose <id>`.
+
+### Fixed
+
+- `propose --help` lists `--no-push`; `alm --help` no longer says a ticket has
+  no acceptance criterion.
+- `alm pr` asks for the least token it needs: Pull requests, read and write.
+- `alm pr` is covered by an E2E journey and is not exposed as an MCP tool.
+
+## [0.22.0] — 2026-10-20
+
+A brief shaped like what it becomes, checked before any agent drafts from it
+(ADR-0038); and a Jira ticket as source text, as a brief is (ADR-0039). Tried
+end to end on a real Jira Cloud board and GitHub: two stories went from the
+ticket to Done, the board moved by its own automation.
+
+### Fixed
+
+- **New ids are free on every branch** (REQ-152). Two changes opened on two
+  branches both reserved REQ-002: reserving ids now reads every local and
+  remote-tracking branch. A change also reserves its scenario ids,
+  `scn_range` in `change.yaml` (REQ-157).
+- **A monorepo's stack is read from its apps** (REQ-153). With npm workspaces,
+  `AGENTS.md` said "Stack: Node.js" for a Spring API in `apps/api`.
+- **`specgate update` updates the `AGENTS.md` contract** (REQ-155), keeping its
+  facts and project rules, also when the project has no other agent files.
+- **The harness's commits name the ticket** (REQ-156): `KAN-14 REQ-002: …`.
+- **`--agent` on an open change hands the agent its findings.** A second run
+  read a finished draft and changed nothing.
+- **Credentials never travel over plain http**: `base_url` and `pr.base_url`
+  must be https (localhost excepted).
+
+- **`specgate alm pull` works against Jira Cloud again.** Atlassian removed
+  `/rest/api/3/search` (HTTP 410); search now pages `/rest/api/3/search/jql`
+  by `nextPageToken`, up to 1000 issues.
+- **Tokens created with scopes.** `cloud_id: auto` sends every Jira request
+  through `api.atlassian.com/ex/jira/<cloud id>`, the only door such a token
+  opens. Sent to the site, such a token is answered as anonymous — HTTP 200 and
+  no issues — which used to read as "No open issues"; it is now a 401 whose fix
+  names `cloud_id: auto`.
+
+### Changed
+
+- **A draft is not opened over a broken brief.** `propose --from-brief
+  <module>` refuses with `brief_not_ready` while the brief has an error: an
+  empty body, an empty module section, a module without its section once the
+  brief uses sections, or rules without examples. A brief with no module
+  sections — a pasted email — drafts as before.
+- **`--new-brief` writes cards.** Why, a glossary, a `## Module:` section with
+  Rules, Examples and Questions, and notes, in place of the six sections.
+
+### Added
+
+- **From a Jira ticket** ([ADR-0039](docs/specs/adr/0039-the-ticket-as-source-text.md),
+  change `ticket-source`, [the page](docs/from-a-ticket.md)).
+  - `specgate propose --from-ticket <KEY | issue.json> --check`: the ticket's
+    intent, source, acceptance criteria and open questions (English, German or
+    Spanish headings, ADF or plain text, or `acceptance_field`), and a
+    Definition of Ready, T1–T9, each with a fix an analyst applies in Jira.
+  - `specgate propose --from-ticket <KEY>`: the change `<key>-<slug>` with
+    `ticket.md` as its source — the D-checklist runs against the ticket, and an
+    edited copy is `ticket_copy_edited` — the capability from `epics:`, and the
+    branch `feature/<KEY>-<slug>` (`bugfix/` for a bug). `--agent` drafts it,
+    confined, never writing the copy.
+  - `ticket_changed` when the ticket moved since the change was opened;
+    `ticket_key_missing` from `check` for a commit on the ticket's branch that
+    does not name it.
+  - `specgate alm pr <change>`: one pull request per ticket on GitHub, titled
+    with the key, its body the requirements and the gate, the archived change
+    included (REQ-159). Never merges; keeps what reviewers wrote.
+  - The ticket's branch is pushed as soon as it is created (REQ-148), so a
+    Jira automation moves the ticket when work starts.
+  - `AGENTS.md` names the ticket path (REQ-154); in a project connected to
+    Jira, `status` suggests `propose --from-ticket` (REQ-158).
+- **Brief cards** ([ADR-0038](docs/specs/adr/0038-brief-cards.md), change `brief-cards`).
+  - `specgate propose --from-brief --check`: rules B1–B11 on the brief, each
+    with its fix. Errors (B1–B4) stop a draft; warnings (B5–B11) name vague
+    words, promises without a number, technology in a rule, modules too big,
+    actors never mentioned, non-goals in a rule, and conditions placed last
+    (EARS).
+  - `non_goals: [...]` in the front matter.
+  - `DRAFTING.md` quotes the module's section and lists its values and
+    questions: a rule becomes a requirement, an example a scenario, a question
+    a `questions.md` row.
+  - `propose --from-brief --agent` proposes the module sections from pasted
+    notes, once the fields are complete; a lost line puts the brief back
+    (`draft_brief_text_lost`).
+  - `propose --help` says when no brief is needed.
+- **"Write the brief" in eight steps**, with a glossary, the EARS patterns and
+  the whole Lingo example, its outputs recorded.
+
+### Fixed
+
+- **Front matter shapes are reported as shapes.** `actors: [Admin]` was "There
+  is no `actors:` list" and `surfaces: web` passed silently; both are now
+  `brief_wrong_shape` with the line to write.
+- **D6 no longer reads HTML comments as the brief.** A template's hint such as
+  "e.g. 48 hours" made 48 look stated.
+- **`explore` prints a project snapshot**, no longer called a brief.
+- **The guides use `propose --from-brief`** where they still said `draft`, and
+  forja's guide follows propose → apply → archive.
+
 ## [0.21.0] — 2026-10-20
 
 The daily loop becomes four verbs over the same gate (ADR-0035), the gate stops

package/README.md

@@ -12,126 +12,111 @@
 
 </div>
 
-> Stop coding before requirements are operationally clear. Every requirement
-> maps to a scenario, a domain artefact, an implementation and a test — and the
-> gate fails when one is missing.
+Specgate keeps what your product must do in the repository, as numbered
+requirements with Gherkin scenarios, next to the code and the tests that prove
+them. A test that mentions a requirement's id (`REQ-007`) is the link, and the
+traceability matrix is generated from those mentions. The gate, `specgate check`,
+fails a pull request when a delivered requirement has no scenario or no test
+that names it, or when your test suite fails.
 
----
+## ⚡ Install
 
-## ⚡ Start
+You need **Node.js 22 or later**.
 
 ```bash
-npm i -g @rsaglobaltech/specgate   # or prefix every command with npx @rsaglobaltech/specgate@latest
-
-cd your-repo                       # or an empty directory
-specgate init                      # adopts the code that is there, touching none of it;
-                                   # scaffolds a new project where there is none
-specgate ci init                   # the gate as a CI job — GitHub, GitLab, Azure or Jenkins,
-                                   # detected from the repository
-specgate check                     # the gate, locally
+npm install --save-dev @rsaglobaltech/specgate   # in a project with a package.json
+npx specgate --help
 ```
 
-Requires **Node.js ≥ 22** — or none with Docker: `docker run --rm -v "$PWD:/workspace" ghcr.io/rsaglobaltech/specgate check`.
-The package is scoped, the binary is not ([ADR-0024](docs/specs/adr/0024-the-tool-is-renamed-the-format-is-not.md)).
+Without installing it (an empty folder, a Java or Python project), prefix each
+command with `npx @rsaglobaltech/specgate@latest` instead of `npx specgate`.
+With Docker and no Node.js: `docker run --rm -v "$PWD:/workspace" ghcr.io/rsaglobaltech/specgate check`.
 
-→ [Getting started](docs/getting-started.md) · [Your team's first pull request](docs/first-pr.md) · [Quickstart for joiners](docs/quickstart.md)
+Then run `init` once:
 
-## 🔁 The daily loop — four verbs
+- **In a repository that has code** (`package.json`, `pom.xml`, `go.mod`, …),
+  `specgate init` adopts it in place: it adds `spec.md`, `features/` and
+  `docs/specs/`, and changes no source file.
+- **In an empty folder**, `npx @rsaglobaltech/specgate@latest init` scaffolds a
+  new specification project. A wizard asks for the project's name, type, stack
+  and test toolchain, then creates it in a new sub-folder named after the
+  project, for example `./my-spec-driven-app/`. `--yes` takes every default
+  without asking. It writes the specification files, not application code.
+
+Step by step, with every output shown: [Getting started](docs/getting-started.md).
+
+## 🔁 The lifecycle — four verbs
 
 ```bash
-specgate propose add-pdf-invoices   # a change: proposal, tasks, a delta to write, REQ ids reserved
-# write REQ-007 and its scenario in the delta, a test that mentions REQ-007, the code
-specgate apply                      # the next requirement through the gate: Implemented when green
-specgate status                     # what is open, and the next command to run
+specgate propose add-pdf-invoices   # open a change: a proposal, a delta to write, REQ ids reserved
+# write REQ-007 and its scenario in the delta, a test that mentions REQ-007, then the code
+specgate apply REQ-007              # refused until a test names it and the gate passes; then Implemented
+specgate status                     # what is left, and the next command to run
 specgate archive add-pdf-invoices   # once every requirement in it is Implemented
 ```
 
-`specgate check` is the same gate for CI ([ADR-0035](docs/specs/adr/0035-four-verbs-one-lifecycle.md)).
-**A change is archived when its code is done**: while it is open its
-requirements already count — `status` lists them, `apply` and `check` judge the
-project as it will be after archive — and `archive` refuses one still pending.
-`apply` refuses a requirement no test names and writes nothing while the gate
-fails. **Mentioning `REQ-NNN` in a test is the link**; the matrix is generated.
-From a plan: `specgate propose --from-brief`. Old names (`draft`, `done`…) keep
-working; everything else is in `specgate --help --all`.
+`specgate check` runs the same gate before a pull request and in CI;
+`specgate ci init` writes the CI job for GitHub, GitLab, Azure or Jenkins.
+You archive a change on its branch, before the pull request, so the spec and
+the code reach review together.
 
-## 🪜 Adopt one level at a time
+## 📥 Where work comes from
 
-Each level is useful on its own and never requires the ones above it.
+Every piece of work enters the same lifecycle. Pick the entry that matches what
+you have:
 
-| Level  | You get                                          | Commands                     | Cost    |
-| ------ | ------------------------------------------------ | ---------------------------- | ------- |
-| **L1** | Traceable specs in your repo                     | `init`, `propose`, `apply`, `archive` | ~1 hour |
-| **L2** | A PR gate enforcing spec and test coverage       | `check`, `ci init`           | ~1 hour |
-| **L3** | Versioned, reusable domain requirements          | `specops add / sync / diff`  | ~1 day  |
-| **L4** | Agent-driven delivery, one requirement at a time | `agents init`, `harness run` | ~1 week |
+| You have | Run | Guide |
+| --- | --- | --- |
+| One behaviour to add or change | `specgate propose <change-id>` | [Propose one change](docs/start/existing-2-specify.md) |
+| A client brief, or a plan for a new product | `specgate propose --from-brief` | [From a client brief](docs/from-a-brief.md) |
+| A Jira story with acceptance criteria | `specgate propose --from-ticket <KEY>` | [From a Jira ticket](docs/from-a-ticket.md) |
 
 ## 🛠️ What it does
 
-**A gate that does not lie.** `specgate check` fails when a delivered
-requirement has no scenario, template steps, no test that mentions it, or
-points at a file that is gone. A Draft owes nothing yet: green on day one,
-stricter with every delivery. Given a test command, it runs your suite too.
-→ [Writing specs](docs/writing-specs.md) · [Validating](docs/validating.md) · [Command reference](docs/commands.md)
-
-**Reviews that read intent.** The reviewer reads the requirement, its
-scenario and the test that names it — the gate has already proved the
-mechanical part. A change is a reviewable delta: only what moves, never a
-copy. It is archived — merged into the spec tree, with its feature files —
-only once every requirement in it passed the gate, in the same pull request.
-→ [Your team's first pull request](docs/first-pr.md) · [Reviewing changes](docs/reviewing-changes.md)
-
-**From a brief, or from OpenSpec.** Save your plan as `docs/brief.md`, run
-`specgate propose --from-brief`: module by module, it briefs your agent and holds
-the draft to eleven rules — scenarios per actor and surface, sourced laws, every
-value in the brief or listed as an assumption, open questions that block, ids each
-actor can reach. Teams on OpenSpec keep it: `specgate verify` fails while
-a change claims a scenario no test names.
-→ [A new project, step by step](docs/new-project.md) · [From a client brief](docs/from-a-brief.md) · [Already on OpenSpec](docs/openspec.md)
-
-**Your agent works the same loop.** `specgate agents init` gives Claude Code, Cursor,
-Copilot, Windsurf, Aider, Gemini, Cline, Codex or Antigravity the loop as slash commands
-(`/specgate:propose`, `/specgate:apply`, …) from one definition. Every daily command speaks
-JSON with stable codes and a `fix` on each. MCP ships in the package: `specgate mcp install --client claude`.
-→ [Agents](docs/agents.md) · [The agent contract](docs/specs/agent-contract.md) · [Automation and MCP](docs/automation.md)
-
-**Domain knowledge as a dependency.** A pack is a versioned, schema-validated
-domain model. Install it, pin it, upgrade it deliberately — and review the
-upgrade as intent with `specops diff --as-change`, not as a file diff.
-→ [Domain packs: 7 proven in the pilots, 11 starter examples](docs/domain-packs.md) · [Supply chain](docs/supply-chain.md)
-
-**Unattended delivery.** `specgate harness run` drives plan → agent → verify →
-apply for every pending requirement, each in its own git worktree; it merges only
-with `--chain`, only what passed the gate. The agent is any shell command with
-`{prompt_file}`; `specgate studio` shows it at work, at `/live`. `specgate alm sync`
-keeps Jira, Azure Boards or GitHub Issues in step.
-→ [The harness](docs/harness.md) · [Jira, Azure Boards and GitHub Issues](docs/alm.md)
-
-**Tested as you install it.** Every release runs an end-to-end suite over every
-command, against the packed tarball, on Linux, macOS and Windows; releases
-since 0.14 come from building real products with it, from brief to running app.
+- **A gate that does not lie.** `check` fails when a delivered requirement has
+  no scenario, no test that names it, or points at a missing file. A `Draft`
+  owes nothing yet, so the gate is green on day one.
+  → [Validating](docs/validating.md)
+- **Reviews that read intent.** A change is a delta: only what moves. The
+  reviewer reads the requirement, its scenario and its test.
+  → [Your team's first pull request](docs/first-pr.md)
+- **Drafts held to their source.** A draft from a brief or a ticket is checked
+  against that text: every value it uses must come from the source or be listed
+  as an assumption. → [From a client brief](docs/from-a-brief.md)
+- **Your agent works the same loop.** `specgate agents init` installs the loop
+  as slash commands for Claude Code, Cursor, Copilot and other agent tools; an
+  MCP server ships in the package. → [Agent tools](docs/agents.md)
+- **Unattended delivery.** `specgate harness run` hands each pending requirement
+  to your coding agent in its own git worktree and keeps only what passes the
+  gate. → [The harness](docs/harness.md)
+- **Domain knowledge as a dependency.** Versioned domain packs install
+  requirements a team has already proved. → [Domain packs](docs/domain-packs.md)
+- **Already on OpenSpec?** `specgate verify` checks what OpenSpec calls done
+  against your tests. → [Already on OpenSpec](docs/openspec.md)
 
 ## 🆚 How it compares
 
-| Capability                             |        **this**        | [OpenSpec](https://github.com/Fission-AI/OpenSpec) | [spec-kit](https://github.com/github/spec-kit) | [Cursor rules](https://docs.cursor.com/context/rules-for-ai) | README only |
-| -------------------------------------- | :--------------------: | :------------------------------------------------: | :--------------------------------------------: | :----------------------------------------------------------: | :---------: |
-| Change lifecycle                       |           ✅           |                         ✅                         |                       ❌                       |                              ❌                              |     ❌      |
-| Versioned domain packs                 |           ✅           |                         ❌                         |                       ⚠️                       |                              ❌                              |     ❌      |
-| Traceability matrix + CI gate          |           ✅           |                         ❌                         |                       ⚠️                       |                              ❌                              |     ❌      |
-| Agent JSON contract                    |           ✅           |                         ✅                         |                       ❌                       |                              ❌                              |     ❌      |
-| Draft checklist from a brief           |           ✅           |                         ❌                         |                       ⚠️                       |                              ❌                              |     ❌      |
-| Proves OpenSpec's "done" against tests |      ✅ `verify`       |                         ❌                         |                       ❌                       |                              ❌                              |     ❌      |
-| Vendor-neutral                         |           ✅           |                         ✅                         |                       ✅                       |                              ❌                              |     ✅      |
-| Commands to learn before the first PR  | ✅ 6 (31 more, opt-in) |                         ✅                         |                       ✅                       |                              ✅                              |     ✅      |
+Specgate does each of the things below. What the closest alternatives cover:
+
+| Capability                    | [OpenSpec](https://github.com/Fission-AI/OpenSpec) | [spec-kit](https://github.com/github/spec-kit) | [Cursor rules](https://docs.cursor.com/context/rules-for-ai) |
+| ----------------------------- | :------------------------------------------------: | :--------------------------------------------: | :----------------------------------------------------------: |
+| Change lifecycle              |                         ✅                         |                       ❌                       |                              ❌                              |
+| Traceability matrix + CI gate |                         ❌                         |                       ⚠️                       |                              ❌                              |
+| Draft checked against a brief |                         ❌                         |                       ⚠️                       |                              ❌                              |
+| Work from Jira tickets        |                         ❌                         |                       ❌                       |                              ❌                              |
+| Versioned domain packs        |                         ❌                         |                       ⚠️                       |                              ❌                              |
+| Vendor-neutral                |                         ✅                         |                       ✅                       |                              ❌                              |
 
-OpenSpec is the closest tool: if you want the change loop without packs or an enforced matrix, it fits better.
-→ [Full matrix, trade-offs and migration paths](docs/comparisons.md)
+OpenSpec is the closest tool: if you want the change loop without an enforced
+gate, it fits better. → [Full comparison](docs/comparisons.md)
 
 ## 📚 Documentation
 
-- [Getting started](docs/getting-started.md) · [Your team's first pull request](docs/first-pr.md) · [Command reference](docs/commands.md)
-- [How-to guides](docs/how-to.md) · [Tutorial](docs/tutorial.md) · [Supply chain](docs/supply-chain.md) · [Architecture](docs/specs/architecture.md)
-- [Case study](docs/case-studies/case-1.md) · [ADRs](docs/specs/adr/README.md) · [Docs site](https://rsaglobaltech.github.io/specgate/) · [Spec coverage report](https://rsaglobaltech.github.io/specgate/report.html)
+- [Getting started](docs/getting-started.md) — install, pick your path, the four verbs
+- [From a Jira ticket](docs/from-a-ticket.md) · [From a client brief](docs/from-a-brief.md)
+- [Concepts](docs/concepts.md) — the ideas and vocabulary behind every command
+- [Commands](docs/commands.md) — every command and flag
+- [FAQ](docs/faq.md) · [Troubleshooting](docs/troubleshooting.md) · [Docs site](https://rsaglobaltech.github.io/specgate/)
 
 ## 🧰 Companion tools
 
@@ -140,8 +125,8 @@ OpenSpec is the closest tool: if you want the change loop without packs or an en
 
 ## 🤝 Contributing
 
-PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) (good first: templates, validator rules,
-domain packs) · [MAINTAINERS.md](MAINTAINERS.md) · [SECURITY.md](SECURITY.md) for private reports.
+PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) · [MAINTAINERS.md](MAINTAINERS.md) ·
+[SECURITY.md](SECURITY.md) for private reports.
 
 ## 📄 License