forge-orkes 0.55.0 → 0.58.2

package/template/.forge/templates/project.yml

@@ -69,6 +69,36 @@ verification:
   e2e_soft_cap: 10                    # M9: advisory cap on e2e:true stories per milestone. Reviewing warns when exceeded. Soft — never blocks.
   # Advisory mode: commands already failing before Forge started run but don't block — warn only.
 
+# forge:                             # Framework behavior toggles (all optional; absent → defaults).
+#   validation_event: in_session_signoff
+#                                    # How a merged unit becomes VALIDATED in the derived release_state
+#                                    # ladder (unmerged → merged → validated; computed by
+#                                    # .claude/hooks/forge-release-fold.sh, never stored). Two bindings:
+#                                    #   in_session_signoff (DEFAULT — absent means this): today's behavior,
+#                                    #     byte-for-byte — validated derives from the operator's in-session
+#                                    #     sign-off (signoff/<unit> tag, current.human_verified, or the
+#                                    #     legacy-complete grandfather).
+#                                    #   promotion_approval (opt-in): validated derives from a HOST-recorded
+#                                    #     promotion — a CI-signed tag minted by the deploy pipeline's
+#                                    #     Environment-approved job (the Track B coupling: that job must emit
+#                                    #     the tag below byte-exactly). The fold verifies it OFFLINE
+#                                    #     (git tag -v; no network) and checks CONTAINMENT: every unit whose
+#                                    #     landed sha is an ancestor of the approved deploy sha is validated.
+#                                    # B5 CONSEQUENCE: choosing promotion_approval changes when `complete`
+#                                    # can be set — close becomes machine-verified (no in-session sign-off);
+#                                    # the human gate moves to the deploy boundary (derived validated at
+#                                    # promotion). Default binding keeps today's close gate byte-for-byte.
+#                                    # This key sits on the step-2 protected-paths hold list: a diff
+#                                    # flipping the mode blocks auto-merge for operator review — changing
+#                                    # it is an operator decision, never an agent edit (F4/F5).
+#   promotion:                       # Read only when validation_event: promotion_approval.
+#     tag_pattern: "promotion/{sha}" # FROZEN 2026-07-16. {sha} = the full deploy sha the promotion job
+#                                    # approved (not per-unit). The producing side must mint it byte-exactly —
+#                                    # a pattern drift here is a silent never-validates bug.
+#     allowed_signers: ""            # Path to the CI key's allowed-signers file (committed, PUBLIC keys
+#                                    # only — the private key lives host-side, in the deploy Environment).
+#                                    # Empty ⇒ git config gpg.ssh.allowedSignersFile.
+
 success_criteria:                   # How do we know we're done?
   - ""                              # e.g., "User can create and edit posts"
   - ""                              # e.g., "All tests pass with >80% coverage"
@@ -90,28 +120,28 @@ models:
     securing: sonnet                   # Security analysis needs depth
     debugging: sonnet                  # Investigation needs solid reasoning
     discussing: sonnet                 # Conversation needs natural fluency
-  # by_complexity:                     # Per-task complexity -> model (M24). Overrides skills.X — see FORGE.md Model Routing Precedence.
-  #   trivial: haiku
-  #   standard: sonnet
-  #   complex: opus
-
-orchestration:                       # M10 multi-agent orchestration (experimental). Only consulted when M10 is installed.
-  # auto: true                         # false = never auto-route Standard/Full through orchestrating (install = consent; set false to opt out).
-  # worktree_root: "../<repo>-worktrees"  # Where Forge worktrees live. Default: ../<repo-basename>-worktrees (per-repo sibling — see ADR-010).
-                                          # Relative paths resolve against the REPO ROOT (not shell cwd). Absolute paths and a leading ~ are honored.
-                                          # Editing only affects newly created worktrees; live worktrees keep their recorded lifecycle.worktree_path.
-                                          # Common overrides:
-                                          #   ~/.forge/worktrees/<repo>    — central home dir, keeps the parent dir of the repo clutter-free
-                                          #   ../wt/<repo>                 — shared dir with per-repo subfolder
-                                          # Do NOT point this inside the repo working tree (file watchers + indexers will recurse into the worktree).
 
-forge:                               # Forge framework-level settings (all optional)
-  # upstream_repo: "https://github.com/zayneupton/forge"
-                                       # Where framework-scope desire paths (ADR-012) file issues when `gh`
-                                       # is available. Default if absent: the canonical Forge repo, so this
-                                       # works configless. Uncomment only to retarget a fork/mirror.
-  # worktree_rebase_check: true        # Opt-in: when forge boots inside a worktree, diff .forge/ vs main and
-                                       # offer to rebase/restore shared-mutable files (FORGE.md State Ownership).
+# notion:                            # OPT-IN work-management adapter — INERT by default. Projects Forge
+#                                    # milestones/streams/packages onto a Notion board and reads human triage/
+#                                    # priority proposals back. Activates only with BOTH this block (enabled: true)
+#                                    # AND a Notion MCP server in .mcp.json; absent either → fully inert, zero
+#                                    # behavior change. Git (.forge/) stays source of truth — Notion is a
+#                                    # projection + inbox, never symmetric sync (ADR-019). Mirrors the opt-in
+#                                    # shape of forge.beads_integration.
+#   enabled: false                   # Master switch. false/absent → adapter never runs.
+#   database_id: ""                  # Id of the single "Forge Work Items" Notion database (all layers as rows).
+#   properties:                      # OPTIONAL rename map: Forge property → your Notion column name. Omit → defaults.
+#     Forge ID: "Forge ID"           #   Binding key — agent-owned, set once, never overwritten.
+#     Status: "Status"               #   Agent-owned, overwritten each projection.
+#     Priority: "Priority"           #   Human-owned — read as proposal, never overwritten.
+#   intake_filter:                   # OPTIONAL (FR-116): gate which Forge-ID-less pages pull_inbox() treats as
+#                                    # triage requests, so one board can mix agent items + arbitrary human pages.
+#                                    # Absent → every Forge-ID-less page is a candidate (FR-114 base). One of:
+#     property: "Type"               #   {property, equals} — page's <property> equals <value>
+#     equals: "Request"
+#     # property: "Type"             #   {property, in} — page's <property> is one of <values>
+#     # in: ["Request", "Bug"]
+#     # view: "Triage"               #   {view} — pages in the named saved Notion view
 
 risks:                              # What could go wrong?
   - risk: ""

package/template/.forge/templates/state/index.yml

@@ -1,25 +1,52 @@
-# Forge Global State — Cross-Milestone Index (DERIVED)
-#
-# This file is REGENERATED by the `forge` skill's rollup step from
-# state/milestone-*.yml. Do NOT hand-edit it, and do NOT add per-milestone
-# cursor data or narrative here — that lives in state/milestone-{id}.yml.
-#
-# Worktree / parallel agent sessions MUST NOT write this file. Editing only the
-# per-milestone files (different files = no git conflict) and regenerating this
-# registry from them is what makes Forge state safe across many worktrees.
-#
-# Rollup is deterministic + idempotent: regenerating from the same milestone
-# files yields identical bytes, so concurrent regenerations never conflict.
-
-milestones:                            # Registry rolled up from state/milestone-{id}.yml
+# Forge Global State — Cross-Milestone Index
+# Auto-managed by agents. Do not edit manually unless recovering from errors.
+# This file tracks global concerns. Per-milestone state lives in state/milestone-{id}.yml.
+
+milestones:                            # Active milestones and their high-level status
   - id: 1
-    name: ""                           # mirrors milestone-{id}.yml milestone.name
-    status: not_started                # mirrors current.status: not_started | active | deferred | complete
-    last_updated: null                 # mirrors current.last_updated — used for resume default selection
-
-# NOTE — removed from this file by design (M11). (Tokens below are spaced to
-# avoid tripping naive legacy-detection greps that scan for "<key>:".)
-#   metrics    — had zero writers; derive from `git log` if ever needed.
-#   desire-paths — now append-only files under state/desire-paths/ (one per
-#                  observation) so concurrent agents never collide. Occurrence
-#                  counts are derived by globbing that directory, not mutated here.
+    name: ""                           # Human-readable milestone name from roadmap
+    status: not_started                # not_started | active | deferred | complete
+    last_updated: null                 # ISO 8601 timestamp — used for resume default selection
+    release_state: unknown             # DERIVED — fold output, git-ignored cache only
+
+metrics:
+  total_commits: 0
+  total_files_modified: 0
+  verification_passes: 0
+  verification_failures: 0
+  checkpoints_hit: 0
+
+# Desire Paths — Patterns in how the framework is actually used
+# Collected automatically by agents. Reviewed during verification retrospective.
+# When a pattern appears 3+ times, it becomes a candidate for framework evolution.
+# Desire paths are GLOBAL — they track framework usage across all milestones.
+desire_paths:
+  deviation_patterns: []               # Repeated Rule 1/2/3 deviations (same type, same area)
+    # - pattern: ""                    # e.g., "Rule 2: missing null checks in API handlers"
+    #   occurrences: 0
+    #   first_seen: null
+    #   last_seen: null
+
+  tier_overrides: []                   # User overriding auto-detected tier
+    # - detected: ""                   # What Forge detected
+    #   overridden_to: ""              # What user chose instead
+    #   reason: ""                     # Why (if stated)
+
+  skipped_steps: []                    # Steps users consistently skip or rush through
+    # - step: ""                       # e.g., "constitutional gate check"
+    #   skill: ""
+    #   times_skipped: 0
+
+  recurring_friction: []               # Same problem appearing across sessions
+    # - description: ""                # e.g., "Design system violations in form components"
+    #   occurrences: 0
+    #   related_files: []
+
+  agent_struggles: []                  # Tasks where agents consistently fail or need retries
+    # - task_type: ""                  # e.g., "Responsive layout implementation"
+    #   failure_pattern: ""
+    #   occurrences: 0
+
+  user_corrections: []                 # User correcting agent output in the same way repeatedly
+    # - correction: ""                 # e.g., "Always adds 'use client' directive"
+    #   occurrences: 0