From aa1cb908e6beaccb9cbfab67f916b7f78cb3bfa1 Mon Sep 17 00:00:00 2001
From: Tutitoos <developer@tutitoos.dev>
Date: Wed, 23 Sep 2026 12:30:39 +0200
Subject: [PATCH 1/2] chore: adopt FloowGitHub Project workflow

---
 .github/floowgithub.json     | 29 ++++++++++++++++++++++++++++-
 AGENTS.md                    |  1 +
 docs/content/git-workflow.md |  9 ++++++---
 3 files changed, 35 insertions(+), 4 deletions(-)

diff --git a/.github/floowgithub.json b/.github/floowgithub.json
index 39ecf68c..9e4ec995 100644
--- a/.github/floowgithub.json
+++ b/.github/floowgithub.json
@@ -3,5 +3,32 @@
   "branch_pattern": "^(feat|fix|docs|refactor|chore)/(\\d+)-[a-z0-9]+(?:-[a-z0-9]+)*$",
   "issue_required": true,
   "closing_keywords": ["Closes"],
-  "exactly_one_closing_reference": true
+  "exactly_one_closing_reference": true,
+  "project": {
+    "owner": "Tutitoos",
+    "number": 4,
+    "task_id_prefix": "TASK",
+    "status_field": "Status",
+    "task_link_field": "Parent Task",
+    "statuses": {
+      "backlog": "Backlog",
+      "in_progress": "In Progress",
+      "needs_fix": "Needs Fix",
+      "qa": "QA",
+      "completed": "Completed"
+    }
+  },
+  "tasks": {
+    "maximum_depth": 2,
+    "checklist_required": true,
+    "acceptance_criteria_required": true,
+    "validation_required": true,
+    "issues_required_for_code": true,
+    "synchronize_parent_checklist": true,
+    "synchronize_evidence": true
+  },
+  "worktrees": {
+    "one_active_per_issue": true,
+    "require_clean_before_removal": true
+  }
 }
diff --git a/AGENTS.md b/AGENTS.md
index 519065fa..83151f5e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -5,6 +5,7 @@ These instructions apply to the entire repository.
 ## Git and GitHub
 
 - Read `docs/content/git-workflow.md` and use the installed `$floowgithub` skill for issue, branch, commit, pull request, review, and merge work.
+- Use ATENEA Workflow (Tutitoos Project #4) for Project draft tasks. Link each delivery issue and PR to its owning task through `Parent Task`, and update checklist evidence and Kanban status as work progresses.
 - Use one primary issue per implementable branch and PR. Include exactly one matching `Closes #N`, except for bot dependency PRs and private security advisories.
 - Never commit directly to `main`. Create an isolated worktree from a verified `origin/main` and use `<category>/<issue>-<slug>` with `feat`, `fix`, `docs`, `refactor`, or `chore`.
 - Preserve a branch name explicitly required by an accepted plan. Link its issue in the PR instead of rewriting published history.
diff --git a/docs/content/git-workflow.md b/docs/content/git-workflow.md
index 243d78ec..ebd3d66c 100644
--- a/docs/content/git-workflow.md
+++ b/docs/content/git-workflow.md
@@ -5,11 +5,12 @@ weight: 42
 
 # Git and GitHub delivery
 
-ATENEA uses one primary GitHub issue for each reviewable implementation:
+ATENEA tracks work in [ATENEA Workflow](https://github.com/users/Tutitoos/projects/4). A Project draft task owns the acceptance checklist and may have one level of subtasks. Each reviewable implementation still uses one primary GitHub issue:
 
 ```text
-issue -> branch/worktree -> implementation -> validation -> commit -> push
-      -> pull request -> checks/review -> authorized merge -> installation
+Project task -> issue -> branch/worktree -> implementation -> validation
+             -> commit -> push -> pull request -> checks/review
+             -> authorized merge -> installation
 ```
 
 New branches use `<category>/<issue-number>-<slug>` with `feat`, `fix`, `docs`, `refactor`, or `chore`, start from a verified `origin/main`, and have one writer in an isolated worktree. A branch name explicitly fixed by an accepted earlier plan may remain unchanged when its PR records the exception and still links its primary issue.
@@ -19,3 +20,5 @@ Every non-bot PR targets `main`, includes exactly one `Closes #N`, states exact
 Review checks, formal reviews, issue comments, inline comments, and unresolved threads. Verify automated findings in code. Readiness requires successful required checks, satisfied acceptance criteria, no actionable thread, and an unchanged reviewed SHA. Never self-approve or bypass protection. Merge, installation, release, migration, and deployment are distinct effects.
 
 Use the installed `$floowgithub` skill for the operational workflow and deterministic snapshot checker. ATENEA's machine-readable policy lives in `.github/floowgithub.json`; project-specific validation commands remain in `AGENTS.md`.
+
+Project tasks use `Backlog`, `In Progress`, `Needs Fix`, `QA`, and `Completed`. Record the logical task ID in the `Parent Task` field of linked issues and PRs. Update checklist items only after checking current evidence. `Completed` requires finished subtasks, closed issues, merged PRs, successful checks, and final QA evidence; creating a PR does not complete the task.

From ab97e7c8e8a030840fbc89335d2ae16904238db1 Mon Sep 17 00:00:00 2001
From: Tutitoos <developer@tutitoos.dev>
Date: Wed, 23 Sep 2026 13:04:14 +0200
Subject: [PATCH 2/2] chore: make ATENEA issues the delivery tasks

---
 .github/floowgithub.json               | 34 +++++++-------------------
 .github/pull_request_template.md       |  5 ++--
 AGENTS.md                              |  6 ++---
 docs/content/git-workflow.md           | 16 ++++++------
 scripts/validate-floowgithub-policy.py | 10 ++++++--
 5 files changed, 31 insertions(+), 40 deletions(-)

diff --git a/.github/floowgithub.json b/.github/floowgithub.json
index 9e4ec995..13b8b5f4 100644
--- a/.github/floowgithub.json
+++ b/.github/floowgithub.json
@@ -2,31 +2,15 @@
   "base_branch": "main",
   "branch_pattern": "^(feat|fix|docs|refactor|chore)/(\\d+)-[a-z0-9]+(?:-[a-z0-9]+)*$",
   "issue_required": true,
-  "closing_keywords": ["Closes"],
-  "exactly_one_closing_reference": true,
-  "project": {
-    "owner": "Tutitoos",
-    "number": 4,
-    "task_id_prefix": "TASK",
-    "status_field": "Status",
-    "task_link_field": "Parent Task",
-    "statuses": {
-      "backlog": "Backlog",
-      "in_progress": "In Progress",
-      "needs_fix": "Needs Fix",
-      "qa": "QA",
-      "completed": "Completed"
-    }
-  },
-  "tasks": {
-    "maximum_depth": 2,
-    "checklist_required": true,
-    "acceptance_criteria_required": true,
-    "validation_required": true,
-    "issues_required_for_code": true,
-    "synchronize_parent_checklist": true,
-    "synchronize_evidence": true
-  },
+  "issue_checklist_required": true,
+  "reference_keywords": [
+    "Refs",
+    "Closes"
+  ],
+  "closing_keywords": [
+    "Closes"
+  ],
+  "exactly_one_issue_reference": true,
   "worktrees": {
     "one_active_per_issue": true,
     "require_clean_before_removal": true
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 461bcea3..f317a42c 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -1,6 +1,6 @@
 ## Related issue or private advisory
 
-Closes #<!-- exactly one primary issue; bot dependency PRs are exempt. For a private security advisory, remove this line and use GitHub's private advisory link without exposing it here. -->
+Refs #<!-- exactly one primary issue while work remains. Use Closes only when this merge completes the issue; bot dependency PRs are exempt. For a private security advisory, remove this line and use GitHub's private advisory link without exposing it here. -->
 
 ## Result
 
@@ -24,7 +24,8 @@ Closes #<!-- exactly one primary issue; bot dependency PRs are exempt. For a pri
 ## Checklist
 
 - [ ] One coherent scope and one primary issue
-- [ ] Branch and `Closes` agree, or an approved branch-name exception is explained
+- [ ] Branch and issue reference agree, or an approved branch-name exception is explained
+- [ ] `Closes` is used only if the issue checklist and QA are complete
 - [ ] Acceptance criteria are satisfied
 - [ ] No credentials, personal data, temporary evidence, or unintended files are included
 - [ ] Tests, documentation, and embedded dashboard assets are current
diff --git a/AGENTS.md b/AGENTS.md
index 83151f5e..562b19f8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,9 +4,9 @@ These instructions apply to the entire repository.
 
 ## Git and GitHub
 
-- Read `docs/content/git-workflow.md` and use the installed `$floowgithub` skill for issue, branch, commit, pull request, review, and merge work.
-- Use ATENEA Workflow (Tutitoos Project #4) for Project draft tasks. Link each delivery issue and PR to its owning task through `Parent Task`, and update checklist evidence and Kanban status as work progresses.
-- Use one primary issue per implementable branch and PR. Include exactly one matching `Closes #N`, except for bot dependency PRs and private security advisories.
+- Read `docs/content/git-workflow.md` and use the installed `$floowgithub` skill for issue, branch, commit, pull request, QA, and merge work.
+- Each issue is the task and owns its checklist, acceptance criteria, linked child issues, and PRs. Update checkboxes only against current evidence. QA includes code review, checks, and functional validation.
+- Use one primary issue per implementable branch and PR. Include exactly one matching `Refs #N` while work remains, or `Closes #N` only when the merge completes the issue; bot dependency PRs and private security advisories are exceptions.
 - Never commit directly to `main`. Create an isolated worktree from a verified `origin/main` and use `<category>/<issue>-<slug>` with `feat`, `fix`, `docs`, `refactor`, or `chore`.
 - Preserve a branch name explicitly required by an accepted plan. Link its issue in the PR instead of rewriting published history.
 - Keep one writer per worktree. Preserve user changes and never stash, reset, amend, rebase, force-push, or discard work you do not own.
diff --git a/docs/content/git-workflow.md b/docs/content/git-workflow.md
index ebd3d66c..4067a06e 100644
--- a/docs/content/git-workflow.md
+++ b/docs/content/git-workflow.md
@@ -5,20 +5,20 @@ weight: 42
 
 # Git and GitHub delivery
 
-ATENEA tracks work in [ATENEA Workflow](https://github.com/users/Tutitoos/projects/4). A Project draft task owns the acceptance checklist and may have one level of subtasks. Each reviewable implementation still uses one primary GitHub issue:
+Each GitHub issue is the task and owns its acceptance checklist, child issues, and linked pull requests:
 
 ```text
-Project task -> issue -> branch/worktree -> implementation -> validation
-             -> commit -> push -> pull request -> checks/review
-             -> authorized merge -> installation
+issue -> branch/worktree -> implementation -> validation
+      -> commit -> push -> pull request -> QA
+      -> authorized merge -> issue closure -> installation
 ```
 
 New branches use `<category>/<issue-number>-<slug>` with `feat`, `fix`, `docs`, `refactor`, or `chore`, start from a verified `origin/main`, and have one writer in an isolated worktree. A branch name explicitly fixed by an accepted earlier plan may remain unchanged when its PR records the exception and still links its primary issue.
 
-Every non-bot PR targets `main`, includes exactly one `Closes #N`, states exact validation and evidence levels, and identifies unrun checks. A private security advisory is the sole exception: keep its reference private, use GitHub's private advisory link, and do not create or mention a public issue. A check or review applies only to the head SHA it inspected. Every push restarts readiness review.
+Every non-bot PR targets `main`, links exactly one primary issue with `Refs #N` while work remains or `Closes #N` only when its merge completes the issue, states exact validation and evidence levels, and identifies unrun checks. A private security advisory is the sole exception: keep its reference private, use GitHub's private advisory link, and do not create or mention a public issue. QA evidence applies only to the head SHA it inspected. Every push restarts QA readiness.
 
-Review checks, formal reviews, issue comments, inline comments, and unresolved threads. Verify automated findings in code. Readiness requires successful required checks, satisfied acceptance criteria, no actionable thread, and an unchanged reviewed SHA. Never self-approve or bypass protection. Merge, installation, release, migration, and deployment are distinct effects.
+QA includes code review, automated checks, and functional validation. Inspect issue comments, inline comments, and unresolved threads; verify automated findings in code. Merge readiness requires successful required checks, satisfied relevant acceptance criteria, no actionable thread, and an unchanged reviewed SHA. Never self-approve or bypass protection. Merge, issue closure, installation, release, migration, and deployment are distinct effects.
 
-Use the installed `$floowgithub` skill for the operational workflow and deterministic snapshot checker. ATENEA's machine-readable policy lives in `.github/floowgithub.json`; project-specific validation commands remain in `AGENTS.md`.
+Use the installed `$floowgithub` skill for the operational workflow and deterministic snapshot checker. ATENEA's machine-readable policy lives in `.github/floowgithub.json`; repository-specific validation commands remain in `AGENTS.md`.
 
-Project tasks use `Backlog`, `In Progress`, `Needs Fix`, `QA`, and `Completed`. Record the logical task ID in the `Parent Task` field of linked issues and PRs. Update checklist items only after checking current evidence. `Completed` requires finished subtasks, closed issues, merged PRs, successful checks, and final QA evidence; creating a PR does not complete the task.
+Update an issue checklist item when its observable result has current evidence; reopen it if that evidence is invalidated. Close a parent issue only after its checklist, child issues, required PRs, and QA are complete. Creating or merging a PR alone does not complete the issue.
diff --git a/scripts/validate-floowgithub-policy.py b/scripts/validate-floowgithub-policy.py
index b38edbef..8f5d756e 100755
--- a/scripts/validate-floowgithub-policy.py
+++ b/scripts/validate-floowgithub-policy.py
@@ -36,10 +36,16 @@
                 errors.append("branch_pattern must reject master")
     if policy.get("issue_required") is not True:
         errors.append("ATENEA must require a primary issue")
+    if policy.get("issue_checklist_required") is not True:
+        errors.append("ATENEA must require an issue checklist")
+    if policy.get("reference_keywords") != ["Refs", "Closes"]:
+        errors.append("ATENEA must allow Refs and Closes issue references")
     if policy.get("closing_keywords") != ["Closes"]:
         errors.append("ATENEA must use the Closes keyword")
-    if policy.get("exactly_one_closing_reference") is not True:
-        errors.append("ATENEA must require exactly one closing reference")
+    if policy.get("exactly_one_issue_reference") is not True:
+        errors.append("ATENEA must require exactly one issue reference")
+    if "project" in policy or "tasks" in policy:
+        errors.append("ATENEA must not require GitHub Projects")
 
 if errors:
     print("\n".join(errors), file=sys.stderr)