feat(evolution): FKST Evolution first proof and control-plane decision logic

.fkst/evolution/changes/2026/80/802380a11ec7f5687ec9505b5f302c29ae517053.yaml

@@ -0,0 +1,81 @@
+# Semantic product change record (spec section 15).
+#
+# The source commit SHA is the identity; the path shard is derived from it
+# (section 15.2), so a record's location is always computable from its identity
+# alone. Reprocessing this commit updates this same file rather than adding
+# another record. Once merged the record is immutable except for schema
+# migration or correction of a demonstrable factual error.
+
+schemaVersion: 1
+sourceCommit: "802380a11ec7f5687ec9505b5f302c29ae517053"
+sourceParents:
+  - "05d718594cdc30c249a5ef41bff1636fc6320fd3"
+pullRequest:
+  number: 558
+  url: "https://github.com/ChronoAIProject/fkst-hosted/pull/558"
+  headCommit: "802380a11ec7f5687ec9505b5f302c29ae517053"
+
+classification: "product-change"
+summary: >-
+  Session owners can queue a work item onto a running session from the
+  dashboard, instead of hand-writing a labelled issue on GitHub.
+
+capabilities:
+  added:
+    - "cap_9d41"
+  changed: []
+  deprecated: []
+  # `removed` is reserved for a capability the product genuinely no longer
+  # offers. A false removal is a user-visible claim that generated release notes
+  # and the repository timeline will publish, so a non-empty list here requires
+  # human review (sections 14.2.2, 27.3). Renames, merges and splits use the
+  # relation lists below instead — encoding a merge as removals would publish
+  # "features removed" about a product that lost nothing.
+  removed: []
+  renamed: []
+  merged: []
+  split: []
+
+journeys:
+  added:
+    - "jny_2f7c"
+  changed: []
+  removed: []
+  renamed: []
+  merged: []
+  split: []
+
+artifactImpact:
+  documentation:
+    - "docs.queue-work-item"
+  skills:
+    - "skill.queue-work-item"
+  screenshots:
+    - "screenshot.sessions-level"
+    - "screenshot.work-composer"
+    - "screenshot.session-detail"
+  videos:
+    - "video.queue-work-item"
+  slides:
+    - "deck.product-intro"
+
+migrations: []
+
+limitations:
+  - >-
+    Authoring a work item requires being the session's effective creator, a
+    listed Session Collaborator, or a deployment global administrator.
+  - "The session's trigger issue must still be open."
+  - "The selected label must be one of the session's applicable work labels."
+
+evidence:
+  - kind: "pull-request"
+    ref: "#558"
+  - kind: "source"
+    ref: "backend/src/routes/canvas/work_item.rs"
+  - kind: "test"
+    ref: "frontend/e2e/dashboard.spec.ts"
+  - kind: "journey"
+    ref: ".fkst/evolution/journeys/queue-work-item.spec.ts"
+
+verification: "passed"

.fkst/evolution/config.yaml

@@ -0,0 +1,119 @@
+# FKST Evolution configuration for fkst-hosted.
+#
+# OWNER-CONTROLLED (section 12.3). Evolution reads this file and never writes
+# it: the section 25.8 confinement check rejects it in a sync PR unconditionally,
+# and section 13.3.1 makes clear that this file is an INPUT, not the safety
+# boundary — the boundary is a control-plane prefix comparison that nothing here
+# can widen.
+#
+# Spec: docs/evolution_temp_spec.md on branch `evolution-temp-spec`.
+
+schemaVersion: 1
+enabled: true
+
+source:
+  # Section 21.1 dynamic default-branch resolution. NOTE: the control plane
+  # cannot express this yet — `validate_branch_name`
+  # (backend/src/reconcile/branches.rs:43) permits only `[A-Za-z0-9._/-]` and so
+  # rejects `@`. Recorded here as the spec-correct value; see issue #5866.
+  branch: "@default"
+
+  # Paths that can plausibly change the PRODUCT SURFACE. This set drives cycle
+  # admission (section 17.5) and is REQUIRED — section 13.3 rejects an absent or
+  # empty set, and open question 40.16 defers the question of a defensible
+  # default to Phase 1 measurement rather than guessing one here.
+  #
+  # The asymmetry that shaped these entries: a too-broad set is merely expensive
+  # and visibly so, while a too-narrow one fails silently — the artifact that was
+  # never regenerated produces no signal and nobody files a bug for a thing that
+  # did not happen. So this errs wide within the two source trees and narrow
+  # outside them.
+  productRelevant:
+    include:
+      # The control plane: HTTP surface, reconciler, and session lifecycle.
+      - "backend/src/**"
+      # The SPA: every user-facing screen and its API client.
+      - "frontend/src/**"
+      - "frontend/index.html"
+      # Operator-facing skill manuals ship as product surface.
+      - "skills/**"
+    exclude:
+      # Tests describe behaviour but are not themselves product surface, and a
+      # test-only commit must not launch a media-rendering cycle. They remain
+      # COVERED below, and they remain evidence (section 14.2) — exclusion here
+      # is about cycle admission, not about ignoring them.
+      - "**/*_tests.rs"
+      - "**/*.test.ts"
+      - "**/*.test.tsx"
+      - "**/test_support.rs"
+      - "frontend/src/test/**"
+
+  # Everything else reachable on the trusted branch is COVERED for provenance
+  # but does not by itself launch a cycle (section 17.5). `.fkst/evolution/**`
+  # and `.fkst/packages/**` are removed unconditionally by section 17.3; the
+  # `**` below is understood to be taken after that removal.
+  coverage:
+    include:
+      - "**"
+    exclude:
+      - ".git/**"
+
+artifactRepository: "."
+
+intent:
+  product: ".fkst/evolution/intent/product.md"
+  overrides: ".fkst/evolution/intent/overrides.yaml"
+
+# Each entry selects a schema-FIXED subtree beneath .fkst/evolution/. There is no
+# path field: configuration can enable or disable a class, never relocate it
+# (section 13.3).
+managedOutputs:
+  documentation: { enabled: true }        # -> .fkst/evolution/docs/
+  skills:        { enabled: true }        # -> .fkst/evolution/skills/
+  journeys:      { enabled: true }        # -> .fkst/evolution/journeys/
+  screenshots:   { enabled: true }        # -> .fkst/evolution/screenshots/
+  slides:        { enabled: true }        # -> .fkst/evolution/slides/
+  video:         { enabled: true, storage: "github-release" }
+
+# Producer roles this deployment does not run (section 17.7.2). Empty: the first
+# proof exercises every role, so nothing may be excused from the required set.
+absentProducerRoles: []
+
+locales:
+  - "en"
+
+triggers:
+  pullRequestPreview: true
+  defaultBranchPush: true
+  releaseFullRebuild: true
+  debounceSeconds: 60
+
+publication:
+  # Bootstrap default (section 27.1). `automerge-managed` additionally requires
+  # accepting section 17.7.1's trust consequence — that corroboration is a
+  # controller TRANSCRIPTION of a sandbox-produced result, not independent
+  # observation — and that acceptance has not been made.
+  mode: "propose"
+  requireCurrentSource: true
+  requireChecks: true
+  allowDirectPush: false
+  onOwnerClose: "suppress-until-input-changes"
+  suppressionLabel: "fkst-evolution-suppressed"
+  maxRegenerationRounds: 5
+  cycleDeadlineSeconds: 3600
+
+drift:
+  # `block` during bootstrap (section 17.8). `repair` is defensible only after
+  # owners have explicitly accepted managed ownership of these subtrees.
+  policy: "block"
+
+generatorEpoch: 1
+
+retention:
+  renderedSnapshots: 10
+  preserveProductReleases: true
+
+security:
+  runPullRequestCode: false
+  allowProductionData: false
+  allowProductionCredentials: false

.fkst/evolution/docs/queue-work-item.md

@@ -0,0 +1,97 @@
+# Queue work for a running session
+
+> **Generated artifact** (`docs.queue-work-item`). Evolution regenerates this page
+> from the product model; edit the model or `intent/`, not this file.
+>
+> Capability `cap_9d41` · Journey `jny_2f7c` · Audience: session owner,
+> repository maintainer · Status: **available**
+
+A session works the issues you give it. This page covers the fastest way to give
+it one: queueing a work item from the dashboard, without hand-writing a labelled
+issue on GitHub.
+
+## Before you start
+
+You need all of the following. Each maps to a specific refusal, so if the button
+is not there or the request fails, the list below tells you which one you are
+missing.
+
+| Requirement | If it is missing |
+| --- | --- |
+| You are the session's **effective creator**, a login frozen under its **Session Collaborators**, or a **deployment global administrator** | `403` — repository admin or maintain permission alone is *not* work authority |
+| The session's **trigger issue is still open** | `409` |
+| The session exposes **at least one applicable work label**, and you pick one of them | `422` |
+| Your GitHub account can open issues on the repository | GitHub refuses the write; surfaced as `403` |
+
+## Queue the work item
+
+1. Open **Dashboard**. You see every account and repository where the fkst
+   GitHub App is installed.
+
+   ![The dashboard showing a repository's running sessions](../screenshots/sessions-level.png)
+
+2. Drill into an account, then a repository. Its running sessions are listed,
+   each backed by its trigger issue.
+
+3. Select the session you want to work, then choose **Add work item**.
+
+4. Fill in the composer.
+
+   ![The Queue work composer with a title, a work label and Markdown details](../screenshots/work-composer.png)
+
+   - **Title** — required. A blank title is rejected with `400`.
+   - **Work label** — the list is that session's *complete effective set*,
+     including labels discovered from its packages. Picking one is what makes
+     the new issue routable to this session and no other.
+   - **Details** — optional, and Markdown. Original whitespace is preserved,
+     because indentation is meaningful. Omitting it opens a body-less issue.
+
+5. Choose **Queue work item**.
+
+## What happens next
+
+The work issue is opened on GitHub **as you** — not as the App, and not as a
+service account. It is stamped with the label you selected and assigned so that
+the reconciler claims it for that session.
+
+From then on the ordinary session lifecycle applies: the session picks the item
+up, works it, and opens a pull request. You can follow that from the session's
+detail drawer.
+
+![A session's detail drawer showing health, phase and work items](../screenshots/session-detail.png)
+
+An open work-label issue keeps its session's pod alive until the issue is closed
+or its pull request merges. Merge or close finished work to let a session idle
+down.
+
+## Why the dashboard is not a second control plane
+
+Sessions are started, driven, and stopped through GitHub issues. This composer is
+a convenience over that protocol, not an alternative to it: it opens exactly the
+issue you would have written by hand, with the label and assignee already
+correct. Anything you can do here you can do from GitHub, and the result is
+identical.
+
+That matters because GitHub is the only durable record. The control plane keeps
+no database, so nothing you queue depends on this service staying available to be
+reconstructed.
+
+## Limits and caveats
+
+- **Nothing here guarantees an outcome.** A session produces candidate pull
+  requests for human review.
+- The label selector shows the session's *effective* labels at the moment the
+  session was read. If the session's packages changed since, reload before
+  queueing.
+- Work authority is enforced on every request, not just when the button renders.
+
+## Evidence
+
+This page's claims resolve to:
+
+- `backend/src/routes/canvas/work_item.rs` — the handler and its documented
+  `400` / `403` / `409` / `422` responses
+- `GET /openapi.json` — the live operation schema
+- `.fkst/evolution/journeys/queue-work-item.spec.ts` — the executable journey
+  that produced every screenshot above
+- `frontend/e2e/dashboard.spec.ts` — the product's own end-to-end coverage

.fkst/evolution/intent/overrides.yaml

@@ -0,0 +1,72 @@
+# Protected facts, terminology, and artifact rules (spec section 14.5).
+#
+# OWNER-CONTROLLED. Evolution reads this file and never writes it.
+#
+# A protected fact is one that cannot be reliably inferred from source. An
+# observed contradiction with any statement here MUST block publication of the
+# affected artifact and produce a clear review request — it is never silently
+# resolved in favour of the inference.
+
+schemaVersion: 1
+
+protectedFacts:
+  - id: "github-is-the-only-durable-store"
+    statement: >-
+      GitHub is the only durable system of record. The control plane keeps no
+      database; a complete loss of its process-local state does not lose work.
+    evidence: "CLAUDE.md"
+    owner: "product"
+
+  - id: "work-item-authority"
+    statement: >-
+      Only a session's effective creator, a login frozen under that session's
+      Session Collaborators, and deployment global administrators may author work
+      for it. Repository admin or maintain permission alone is not work
+      authority.
+    evidence: "backend/src/routes/canvas/work_item.rs"
+    owner: "security"
+
+  - id: "issues-are-the-only-control-surface"
+    statement: >-
+      Sessions are started, driven, and stopped through GitHub issues. The
+      dashboard's write actions are conveniences over that protocol, not a second
+      control plane.
+    evidence: "skills/fkst-control-plane-manual/SKILL.md"
+    owner: "product"
+
+  - id: "no-outcome-guarantee"
+    statement: >-
+      A session produces candidate pull requests for human review. The product
+      does not guarantee correct, complete, or mergeable output.
+    evidence: ".fkst/evolution/intent/product.md"
+    owner: "product"
+
+  - id: "engine-is-out-of-scope"
+    statement: >-
+      fkst-hosted contains no kernel-engine code and never changes engine
+      internals; that work lives upstream in fkst-substrate.
+    evidence: "CLAUDE.md"
+    owner: "product"
+
+terminology:
+  forbidden:
+    - "job"
+    - "agent instance"
+    - "ticket"
+  preferred:
+    "job": "session"
+    "run": "session"
+    "agent instance": "session"
+    "ticket": "work item"
+    "task": "work item"
+
+artifactRules:
+  # Section 27.3: claims marked regulated, legal, financial, or
+  # security-sensitive always require human review.
+  - match: ".fkst/evolution/slides/investor/**"
+    requiresHumanReview: true
+  - match: ".fkst/evolution/slides/internal/**"
+    requiresHumanReview: true
+  # Security-facing documentation makes claims a reader may rely on operationally.
+  - match: ".fkst/evolution/docs/security/**"
+    requiresHumanReview: true