forgedock 1.1.6 → 1.1.8

package/docs/spec/forge-protocol-v1.md

@@ -449,6 +449,43 @@ artifact so a sub-issue builder can fetch upstream context directly.
 <!-- FORGE:PRIOR_GIST: {https://example.com/artifact} -->
 ```
 
+#### Security: Gist Visibility — Normative Requirement <!-- Added: forge#1729 -->
+
+**All FORGE gist types (`FORGE:KNOWLEDGE_GIST`, `FORGE:MILESTONE_INDEX`, `FORGE:PRIOR_GIST`,
+and the memory-index Gist referenced by `FORGE:MEMORY_INDEX` in `close.md`) MUST be created
+secret. Publishing them as public Gists is a protocol violation.**
+
+Rationale: these artifacts embed investigation findings — root causes, file paths, affected
+service names, and security details. A public Gist exposes this content to a world-readable
+URL with no access control. `gh gist create` is secret by default; the requirement is that
+no pipeline spec or operator script must pass `--public` when creating any of these artifacts.
+
+**Enforcement**: The `pre-tool-use.mjs` hook (Rule 3) hard-blocks `gh gist create --public`
+in pipeline sessions. The `doctor-pipeline-state.sh` check I8 audits existing annotation-referenced
+gists and reports a CRITICAL finding if any are public.
+
+**Migration** (if a public gist is found): GitHub does not support changing a Gist's visibility
+in place. To replace a public pipeline gist with a secret one:
+
+```bash
+# 1. Save current content
+gh gist view {GIST_ID} > /tmp/gist_migrate.md
+[ -s /tmp/gist_migrate.md ] || { echo "ABORT: empty save"; exit 1; }
+
+# 2. Delete the public gist
+gh gist delete {GIST_ID} --yes
+
+# 3. Recreate secret (no --public) with same description
+gh gist create /tmp/gist_migrate.md --desc "{ORIGINAL_DESCRIPTION}"
+# gh gist create without --public creates a secret gist.
+
+# 4. Update the FORGE annotation on the issue to point to the new URL
+```
+
+**Override**: set `FORGE_ALLOW_PUBLIC_GIST=1` in the operator's shell environment before
+starting Claude Code only if a public gist is genuinely required (e.g., sharing a demo
+artifact). This must not be used for pipeline memory gists.
+
 ### 4.3 Control and error markers
 
 These markers carry no Markdown body; their presence is the signal.
@@ -1143,16 +1180,71 @@ separate, MIT-licensed npm package:
 **`@forgedock/protocol`** — available at `packages/protocol/` in the ForgeDock
 repository.
 
-It provides:
+### 13.1 Normative codec path
+
+**`packages/protocol/` is the normative write and read path for all FORGE
+annotations.** Hand-rolled annotation construction (embedding raw
+`<!-- FORGE:TYPE -->` strings in inline heredocs or `--body` blocks) is
+**non-conformant** because it bypasses the codec's escaping and round-trip
+guarantees. Every producer MUST route annotation construction through one of:
+
+1. **`forge-annotation.sh write <TYPE> --field KEY=VALUE ...`** (AGPL-licensed,
+   ships with the npm package at `scripts/forge-annotation.sh`), or
+2. **`node packages/protocol/src/cli.js emit <TYPE> --field KEY=VALUE ...`**
+   (MIT-licensed, part of the `@forgedock/protocol` package)
+
+Both paths delegate to `emit()` from `packages/protocol/src/emit.js`, which
+applies the complete escaping and sanitization policy (§3.5 injection hardening).
+
+### 13.2 JavaScript API
+
+```js
+import { parse, validate, emit, emitPartial } from '@forgedock/protocol';
+```
 
 - `parse(commentBody)` — extracts all annotations from a comment body string
 - `validate(annotation)` — checks conformance per §3–4; returns `{ valid, errors, warnings }`
-- `emit(type, fields)` — produces well-formed annotation strings
+- `emit(type, fields)` — produces a well-formed annotation string; applies all §3.5 escaping
 - `emitPartial(type)` — produces the partial sentinel for a type (§3.3)
 
-A conformance suite in `packages/protocol/fixtures/` covers all 13 reserved
-types with valid and invalid examples. The CLI runner can be invoked against any
-fixtures directory:
+### 13.3 CLI subcommands
+
+The CLI at `packages/protocol/src/cli.js` exposes three modes:
+
+```bash
+# Emit — print a well-formed annotation body to stdout
+node packages/protocol/src/cli.js emit INVESTIGATOR \
+  --field Verdict=CONFIRMED --field Confidence=HIGH \
+  --field Severity=MEDIUM --field "Task Type=Bug Fix" \
+  --field "Decomposition Assessment=NO — single fix."
+
+# Parse — read a comment body from stdin, extract a field value
+echo '<!-- FORGE:INVESTIGATOR -->...' | \
+  node packages/protocol/src/cli.js parse --type INVESTIGATOR --field Verdict
+# → CONFIRMED
+
+# Conformance runner (legacy — no subcommand keyword)
+node packages/protocol/src/cli.js fixtures/
+```
+
+The `emit` subcommand also supports the Base64url machine-surface form for
+`FORGE:CARD` annotations (design decision 2026-07-08: encoding beats escaping):
+
+```bash
+node packages/protocol/src/cli.js emit CARD \
+  --field issue=1370 --field status=merged --b64
+# → <!-- FORGE:CARD: v1 sha:7234c2d8 b64:eyJ... -->
+```
+
+The Base64url alphabet `[A-Za-z0-9_-]` cannot contain `>`, `<`, or `!`, making
+`-->`, `--!>`, and `<!--` structurally unrepresentable in the machine surface.
+
+### 13.4 Conformance suite
+
+A conformance suite in `packages/protocol/fixtures/` covers all reserved types
+with valid and invalid examples, including adversarial payloads that reproduce
+historical escaping vulnerabilities. The suite can be run against any fixtures
+directory:
 
 ```bash
 npx @forgedock/protocol fixtures/

package/docs/spec/label-state-machine.md

@@ -14,11 +14,14 @@ See also: [FORGE Annotation Protocol §6](forge-protocol-v1.md#6-label-state-mac
 | `workflow:ready-to-build` | Investigation complete, build not started | Investigator agent |
 | `workflow:building` | Build phase active | Builder agent |
 | `workflow:in-review` | PR created, review active | Orchestrator agent |
+| `workflow:awaiting-merge` | Remediated + re-reviewed, awaiting a human merge decision | Review-pr Phase 8 (auto-merge guard) |
 | `workflow:merged` | PR merged, issue closed | Close phase agent |
 | `workflow:invalid` | Issue closed as invalid | Investigator agent |
 | `workflow:decomposed` | Issue decomposed into sub-issues | Decomposer agent |
 | `needs-human` | Pipeline blocked, human intervention required | Any agent on error |
 
+`workflow:awaiting-merge` vs `needs-human`: both are terminal (the pipeline stops advancing the issue automatically), but they mean different things. `needs-human` means the pipeline hit a condition it cannot resolve on its own (genuinely blocked — conflicting PR, failed verdict, calibration/trust escalation, etc.) and a human must diagnose and act. `workflow:awaiting-merge` means the opposite: the PR was previously escalated to `needs-human`, has since been remediated and re-reviewed to a clean `APPROVED` verdict with no mergeability blockers, but does not yet meet the automated auto-land bar (see forge#1809 Q1) — a human only needs to click merge, not diagnose a problem. `scripts/transition-label.sh` clears `needs-human` (best-effort) on every transition, so moving an issue onto `workflow:awaiting-merge` also clears any stale `needs-human` label.
+
 ## Transitions
 
 ```
@@ -27,6 +30,7 @@ See also: [FORGE Annotation Protocol §6](forge-protocol-v1.md#6-label-state-mac
   → workflow:ready-to-build     [Phase 2: Investigation complete]
   → workflow:building           [Phase 3: Build started]
   → workflow:in-review          [Phase 4: PR created]
+  → workflow:awaiting-merge [TERMINAL] [Phase 5/review-pr: re-reviewed after needs-human, awaiting human merge]
   → workflow:merged  [TERMINAL] [Phase 5: PR merged]
   → workflow:invalid [TERMINAL] [Any phase: closed as invalid]
   → workflow:decomposed [TERMINAL] [Phase 2: split into sub-issues]
@@ -40,6 +44,7 @@ Processing stops when any of these labels is set:
 - `workflow:merged`
 - `workflow:invalid`
 - `workflow:decomposed`
+- `workflow:awaiting-merge`
 - `needs-human`
 
 ## Label Exclusivity
@@ -49,7 +54,7 @@ At most one `workflow:*` label should be active on an issue at any time. When tr
 ```bash
 gh issue edit {NUMBER} -R {REPO} \
   --add-label "workflow:building" \
-  --remove-label "workflow:investigating,workflow:ready-to-build,workflow:in-review,workflow:merged,workflow:invalid,workflow:decomposed"
+  --remove-label "workflow:investigating,workflow:ready-to-build,workflow:in-review,workflow:awaiting-merge,workflow:merged,workflow:invalid,workflow:decomposed"
 ```
 
 This is enforced by `scripts/transition-label.sh` — use `resolve_script 'transition-label'` rather than calling `gh issue edit` directly when possible.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "description": "Autonomous dev pipeline for Claude Code. GitHub as institutional memory — every issue, PR, and annotation survives context resets and makes the next agent smarter.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"
@@ -45,7 +45,7 @@
     "README.md"
   ],
   "scripts": {
-    "test": "node --test \"bin/tests/**/*.test.mjs\"",
+    "test": "node --test \"bin/tests/**/*.test.mjs\" \"packages/protocol/test/**/*.test.mjs\"",
     "docs:dev": "vitepress dev docs/site",
     "docs:build": "vitepress build docs/site",
     "docs:preview": "vitepress preview docs/site"