From d56d7a827195e5cfd15ddf4e97e8d89b34ba4c1d Mon Sep 17 00:00:00 2001 From: Mike Clay Date: Thu, 23 Apr 2026 10:38:21 +0100 Subject: [PATCH 1/5] feat(work-package): DCO policy compatibility - Remove GPG resign infrastructure for branch commits (validate scan, strategic-review resign checkpoint/step, complete resign-artifact-commits, manage-git gpg-resign-range protocol) - Add squash merge detection in start-work-package (GitHub API) with squash_merge_available variable driving downstream DCO path - Add context_scope variable (repo-only|web-retrieval|mixed) set at end of research phase via new context-scope-declaration checkpoint - Add provenance-log.md artifact to implement; log-provenance step appends one row per task (model, prompt class, context scope, description) - Add Assisted-by commit trailer to manage-git code-commits protocol - Strengthen post-impl-review manual diff review: affirmative rationale confirmation replaces passive issue-flagging only - Add DCO sign-off blocking checkpoint in submit-for-review presenting the six-item DCO checklist before push - Add merge-strategy-reminder checkpoint instructing squash merge with signed commit (local git merge --squash flow for GPG verification) - Add AI Assistance section to PR description Final template Co-Authored-By: Claude Sonnet 4.6 --- .../activities/01-start-work-package.toon | 15 ++++-- work-package/activities/04-research.toon | 39 ++++++++++++-- work-package/activities/08-implement.toon | 21 ++++++-- .../activities/09-post-impl-review.toon | 42 +++++++++++---- work-package/activities/10-validate.toon | 20 ++----- .../activities/11-strategic-review.toon | 47 +++------------- .../activities/12-submit-for-review.toon | 54 ++++++++++++++++--- work-package/activities/13-complete.toon | 16 ++---- work-package/resources/12-pr-description.md | 9 ++++ work-package/skills/15-manage-git.toon | 14 +++-- work-package/workflow.toon | 17 +++--- 11 files changed, 178 insertions(+), 116 deletions(-) diff --git a/work-package/activities/01-start-work-package.toon b/work-package/activities/01-start-work-package.toon index e972be16..8a25f493 100644 --- a/work-package/activities/01-start-work-package.toon +++ b/work-package/activities/01-start-work-package.toon @@ -1,5 +1,5 @@ id: start-work-package -version: 3.3.0 +version: 3.4.0 name: Start Work Package description: "Initialize the work package: verify or create an issue, set up feature branch and draft PR, and create planning folder. Establishes traceability from requirements through implementation." problem: User needs to initialize a work package with issue tracking, branch, and PR @@ -19,7 +19,7 @@ entryActions[1]: message: Starting issue management skills: primary: meta/activity-worker -steps[20]: +steps[21]: - id: detect-review-mode name: Detect Review Mode description: "Check if user request indicates review of existing PR. If detected, set is_review_mode=true and prompt for PR reference." @@ -45,6 +45,14 @@ steps[20]: name: Initialize Target Directory description: "cd into target_path. Fetch origin and checkout the default branch (main/master). Pull latest. This ensures the target is at HEAD before creating a feature branch." skill: manage-git + - id: detect-merge-strategy + name: Detect Merge Strategy + description: "Call 'gh api repos/{owner}/{repo}' in target_path (resolve owner/repo from git remote get-url origin). Extract allow_squash_merge. Set squash_merge_available=true if allow_squash_merge is true, false otherwise. This drives the DCO merge path: squash-merge with signed merge commit when available, unsigned branch commits otherwise." + skill: github-cli-protocol + actions[1]: + - action: set + target: squash_merge_available + description: "true if allow_squash_merge=true in repo settings, false otherwise" - id: detect-project-type name: Detect Project Type description: "Auto-detect project type inside target_path: Check for Cargo.toml with Substrate dependencies (sp-*, frame-*, pallet-*). Set project_type to 'rust-substrate' if found, otherwise 'other'." @@ -484,7 +492,7 @@ outcome[5]: - Feature branch created from main - Draft PR created and linked to issue - Planning folder initialized -context_to_preserve[16]: +context_to_preserve[17]: - issue_number - The associated issue number (GitHub #N or Jira KEY-N) - issue_platform - github or jira - issue_type - Type of issue (feature, bug, task, enhancement, epic) @@ -501,3 +509,4 @@ context_to_preserve[16]: - jira_cloud_id - Atlassian cloud ID for subsequent Jira operations - github_issue_found - Whether a GitHub issue linked to the Jira ticket was found - github_issue_number - GitHub issue number linked to the Jira ticket (if found or created) + - squash_merge_available - Whether target repo allows squash merges (drives DCO merge path) diff --git a/work-package/activities/04-research.toon b/work-package/activities/04-research.toon index 791e2125..6e7c2d68 100644 --- a/work-package/activities/04-research.toon +++ b/work-package/activities/04-research.toon @@ -1,5 +1,5 @@ id: research -version: 2.3.2 +version: 2.4.0 name: Research description: "Research the knowledge base and external sources to discover best practices, patterns, and resources to inform the plan-prepare activity." problem: User needs to research best practices before planning @@ -11,7 +11,7 @@ required: false estimatedTime: 20-45m skills: primary: meta/activity-worker -steps[9]: +steps[10]: - id: kb-research name: Knowledge base research description: "Call get_guidance before making concept-rag MCP tool calls. Search for relevant patterns and practices." @@ -48,6 +48,14 @@ steps[9]: actions[1]: - action: message message: "**Resolved Assumptions** — the following assumptions were resolved through code analysis during this phase." + - id: declare-context-scope + name: Declare Context Scope + description: "Set context_scope based on whether web retrieval was used during research. If web-research step retrieved external content that informed design decisions or code generation, set context_scope to 'web-retrieval'. If only repository-local sources were used, set context_scope to 'repo-only'. If both were used, set context_scope to 'mixed'. This value flows into Assisted-by commit trailers and the provenance log." + checkpoint: context-scope-declaration + actions[1]: + - action: set + target: context_scope + description: "repo-only | web-retrieval | mixed based on research sources used" - id: interview-open-assumptions name: Interview open assumptions description: "For each open (stakeholder-dependent) assumption, present it individually to the user via the research-assumption-interview checkpoint. The user can resolve it inline or defer it to stakeholder review. Update the assumptions log after each response." @@ -88,7 +96,7 @@ artifacts[1]: - id: research-document name: kb-research.md location: planning -checkpoints[3]: +checkpoints[4]: - id: research-findings name: Research Findings Checkpoint message: "Here are the combined findings from knowledge base and web research. Proceeding in 30s unless you want changes." @@ -149,6 +157,31 @@ checkpoints[3]: effect: setVariable: assumption_deferred: true + - id: context-scope-declaration + name: Context Scope Declaration + message: "Did research use external web sources (web search, documentation URLs, external references)? This determines the provenance scope recorded in commit trailers and the provenance log." + blocking: false + defaultOption: repo-only + autoAdvanceMs: 15000 + options[3]: + - id: repo-only + label: "Repository only — no external web sources used" + description: All research was based on codebase and local knowledge (default) + effect: + setVariable: + context_scope: repo-only + - id: web-retrieval + label: "External web sources used for design decisions" + description: Web search, external docs, or third-party references informed the approach + effect: + setVariable: + context_scope: web-retrieval + - id: mixed + label: "Both repository and external sources used" + description: Mix of codebase analysis and external references + effect: + setVariable: + context_scope: mixed transitions[1]: - to: implementation-analysis isDefault: true diff --git a/work-package/activities/08-implement.toon b/work-package/activities/08-implement.toon index b6d71732..7d13c0ef 100644 --- a/work-package/activities/08-implement.toon +++ b/work-package/activities/08-implement.toon @@ -1,5 +1,5 @@ id: implement -version: 2.6.2 +version: 2.7.0 name: Implement Tasks description: "Execute the implementation plan task by task. Each task follows a cycle of implement → test → commit. Assumptions are collected during each task, reconciled through code analysis after all tasks complete, and only unresolvable assumptions are presented to the user." problem: User needs to implement the planned tasks @@ -11,12 +11,17 @@ required: true estimatedTime: 1-4h rules[1]: - "SYMBOL VERIFICATION: Every symbol introduced or referenced in code or documentation MUST have provenance — exists in codebase, in a declared dependency, or is newly created by the current task. Never fabricate symbols." -artifacts[1]: +artifacts[2]: - id: assumptions-log name: assumptions-log.md location: planning description: "Log of assumptions - continues from earlier phases (design-philosophy, requirements, research, analysis, planning)" action: update + - id: provenance-log + name: provenance-log.md + location: planning + description: "AI assistance provenance record. One row per task: task ID, model ID, prompt class (code-generation|refactoring|test-writing|docs), context_scope, and a one-line description of what was generated. Created on first task, appended on each subsequent task. Linked from PR description." + action: create entryActions[1]{action,target,message}: validate,branch,Verify on correct feature branch before any code changes skills: @@ -27,7 +32,7 @@ loops[3]: type: forEach variable: current_task over: plan.tasks - steps[5]: + steps[6]: - id: implement-task name: Implement task skill: implement-task @@ -38,6 +43,10 @@ loops[3]: - id: commit name: Commit changes skill: manage-git + - id: log-provenance + name: Log AI provenance + description: "Append a row to provenance-log.md for this task: | {current_task.id} | {model_id} | {prompt_class} | {context_scope} | {one-line description of what was generated} |. Create the file with a header row if this is the first task. prompt_class is one of: code-generation, refactoring, test-writing, docs, mixed." + skill: manage-artifacts - id: self-review name: Self-review description: "Perform task completion review: (1) Symbol verification — confirm all new/referenced symbols have provenance in codebase or dependencies; (2) Quality checks — code follows patterns, tests pass, no debug prints, no untracked TODOs. Use attached resource 14 for verification checklist." @@ -167,10 +176,12 @@ transitions[1]: isDefault: true exitActions[1]{action,message}: message,README PROGRESS: Update planning folder README.md — set Status to In Progress and mark implementation artifacts. -outcome[2]: +outcome[3]: - All tasks implemented - Changes committed -context_to_preserve[3]: + - Provenance log created (provenance-log.md) +context_to_preserve[4]: - completed_tasks - Tasks completed during implementation - assumptions - Assumptions made during implementation - commits - Commits created + - provenance_log_path - Path to provenance-log.md diff --git a/work-package/activities/09-post-impl-review.toon b/work-package/activities/09-post-impl-review.toon index 1062468d..afaa52e2 100644 --- a/work-package/activities/09-post-impl-review.toon +++ b/work-package/activities/09-post-impl-review.toon @@ -1,5 +1,5 @@ id: post-impl-review -version: 1.7.1 +version: 1.8.0 name: Post-Implementation Review description: "Review implementation quality regardless of whether code was newly written or adopted. Ensures code review, test suite review, and architecture summary are completed before validation." problem: User needs to review implementation quality before validation @@ -106,21 +106,45 @@ steps[7]: - action: set target: recommended_review_option description: "Set to the recommended review-findings option based on severity analysis" -checkpoints[3]: +checkpoints[4]: - id: file-index-table name: File Index Checkpoint - message: "File index written to {change_block_index_path}. Please review the diff in your side-by-side app using the index for reference, then provide row numbers for any files with issues (e.g., '24, 31, 106') or 'none' if all looks good." + message: "File index written to {change_block_index_path}. The index includes a rationale paragraph for each change block written by the agent. Please review the diff in your side-by-side app. Then: (1) confirm the rationale paragraphs are accurate (or note corrections), and (2) provide row numbers for any blocks with issues (e.g., '24, 31, 106') or 'none'. Your confirmation of the rationale serves as your provenance attestation for each change." blocking: true - options[2]: + options[3]: + - id: rationale-confirmed + label: "Rationale confirmed — no issues" + description: "Agent rationale paragraphs are accurate. All changes understood. Proceed with automated reviews." + - id: rationale-confirmed-with-issues + label: "Rationale confirmed (with corrections) — issues found" + description: "Provide corrections to any rationale paragraphs and comma-separated block indices with issues" + effect: + setVariable: + has_flagged_blocks: true - id: has-issues - label: Issues found - provide indices - description: Enter comma-separated list of block indices with issues + label: Issues found — rationale not yet reviewed + description: Enter comma-separated list of block indices with issues; rationale review deferred effect: setVariable: has_flagged_blocks: true - - id: no-issues - label: No issues found - description: All changes look good, proceed with automated reviews + - id: rationale-amendment + name: Rationale Amendment Checkpoint + condition: + type: simple + variable: has_flagged_blocks + operator: "==" + value: false + message: "Please provide any corrections to the agent rationale paragraphs in change-block-index.md, or confirm they are all accurate. Corrections are recorded in manual-diff-review-report.md as your provenance statement." + blocking: false + defaultOption: all-accurate + autoAdvanceMs: 20000 + options[2]: + - id: all-accurate + label: "All rationale paragraphs are accurate (default)" + description: No corrections needed — rationale confirmed as written + - id: provide-corrections + label: "Provide corrections to specific blocks" + description: Amend rationale paragraphs for one or more blocks - id: block-interview name: Block Interview Checkpoint condition: diff --git a/work-package/activities/10-validate.toon b/work-package/activities/10-validate.toon index e9c01b4e..dda2c8f8 100644 --- a/work-package/activities/10-validate.toon +++ b/work-package/activities/10-validate.toon @@ -1,5 +1,5 @@ id: validate -version: 2.5.0 +version: 2.6.0 name: Verify & Validate Design description: "Validate the implementation through testing and build verification. Test suite quality was already reviewed in implement phase." problem: User needs to validate the implementation passes all tests @@ -11,7 +11,7 @@ required: true estimatedTime: 15-30m skills: primary: meta/activity-worker -steps[9]: +steps[8]: - id: run-tests name: Run all tests description: "Execute unit, integration, e2e tests. Observe and record results." @@ -73,17 +73,6 @@ steps[9]: variable: has_failures operator: == value: true - - id: scan-commit-signatures-for-strategic - name: Scan PR commit signatures (preflight) - description: "In target_path, resolve MERGE_BASE against the default branch (try origin/main, origin/master, main, master in order). Run git log --format='%h %G? %s' MERGE_BASE..HEAD. If ANY line has %G? of N (no signature) or B (bad), set unsigned_commits_in_pr to true and populate unsigned_commit_list_summary with a concise list of affected commits; otherwise set unsigned_commits_in_pr to false and clear the summary. Review mode uses the same branch/PR under review. This runs before strategic-review so the orchestrator can resolve the unsigned-commits checkpoint with accurate state." - skill: manage-git - actions[2]: - - action: set - target: unsigned_commits_in_pr - message: "true if any commit in range has G? N or B; false if all commits good (G/U) or range empty" - - action: set - target: unsigned_commit_list_summary - message: "Comma-separated short lines (hash + subject) for unsigned/bad commits, or empty string if none" loops[1]: - id: fix-revalidate-cycle name: Fix and Revalidate Cycle @@ -115,10 +104,7 @@ exitActions[1]{action,message}: outcome[2]: - All tests passing - Build successful -context_to_preserve[6]: +context_to_preserve[3]: - test_results - Test execution results - build_status - Build success/failure status - validation_passed - Whether all validation checks passed - - unsigned_commits_in_pr - Whether unsigned/bad GPG commits exist in PR range - - unsigned_commit_list_summary - Summary for strategic-review checkpoint messaging - - resign_unsigned_commits_requested - Filled when user opts to re-sign at strategic review diff --git a/work-package/activities/11-strategic-review.toon b/work-package/activities/11-strategic-review.toon index 80dd18bf..b240c821 100644 --- a/work-package/activities/11-strategic-review.toon +++ b/work-package/activities/11-strategic-review.toon @@ -1,7 +1,7 @@ id: strategic-review -version: 2.5.1 +version: 2.6.0 name: Strategic Review -description: "Review the implementation to ensure changes are minimal and focused. Validates that the final PR contains only the changes required for the solution. Confirms GPG signatures on PR commits (with user consent before history rewrite) and ensures a changelog fragment exists when the target repo uses a root-level changes/ convention." +description: "Review the implementation to ensure changes are minimal and focused. Validates that the final PR contains only the changes required for the solution. Ensures a changelog fragment exists when the target repo uses a root-level changes/ convention." problem: User needs to ensure changes are minimal and focused recognition[3]: - strategic review @@ -20,21 +20,11 @@ artifacts[2]: name: "architecture-summary.md" location: planning description: "High-level architecture summary for management stakeholders. Uses UML-style diagrams (system context, package, sequence) to visualize changes. See architecture-summary resource for template." -steps[9]: +steps[8]: - id: diff-review name: Review diff description: "Examine all changes in the PR for scope and relevance" skill: review-strategy - checkpoint: unsigned-commits-prompt - - id: resign-unsigned-pr-commits - name: Re-sign unsigned commits - description: "Only when resign_unsigned_commits_requested is true. In target_path, rebase onto MERGE_BASE (same resolution as validate scan) and re-sign each commit: e.g. git rebase --exec 'git commit --amend --no-edit -S' MERGE_BASE (or equivalent interactive rebase) so every commit in MERGE_BASE..HEAD ends with a good GPG signature. Then git log --format='%h %G?' MERGE_BASE..HEAD to confirm no N/B remains. If push is required, use git push --force-with-lease. Set unsigned_commits_in_pr to false and resign_unsigned_commits_requested to false on success; document any failure in strategic-review-{n}.md." - skill: manage-git - condition: - type: simple - variable: resign_unsigned_commits_requested - operator: == - value: true - id: identify-artifacts name: Identify artifacts description: "Find investigation artifacts, over-engineering, orphaned infrastructure" @@ -77,29 +67,7 @@ steps[9]: - action: set target: recommended_strategic_option description: "Set to the recommended strategic review option based on findings analysis" -checkpoints[2]: - - id: unsigned-commits-prompt - name: Unsigned or unverified commits - message: "Preflight scan reports one or more commits without a valid GPG signature in this PR range: {unsigned_commit_list_summary}. Re-sign all unsigned commits now? This rewrites branch history and may require force-with-lease push." - condition: - type: simple - variable: unsigned_commits_in_pr - operator: == - value: true - blocking: true - options[2]: - - id: resign-all - label: Yes — re-sign all unsigned commits - description: Rewrites commits with GPG signatures using git rebase; confirm signing key is available - effect: - setVariable: - resign_unsigned_commits_requested: true - - id: decline-resign - label: No — proceed without re-signing - description: Keep history as-is; note unsigned commits in strategic-review documentation - effect: - setVariable: - resign_unsigned_commits_requested: false +checkpoints[1]: - id: review-findings name: Strategic Review Findings Checkpoint message: "Strategic review complete. Based on findings analysis, the recommended action is {recommended_strategic_option}. Auto-advancing in 30s." @@ -145,16 +113,13 @@ transitions[3]: isDefault: true exitActions[1]{action,message}: message,README PROGRESS: Update planning folder README.md — mark strategic review artifacts as ✅ Complete. -outcome[6]: +outcome[4]: - Changes validated as minimal and focused - Investigation artifacts and over-engineering removed - Review findings documented in strategic-review-{n}.md - Architecture summary created in architecture-summary.md for stakeholder communication - - PR commit GPG signature expectations addressed (resign completed or user declined with documentation) - Changelog fragment added when target repo uses root changes/ and none existed for this work -context_to_preserve[5]: +context_to_preserve[3]: - review_findings - Findings from strategic review - review_passed - Whether review passed - items_removed - List of items removed during cleanup - - unsigned_commits_in_pr - Whether any unsigned commits remained after strategic review - - resign_unsigned_commits_requested - Whether user requested resign at checkpoint diff --git a/work-package/activities/12-submit-for-review.toon b/work-package/activities/12-submit-for-review.toon index 210b735a..f4dad63a 100644 --- a/work-package/activities/12-submit-for-review.toon +++ b/work-package/activities/12-submit-for-review.toon @@ -1,5 +1,5 @@ id: submit-for-review -version: 1.1.0 +version: 1.2.0 name: Submit for Review description: "Push implementation, update PR, mark ready for review, then handle the review cycle. If review feedback requires significant changes, transition back to plan-prepare." problem: User needs to submit the PR for review and handle reviewer feedback @@ -14,7 +14,7 @@ entryActions[1]{action,message}: log,Submitting PR for review skills: primary: meta/activity-worker -steps[12]: +steps[13]: - id: consolidate-review-findings name: Consolidate Review Findings description: "Gather all findings from code review, test review, validation, and strategic review. Categorize by severity and type." @@ -51,10 +51,15 @@ steps[12]: variable: is_review_mode operator: "==" value: true - - id: verify-commit-signatures - name: Verify and sign commits - description: "BEFORE pushing, check all commits on the feature branch for GPG signatures. Run 'git log main...HEAD --format=\"%h %G? %s\"' in target_path. If ANY commit shows 'N' (no signature), the agent MUST rebase and sign them: 'git rebase --exec \"git commit --amend --no-edit -S\" main' followed by 'git push --force-with-lease'. This ensures all commits are verified before review. If the target repo's AGENTS.md requires signed commits, this step is mandatory." - skill: manage-git + - id: dco-sign-off + name: DCO Sign-off + description: "Present the DCO sign-off checkpoint to the human before pushing. Surface the provenance context: model used, context_scope, squash_merge_available, and commit count. The human must certify the DCO checklist before the PR is submitted. Record the attestation timestamp and human identity in provenance-log.md." + checkpoint: dco-sign-off + condition: + type: simple + variable: is_review_mode + operator: "!=" + value: true required: true - id: push-commits name: Push all commits @@ -74,6 +79,15 @@ steps[12]: variable: is_review_mode operator: "!=" value: true + - id: instruct-merge-strategy + name: Instruct Merge Strategy + description: "Present merge strategy guidance to the human. If squash_merge_available is true: instruct the human to merge using squash merge with 'git commit -s -S' (Signed-off-by + GPG) — note that GitHub web UI squash merges are not GPG-signed; use 'git merge --squash' locally for a fully signed merge commit. If squash_merge_available is false: note that branch commits are unsigned and will land on main as-is — no signing action required." + checkpoint: merge-strategy-reminder + condition: + type: simple + variable: is_review_mode + operator: "!=" + value: true - id: mark-ready name: Mark PR ready for review description: "Mark the draft PR as ready for review using gh pr ready." @@ -104,7 +118,33 @@ steps[12]: - action: set target: recommended_outcome description: "Set to the recommended review-outcome option based on comment analysis" -checkpoints[4]: +checkpoints[6]: + - id: dco-sign-off + name: DCO Sign-off + message: "Before pushing: please certify the Developer Certificate of Origin for this work package.\n\nProvenance context:\n- Model: {model_id}\n- Context scope: {context_scope}\n- Squash merge available: {squash_merge_available}\n- Provenance log: {provenance_log_path}\n\nCertify that you:\n1. Reviewed the entire diff and understand each material change\n2. Have the right to submit this contribution under the project's license\n3. Did not include code with unclear or incompatible provenance\n4. Can explain where the solution came from (your design, repo context, or approved references)\n5. Tests and linters have been run (or will run in CI)\n6. Are willing to take responsibility for defects and licensing issues in this patch" + blocking: true + options[2]: + - id: certify + label: "I certify all of the above — proceed" + description: "DCO attestation recorded. Timestamp and identity logged to provenance-log.md." + - id: flag-legal + label: "I have reservations — flag for legal review" + description: "Document concern in provenance-log.md before proceeding. Consider escalating to legal or OSS program review." + - id: merge-strategy-reminder + name: Merge Strategy Reminder + message: "PR is ready for review. Merge strategy guidance:\n\n**Squash merge available — use squash merge with signed commit.**\nTo get a GPG-signed + DCO-attested merge commit, merge locally:\n```\ngit checkout main && git pull\ngit merge --squash {branch_name}\ngit commit -s -S -m 'feat: description (#{pr_number})'\ngit push\n```\nNote: GitHub web UI squash merge is not GPG-signed. Use the local flow above for a verified commit.\n\nIf squash merge is not available on this repo, branch commits land as-is — no signing required." + condition: + type: simple + variable: squash_merge_available + operator: "==" + value: true + blocking: false + defaultOption: acknowledged + autoAdvanceMs: 20000 + options[1]: + - id: acknowledged + label: "Understood — will use squash merge with signed commit" + description: Proceed to mark PR ready for review - id: review-received name: Review Received Checkpoint message: "Has the PR received manual review feedback?" diff --git a/work-package/activities/13-complete.toon b/work-package/activities/13-complete.toon index 12140278..f0f9aaf4 100644 --- a/work-package/activities/13-complete.toon +++ b/work-package/activities/13-complete.toon @@ -1,5 +1,5 @@ id: complete -version: 1.3.0 +version: 1.4.0 name: Complete Work Package description: "After PR is merged, wrap up the work package: create ADR (if applicable), finalize documentation, conduct retrospective, update status, and prepare for next work package." problem: User needs to finalize all documentation and close out the work package after PR merge @@ -29,7 +29,7 @@ artifacts[4]: description: "PR review analysis document" skills: primary: meta/activity-worker -steps[10]: +steps[9]: - id: create-adr name: Create Architecture Decision Record description: "Create ADR at .engineering/artifacts/adr/ documenting the architectural decision, rationale, and alternatives." @@ -111,27 +111,17 @@ steps[10]: name: Update work package plan status description: "After PR merged, update work package plan status to reflect completion." skill: conduct-retrospective - - id: resign-artifact-commits - name: Re-sign all planning artifact commits - description: "Apply gpg-resign-range to the parent (engineering) repo to re-sign every unsigned artifact commit made during this work package. Resolve MERGE_BASE as the point where the current engineering branch diverged from its default branch. Run: git rebase --exec 'git commit --amend --no-edit -S' MERGE_BASE in the engineering repo root. Verify all commits show G with git log --format='%h %G? %s' MERGE_BASE..HEAD, then push with --force-with-lease. This converts the full unsigned artifact history to a signed history in one operation. Requires the GPG agent to be unlocked — the user is present at this stage for post-review work." - skill: manage-git - condition: - type: simple - variable: is_review_mode - operator: "!=" - value: true - id: select-next name: Select next work package description: "Identify and select next work package if applicable. Prepare context for transition." skill: conduct-retrospective exitActions[1]{action,message}: log,Work package workflow complete -outcome[6]: +outcome[5]: - ADR created and accepted (if moderate/complex) - Documentation finalized (test plan, COMPLETE.md, API docs) - Retrospective completed with lessons learned - Work package status updated - - All planning artifact commits re-signed via gpg-resign-range and force-pushed - Ready for next work package context_to_preserve[6]: - planning_folder_path - Path to this work package's planning folder (returned to parent workflow via returnedContext) diff --git a/work-package/resources/12-pr-description.md b/work-package/resources/12-pr-description.md index 50773dfb..e3e5612b 100644 --- a/work-package/resources/12-pr-description.md +++ b/work-package/resources/12-pr-description.md @@ -158,6 +158,15 @@ A well-written PR description serves multiple audiences: --- +## 🤖 AI Assistance + +- **Tool / Model:** claude / [model-id] +- **Context scope:** [repo-only | web-retrieval | mixed] +- **Prompt classes:** [code-generation, test-writing, refactoring, docs — list applicable] +- **Provenance log:** [link to provenance-log.md in engineering artifacts] + +--- + ## 📌 Submission Checklist - [x] Changes are backward-compatible (or flagged if breaking) diff --git a/work-package/skills/15-manage-git.toon b/work-package/skills/15-manage-git.toon index 53437c40..71adbf87 100644 --- a/work-package/skills/15-manage-git.toon +++ b/work-package/skills/15-manage-git.toon @@ -1,5 +1,5 @@ id: manage-git -version: 1.4.0 +version: 1.5.0 capability: Manage git operations — branching, PR lifecycle, and branch synchronization description: "Handles git branch management, PR creation/updates via gh CLI, and branch synchronization. All git operations are performed INSIDE target_path. Branches and PRs are created against the target's upstream." @@ -31,17 +31,15 @@ protocol: - Fetch and rebase/merge from main to keep branch current - Resolve merge conflicts if any - Sync before pushing to avoid conflicts + code-commits[2]: + - "Append 'Assisted-by: claude:{model_id} [{context_scope}]' as a trailer on all code commits (not artifact commits). Use git commit -m $'subject\n\nAssisted-by: claude:{model_id} [{context_scope}]'" + - "context_scope is the workflow variable set during research: repo-only | web-retrieval | mixed" push-commits[2]: - Push all local commits to remote - Verify push succeeded - gpg-resign-range[3]: - - Resolve MERGE_BASE against default branch (same order as validate strategic preflight) - - Re-sign each commit in MERGE_BASE..HEAD via rebase --exec 'git commit --amend --no-edit -S' (GPG); ensure user.signingkey and gpg agent are available - - After rewrite, verify with git log --format='%h %G?' MERGE_BASE..HEAD; push with --force-with-lease only when appropriate for the PR branch - artifact-commits[3]: - - "ALL planning artifact commits to the parent (engineering) repo MUST use --no-gpg-sign: git add && git commit --no-gpg-sign -m 'docs(work-package): artifacts for ' && git push origin " + artifact-commits[2]: + - "git add && git commit -m 'docs(work-package): artifacts for ' && git push origin " - "Commit after each workflow activity completes. Use the message pattern: docs(work-package): artifacts for " - - "The --no-gpg-sign flag is mandatory on all intermediate artifact commits so the workflow can proceed unattended without a GPG pinentry prompt. At completion, resign-artifact-commits in the complete activity re-signs the full history via gpg-resign-range" output[1]: - id: branch-and-pr diff --git a/work-package/workflow.toon b/work-package/workflow.toon index 06ebb0ad..05d01444 100644 --- a/work-package/workflow.toon +++ b/work-package/workflow.toon @@ -1,6 +1,6 @@ "$schema": ../../schemas/workflow.schema.json id: work-package -version: 3.7.0 +version: 3.8.0 title: Work Package Implementation Workflow description: "Defines how to plan and implement ONE work package from inception to merged PR. A work package is a discrete unit of work such as a feature, bug-fix, enhancement, refactoring, or any other deliverable change. For multiple related work packages, use work-packages.toon to create a roadmap first." author: m2ux @@ -45,7 +45,7 @@ modes[1]: defaults: needs_elicitation: false resource: resources/24-review-mode.md -variables[70]: +variables[69]: - name: target_path type: string description: "Path to the target directory for this work package (e.g., a submodule, standalone repo, or monorepo subdirectory). All git operations (branch, PR) are performed inside this directory. Resolved by start-workflow discover-target checkpoints." @@ -290,17 +290,14 @@ variables[70]: - name: recommended_strategic_option type: string description: "Agent-recommended action after strategic review analysis (fix-findings|acceptable). Set by analyze-strategic-findings step." - - name: unsigned_commits_in_pr + - name: squash_merge_available type: boolean - description: "True when any commit in merge-base..HEAD has no valid GPG signature (%G? N or B). Set during validate (pre-strategic scan) so strategic-review can gate resign consent before the worker runs." + description: "True when the target repo allows squash merges (allow_squash_merge=true from GitHub API). Detected during start-work-package. Drives DCO merge strategy: squash-merge path when true, unsigned-commit path when false." defaultValue: false - - name: resign_unsigned_commits_requested - type: boolean - description: "User chose to re-sign unsigned commits at the strategic-review checkpoint. Drives the resign-unsigned-pr-commits step." - defaultValue: false - - name: unsigned_commit_list_summary + - name: context_scope type: string - description: "Short human-readable summary of unsigned or bad-signature commits (e.g. hashes and subjects) for checkpoint messaging." + description: "Provenance scope of AI-generated code in this work package. Set during research phase. Values: repo-only (all context from repository), web-retrieval (web sources used), mixed (both). Used in Assisted-by commit trailers and provenance log." + defaultValue: repo-only - name: recommended_outcome type: string description: "Agent-recommended PR review outcome (approved|minor-changes|significant-changes). Set by analyze-review-outcome step." From 6ab3d66c091e4d540f9450be242fdc0ce9556bcb Mon Sep 17 00:00:00 2001 From: Mike Clay Date: Thu, 23 Apr 2026 10:48:26 +0100 Subject: [PATCH 2/5] refactor(work-package): move DCO methodology from descriptions to skills MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Move implementation methodology out of activity step description prose into referenced skills, following the workflow convention that descriptions state WHAT and skills contain HOW. - Add skill 24-dco-provenance: provenance log schema, attestation recording protocol, and context scope classification - Add detect-merge-strategy and squash-merge-instruction protocols to manage-git skill - detect-merge-strategy step now references manage-git (was github-cli-protocol) - declare-context-scope, log-provenance, dco-sign-off, instruct-merge-strategy steps: trimmed descriptions to declarative-only, added skill references - Update skills README: count 24→25, skill 15 description, add skill 24 row Co-Authored-By: Claude Sonnet 4.6 --- .../activities/01-start-work-package.toon | 4 +-- work-package/activities/04-research.toon | 3 +- work-package/activities/08-implement.toon | 4 +-- .../activities/12-submit-for-review.toon | 6 ++-- work-package/skills/15-manage-git.toon | 9 ++++++ work-package/skills/24-dco-provenance.toon | 29 +++++++++++++++++++ work-package/skills/README.md | 5 ++-- 7 files changed, 51 insertions(+), 9 deletions(-) create mode 100644 work-package/skills/24-dco-provenance.toon diff --git a/work-package/activities/01-start-work-package.toon b/work-package/activities/01-start-work-package.toon index 8a25f493..c2f769ea 100644 --- a/work-package/activities/01-start-work-package.toon +++ b/work-package/activities/01-start-work-package.toon @@ -47,8 +47,8 @@ steps[21]: skill: manage-git - id: detect-merge-strategy name: Detect Merge Strategy - description: "Call 'gh api repos/{owner}/{repo}' in target_path (resolve owner/repo from git remote get-url origin). Extract allow_squash_merge. Set squash_merge_available=true if allow_squash_merge is true, false otherwise. This drives the DCO merge path: squash-merge with signed merge commit when available, unsigned branch commits otherwise." - skill: github-cli-protocol + description: "Detect whether the target repo permits squash merges. Sets squash_merge_available for downstream DCO merge path routing." + skill: manage-git actions[1]: - action: set target: squash_merge_available diff --git a/work-package/activities/04-research.toon b/work-package/activities/04-research.toon index 6e7c2d68..b9922016 100644 --- a/work-package/activities/04-research.toon +++ b/work-package/activities/04-research.toon @@ -50,7 +50,8 @@ steps[10]: message: "**Resolved Assumptions** — the following assumptions were resolved through code analysis during this phase." - id: declare-context-scope name: Declare Context Scope - description: "Set context_scope based on whether web retrieval was used during research. If web-research step retrieved external content that informed design decisions or code generation, set context_scope to 'web-retrieval'. If only repository-local sources were used, set context_scope to 'repo-only'. If both were used, set context_scope to 'mixed'. This value flows into Assisted-by commit trailers and the provenance log." + description: "Classify the provenance scope of this work package's research sources. Sets context_scope for Assisted-by commit trailers and the provenance log." + skill: dco-provenance checkpoint: context-scope-declaration actions[1]: - action: set diff --git a/work-package/activities/08-implement.toon b/work-package/activities/08-implement.toon index 7d13c0ef..7cbe8b83 100644 --- a/work-package/activities/08-implement.toon +++ b/work-package/activities/08-implement.toon @@ -45,8 +45,8 @@ loops[3]: skill: manage-git - id: log-provenance name: Log AI provenance - description: "Append a row to provenance-log.md for this task: | {current_task.id} | {model_id} | {prompt_class} | {context_scope} | {one-line description of what was generated} |. Create the file with a header row if this is the first task. prompt_class is one of: code-generation, refactoring, test-writing, docs, mixed." - skill: manage-artifacts + description: "Append a provenance record for this task to provenance-log.md." + skill: dco-provenance - id: self-review name: Self-review description: "Perform task completion review: (1) Symbol verification — confirm all new/referenced symbols have provenance in codebase or dependencies; (2) Quality checks — code follows patterns, tests pass, no debug prints, no untracked TODOs. Use attached resource 14 for verification checklist." diff --git a/work-package/activities/12-submit-for-review.toon b/work-package/activities/12-submit-for-review.toon index f4dad63a..5f918a9e 100644 --- a/work-package/activities/12-submit-for-review.toon +++ b/work-package/activities/12-submit-for-review.toon @@ -53,7 +53,8 @@ steps[13]: value: true - id: dco-sign-off name: DCO Sign-off - description: "Present the DCO sign-off checkpoint to the human before pushing. Surface the provenance context: model used, context_scope, squash_merge_available, and commit count. The human must certify the DCO checklist before the PR is submitted. Record the attestation timestamp and human identity in provenance-log.md." + description: "Gate PR submission on human DCO attestation. Records attestation in provenance-log.md." + skill: dco-provenance checkpoint: dco-sign-off condition: type: simple @@ -81,7 +82,8 @@ steps[13]: value: true - id: instruct-merge-strategy name: Instruct Merge Strategy - description: "Present merge strategy guidance to the human. If squash_merge_available is true: instruct the human to merge using squash merge with 'git commit -s -S' (Signed-off-by + GPG) — note that GitHub web UI squash merges are not GPG-signed; use 'git merge --squash' locally for a fully signed merge commit. If squash_merge_available is false: note that branch commits are unsigned and will land on main as-is — no signing action required." + description: "Present merge strategy guidance based on squash_merge_available. Instructs human on the correct merge procedure for a DCO-compliant merge commit." + skill: manage-git checkpoint: merge-strategy-reminder condition: type: simple diff --git a/work-package/skills/15-manage-git.toon b/work-package/skills/15-manage-git.toon index 71adbf87..2184eadf 100644 --- a/work-package/skills/15-manage-git.toon +++ b/work-package/skills/15-manage-git.toon @@ -34,6 +34,15 @@ protocol: code-commits[2]: - "Append 'Assisted-by: claude:{model_id} [{context_scope}]' as a trailer on all code commits (not artifact commits). Use git commit -m $'subject\n\nAssisted-by: claude:{model_id} [{context_scope}]'" - "context_scope is the workflow variable set during research: repo-only | web-retrieval | mixed" + detect-merge-strategy[3]: + - "Resolve owner/repo from git remote get-url origin in target_path (convert SSH to HTTPS if needed, strip .git suffix)" + - "Call: gh api repos/{owner}/{repo} --jq '{allow_squash_merge}'" + - "Set squash_merge_available=true if allow_squash_merge is true; false otherwise" + squash-merge-instruction[4]: + - "GitHub web UI squash merges do not produce GPG-signed commits — use the local flow for a signed merge commit" + - "Checkout and update default branch: git checkout {default_branch} && git pull" + - "Squash all branch commits: git merge --squash {branch_name}" + - "Commit with Signed-off-by and GPG signature: git commit -s -S -m '{type}: {description} (#{pr_number})' then git push" push-commits[2]: - Push all local commits to remote - Verify push succeeded diff --git a/work-package/skills/24-dco-provenance.toon b/work-package/skills/24-dco-provenance.toon new file mode 100644 index 00000000..4b0af753 --- /dev/null +++ b/work-package/skills/24-dco-provenance.toon @@ -0,0 +1,29 @@ +id: dco-provenance +version: 1.0.0 +capability: DCO compliance and AI provenance tracking — provenance log, attestation recording, and context scope management + +description: "Manages Developer Certificate of Origin (DCO) compliance artifacts and AI provenance records for a work package. Handles provenance-log.md creation and maintenance, DCO attestation recording, and context scope classification." + +protocol: + provenance-log[4]: + - "Schema: markdown table with columns | Task ID | Model | Prompt Class | Context Scope | Description |" + - "On first task create the file with header row: | Task ID | Model | Prompt Class | Context Scope | Description |\n|---|---|---|---|---|" + - "Append one row per task: current_task.id, model_id, prompt_class, context_scope variable, one-line description of what was generated" + - "Prompt class values: code-generation | refactoring | test-writing | docs | mixed" + record-attestation[3]: + - "Append an '## Attestation' section to provenance-log.md with: ISO 8601 timestamp, certifier identity from git config user.name/user.email, and the option selected (certify | flag-legal)" + - "If flag-legal selected, include a 'Legal Review Note' field with the concern text provided by the user" + - "Do not record attestation until the human explicitly selects the certify or flag-legal option at the dco-sign-off checkpoint" + context-scope[3]: + - "repo-only: all research and code generation used only repository-local sources (codebase, git history, local knowledge)" + - "web-retrieval: external web sources were accessed during research that informed design decisions or code patterns" + - "mixed: both repository-local and external web sources contributed to the implementation" + +output[1]: + - id: provenance-record + description: "provenance-log.md updated with task entry or attestation record" + +errors: + log_not_found: + cause: provenance-log.md does not exist when appending + recovery: Create file with header row, then append diff --git a/work-package/skills/README.md b/work-package/skills/README.md index bfcea912..ba1319bc 100644 --- a/work-package/skills/README.md +++ b/work-package/skills/README.md @@ -2,7 +2,7 @@ > Part of the [Work Package Implementation Workflow](../README.md) -## Skills (24 workflow-specific + 6 cross-workflow) +## Skills (25 workflow-specific + 6 cross-workflow) The workflow uses 24 workflow-specific skills organized by capability, plus 6 cross-workflow skill references. Universal meta skills are auto-included on the first `get_skills` call. Skills are referenced by activities through `primary` and `supporting` roles. @@ -23,7 +23,7 @@ The workflow uses 24 workflow-specific skills organized by capability, plus 6 cr | 12 | `review-strategy` | Strategic review ensuring minimal and focused changes | Strategic Review | | 13 | `review-assumptions` | Assumption collection, classification, and structured review | All planning and implementation activities | | 14 | `manage-artifacts` | Planning folder creation and artifact numbering management | Start Work Package, Requirements Elicitation, Implementation Analysis | -| 15 | `manage-git` | Git branching, PR lifecycle, branch sync, GPG re-sign | Start Work Package, Implement, Validate, Strategic Review | +| 15 | `manage-git` | Git branching, PR lifecycle, branch sync, merge strategy detection, squash merge instruction | Start Work Package, Implement, Submit for Review | | 16 | `validate-build` | Test execution, build verification, lint checking | Validate, Implement | | 17 | `finalize-documentation` | ADR updates, test plan finalization, COMPLETE.md creation | Complete | | 18 | `update-pr` | PR description update, push commits, mark ready for review | Submit for Review | @@ -32,6 +32,7 @@ The workflow uses 24 workflow-specific skills organized by capability, plus 6 cr | 21 | `create-adr` | Architecture Decision Record creation for significant decisions | Complete | | 22 | `build-comprehension` | Codebase comprehension via hierarchical analysis and persistent knowledge artifacts | Codebase Comprehension | | 23 | `reconcile-assumptions` | Iterative assumption reconciliation through targeted code analysis | Design Philosophy, Requirements Elicitation, Research, Implementation Analysis, Plan & Prepare, Implement | +| 24 | `dco-provenance` | DCO compliance and AI provenance tracking — provenance log, attestation recording, context scope | Research, Implement, Submit for Review | > Skills `11-activity-worker`, `meta-orchestrator`, `workflow-orchestrator`, and `activity-worker` are **universal skills** in [meta/skills/](../../meta/skills/). They provide the core orchestration and execution protocols used across all workflows. From 396607c2dcfea041c7ab2c59d495c6089dc3daf7 Mon Sep 17 00:00:00 2001 From: Mike Clay Date: Thu, 23 Apr 2026 10:55:35 +0100 Subject: [PATCH 3/5] =?UTF-8?q?fix(work-package):=20generalise=20AI=20tool?= =?UTF-8?q?=20references=20=E2=80=94=20remove=20hardcoded=20claude?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Assisted-by trailer, provenance log schema, and PR description template now use {tool}/{model_id} placeholders rather than hardcoding claude, to support any AI assistant (claude, gpt, gemini, etc.). Co-Authored-By: Claude Sonnet 4.6 --- work-package/resources/12-pr-description.md | 2 +- work-package/skills/15-manage-git.toon | 2 +- work-package/skills/24-dco-provenance.toon | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/work-package/resources/12-pr-description.md b/work-package/resources/12-pr-description.md index e3e5612b..4f41fde6 100644 --- a/work-package/resources/12-pr-description.md +++ b/work-package/resources/12-pr-description.md @@ -160,7 +160,7 @@ A well-written PR description serves multiple audiences: ## 🤖 AI Assistance -- **Tool / Model:** claude / [model-id] +- **Tool / Model:** [tool] / [model-id] - **Context scope:** [repo-only | web-retrieval | mixed] - **Prompt classes:** [code-generation, test-writing, refactoring, docs — list applicable] - **Provenance log:** [link to provenance-log.md in engineering artifacts] diff --git a/work-package/skills/15-manage-git.toon b/work-package/skills/15-manage-git.toon index 2184eadf..afbd2b93 100644 --- a/work-package/skills/15-manage-git.toon +++ b/work-package/skills/15-manage-git.toon @@ -32,7 +32,7 @@ protocol: - Resolve merge conflicts if any - Sync before pushing to avoid conflicts code-commits[2]: - - "Append 'Assisted-by: claude:{model_id} [{context_scope}]' as a trailer on all code commits (not artifact commits). Use git commit -m $'subject\n\nAssisted-by: claude:{model_id} [{context_scope}]'" + - "Append 'Assisted-by: {tool}:{model_id} [{context_scope}]' as a trailer on all code commits (not artifact commits). Use git commit -m $'subject\n\nAssisted-by: {tool}:{model_id} [{context_scope}]'. {tool} is the name of the AI assistant (e.g. claude, gpt, gemini); {model_id} is the specific model version." - "context_scope is the workflow variable set during research: repo-only | web-retrieval | mixed" detect-merge-strategy[3]: - "Resolve owner/repo from git remote get-url origin in target_path (convert SSH to HTTPS if needed, strip .git suffix)" diff --git a/work-package/skills/24-dco-provenance.toon b/work-package/skills/24-dco-provenance.toon index 4b0af753..c31a53d3 100644 --- a/work-package/skills/24-dco-provenance.toon +++ b/work-package/skills/24-dco-provenance.toon @@ -6,9 +6,9 @@ description: "Manages Developer Certificate of Origin (DCO) compliance artifacts protocol: provenance-log[4]: - - "Schema: markdown table with columns | Task ID | Model | Prompt Class | Context Scope | Description |" - - "On first task create the file with header row: | Task ID | Model | Prompt Class | Context Scope | Description |\n|---|---|---|---|---|" - - "Append one row per task: current_task.id, model_id, prompt_class, context_scope variable, one-line description of what was generated" + - "Schema: markdown table with columns | Task ID | Tool | Model | Prompt Class | Context Scope | Description |" + - "On first task create the file with header row: | Task ID | Tool | Model | Prompt Class | Context Scope | Description |\n|---|---|---|---|---|---|" + - "Append one row per task: current_task.id, tool name (e.g. claude, gpt, gemini), model_id, prompt_class, context_scope variable, one-line description of what was generated" - "Prompt class values: code-generation | refactoring | test-writing | docs | mixed" record-attestation[3]: - "Append an '## Attestation' section to provenance-log.md with: ISO 8601 timestamp, certifier identity from git config user.name/user.email, and the option selected (certify | flag-legal)" From 31c2811715fbb86551f98f2e92107eea0a3986c8 Mon Sep 17 00:00:00 2001 From: Mike Clay Date: Thu, 23 Apr 2026 10:56:46 +0100 Subject: [PATCH 4/5] fix(work-package): rename 'tool' to 'assistant' in provenance references Co-Authored-By: Claude Sonnet 4.6 --- work-package/resources/12-pr-description.md | 2 +- work-package/skills/15-manage-git.toon | 2 +- work-package/skills/24-dco-provenance.toon | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/work-package/resources/12-pr-description.md b/work-package/resources/12-pr-description.md index 4f41fde6..44f66c14 100644 --- a/work-package/resources/12-pr-description.md +++ b/work-package/resources/12-pr-description.md @@ -160,7 +160,7 @@ A well-written PR description serves multiple audiences: ## 🤖 AI Assistance -- **Tool / Model:** [tool] / [model-id] +- **Assistant / Model:** [assistant] / [model-id] - **Context scope:** [repo-only | web-retrieval | mixed] - **Prompt classes:** [code-generation, test-writing, refactoring, docs — list applicable] - **Provenance log:** [link to provenance-log.md in engineering artifacts] diff --git a/work-package/skills/15-manage-git.toon b/work-package/skills/15-manage-git.toon index afbd2b93..bd21d3e7 100644 --- a/work-package/skills/15-manage-git.toon +++ b/work-package/skills/15-manage-git.toon @@ -32,7 +32,7 @@ protocol: - Resolve merge conflicts if any - Sync before pushing to avoid conflicts code-commits[2]: - - "Append 'Assisted-by: {tool}:{model_id} [{context_scope}]' as a trailer on all code commits (not artifact commits). Use git commit -m $'subject\n\nAssisted-by: {tool}:{model_id} [{context_scope}]'. {tool} is the name of the AI assistant (e.g. claude, gpt, gemini); {model_id} is the specific model version." + - "Append 'Assisted-by: {assistant}:{model_id} [{context_scope}]' as a trailer on all code commits (not artifact commits). Use git commit -m $'subject\n\nAssisted-by: {assistant}:{model_id} [{context_scope}]'. {assistant} is the name of the AI assistant name (e.g. claude, gpt, gemini); {model_id} is the specific model version." - "context_scope is the workflow variable set during research: repo-only | web-retrieval | mixed" detect-merge-strategy[3]: - "Resolve owner/repo from git remote get-url origin in target_path (convert SSH to HTTPS if needed, strip .git suffix)" diff --git a/work-package/skills/24-dco-provenance.toon b/work-package/skills/24-dco-provenance.toon index c31a53d3..23efa235 100644 --- a/work-package/skills/24-dco-provenance.toon +++ b/work-package/skills/24-dco-provenance.toon @@ -6,9 +6,9 @@ description: "Manages Developer Certificate of Origin (DCO) compliance artifacts protocol: provenance-log[4]: - - "Schema: markdown table with columns | Task ID | Tool | Model | Prompt Class | Context Scope | Description |" - - "On first task create the file with header row: | Task ID | Tool | Model | Prompt Class | Context Scope | Description |\n|---|---|---|---|---|---|" - - "Append one row per task: current_task.id, tool name (e.g. claude, gpt, gemini), model_id, prompt_class, context_scope variable, one-line description of what was generated" + - "Schema: markdown table with columns | Task ID | Assistant | Model | Prompt Class | Context Scope | Description |" + - "On first task create the file with header row: | Task ID | Assistant | Model | Prompt Class | Context Scope | Description |\n|---|---|---|---|---|---|" + - "Append one row per task: current_task.id, assistant name (e.g. claude, gpt, gemini), model_id, prompt_class, context_scope variable, one-line description of what was generated" - "Prompt class values: code-generation | refactoring | test-writing | docs | mixed" record-attestation[3]: - "Append an '## Attestation' section to provenance-log.md with: ISO 8601 timestamp, certifier identity from git config user.name/user.email, and the option selected (certify | flag-legal)" From cc4700f8ebc2c1e8fcffd8d8c1eae2031168fcf5 Mon Sep 17 00:00:00 2001 From: Mike Clay Date: Thu, 23 Apr 2026 11:01:20 +0100 Subject: [PATCH 5/5] fix(work-package): replace Assisted-by with Co-authored-by; harness-aware protocol Co-authored-by is the GitHub-compatible standard trailer that produces the 'X and Y committed' byline. The code-commits protocol now documents per-assistant harness behaviour to prevent double-injection: Claude Code auto-adds the trailer so the agent must not add it again; other assistants that do not auto-inject must add it explicitly. Cleans up two stale Assisted-by references in variable descriptions. Co-Authored-By: Claude Sonnet 4.6 --- work-package/activities/04-research.toon | 2 +- work-package/skills/15-manage-git.toon | 9 +++++---- work-package/workflow.toon | 2 +- 3 files changed, 7 insertions(+), 6 deletions(-) diff --git a/work-package/activities/04-research.toon b/work-package/activities/04-research.toon index b9922016..a822f36a 100644 --- a/work-package/activities/04-research.toon +++ b/work-package/activities/04-research.toon @@ -50,7 +50,7 @@ steps[10]: message: "**Resolved Assumptions** — the following assumptions were resolved through code analysis during this phase." - id: declare-context-scope name: Declare Context Scope - description: "Classify the provenance scope of this work package's research sources. Sets context_scope for Assisted-by commit trailers and the provenance log." + description: "Classify the provenance scope of this work package's research sources. Sets context_scope for the provenance log and PR description." skill: dco-provenance checkpoint: context-scope-declaration actions[1]: diff --git a/work-package/skills/15-manage-git.toon b/work-package/skills/15-manage-git.toon index bd21d3e7..709eff42 100644 --- a/work-package/skills/15-manage-git.toon +++ b/work-package/skills/15-manage-git.toon @@ -1,5 +1,5 @@ id: manage-git -version: 1.5.0 +version: 1.6.0 capability: Manage git operations — branching, PR lifecycle, and branch synchronization description: "Handles git branch management, PR creation/updates via gh CLI, and branch synchronization. All git operations are performed INSIDE target_path. Branches and PRs are created against the target's upstream." @@ -31,9 +31,10 @@ protocol: - Fetch and rebase/merge from main to keep branch current - Resolve merge conflicts if any - Sync before pushing to avoid conflicts - code-commits[2]: - - "Append 'Assisted-by: {assistant}:{model_id} [{context_scope}]' as a trailer on all code commits (not artifact commits). Use git commit -m $'subject\n\nAssisted-by: {assistant}:{model_id} [{context_scope}]'. {assistant} is the name of the AI assistant name (e.g. claude, gpt, gemini); {model_id} is the specific model version." - - "context_scope is the workflow variable set during research: repo-only | web-retrieval | mixed" + code-commits[3]: + - "Every code commit (not artifact commits) must carry a 'Co-authored-by: {display_name} <{email}>' trailer so GitHub renders both the human and assistant in the commit byline." + - "Whether to add it manually depends on the harness: Claude Code adds it automatically — do NOT add it again or it will appear twice. Other assistants that do not auto-inject the trailer must add it explicitly via: git commit -m $'subject\n\nCo-authored-by: {display_name} <{email}>'" + - "Known assistant identities — Claude (Claude Code harness): 'Co-authored-by: Claude ' (auto-injected, no action needed). For other assistants, use the identity provided by their harness or documentation." detect-merge-strategy[3]: - "Resolve owner/repo from git remote get-url origin in target_path (convert SSH to HTTPS if needed, strip .git suffix)" - "Call: gh api repos/{owner}/{repo} --jq '{allow_squash_merge}'" diff --git a/work-package/workflow.toon b/work-package/workflow.toon index 05d01444..8186bc04 100644 --- a/work-package/workflow.toon +++ b/work-package/workflow.toon @@ -296,7 +296,7 @@ variables[69]: defaultValue: false - name: context_scope type: string - description: "Provenance scope of AI-generated code in this work package. Set during research phase. Values: repo-only (all context from repository), web-retrieval (web sources used), mixed (both). Used in Assisted-by commit trailers and provenance log." + description: "Provenance scope of AI-generated code in this work package. Set during research phase. Values: repo-only (all context from repository), web-retrieval (web sources used), mixed (both). Recorded in the provenance log and PR description." defaultValue: repo-only - name: recommended_outcome type: string