Workflow refactor#1
Merged
Merged
Conversation
- Updated AGENTS.md to clarify the purpose of roadmap.md and the order of operations for agents. - Revised README.md to emphasize the importance of README for live phase and next actions. - Enhanced operation-guide.md with clearer definitions for lifecycle gates and project evolution mode. - Modified artifact-contracts.md to specify default initiative files and their roles in the workflow. - Improved validation-and-completion.md to refine readiness criteria for roadmap and sprint content. - Adjusted workflow-contract.md to clarify execution rules and project evolution gate requirements. - Updated scaffold_initiative.py to reflect changes in roadmap generation and sprint initialization processes. - Introduced evidence/index.md template for sprint evidence management.
- Introduced a new `.gitignore` file for the evidence directory to exclude local scratch directories. - Added comprehensive context management documentation to guide the interpretation of context tiers and read budgets. - Created a reference for trace tokens to standardize workflow lookup metadata. - Implemented a scaffold script for generating portable ub-workflow artifacts, including commands for bootstrapping, creating waves, initiatives, discoveries, source packs, and preparing sprints.
…ity documentation
There was a problem hiding this comment.
Pull request overview
This PR refactors the ub-workflow scaffolding model from the older “initiative-root SOP” layout to a wave/initiative/discovery/sprint artifact tree, updates templates and references accordingly, and adds regression tests for the new CLI scaffold behaviors. It also removes a large set of previously checked-in .ub-workflows/ initiative/archive artifacts and updates repo routing docs (AGENTS.md, SOURCE_ATLAS.md) to support the new workflow routing surfaces.
Changes:
- Add/extend
ub-workflowCLI support surfaces (new options-board checker, updated placeholder checker) and refresh the workflow templates and references. - Add a new end-to-end unittest suite that boots a disposable workflow root and validates the scaffold layout and placeholder-check behavior.
- Remove legacy checked-in
.ub-workflows/initiative/archive content and adjust repo routing docs and ignore rules around workflow state.
Reviewed changes
Copilot reviewed 103 out of 105 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/skills/ub-workflow/test_scaffold_workflow.py | New subprocess-driven regression tests validating scaffold_workflow.py bootstrap/wave/initiative/discovery/sprint flows and placeholder checks. |
| Taskfile.yml | Removes a deleted YAML template from YAML_TARGETS lint scope. |
| SOURCE_ATLAS.md | Adds a repo-root source routing atlas seeded by workflow bootstrap. |
| AGENTS.md | Adds a root “UB Workflow Routing” block for .ub-workflows/ navigation. |
| .ub-workflows/initiatives/README.md | Deletes legacy initiative index doc (old operations-root model). |
| .ub-workflows/initiatives/operation-guide.md | Deletes legacy initiative SOP doc (replaced by new workflow model/templates). |
| .ub-workflows/initiatives/AGENTS.md | Deletes legacy initiative operations agent guidance (superseded by new workflow model). |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/11-final-audit/sprint.md | Removes archived sprint PRD from the repo’s checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/11-final-audit/evidence/final-audit-summary.md | Removes archived final-audit evidence doc from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/11-final-audit/evidence/.gitkeep | Removes .gitkeep from archived evidence directory. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/11-final-audit/closeout.md | Removes archived sprint closeout from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/10-freshness-and-portability-review/sprint.md | Removes archived sprint PRD from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/10-freshness-and-portability-review/evidence/advisory-freshness-and-portability.md | Removes archived sprint evidence from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/10-freshness-and-portability-review/evidence/.gitkeep | Removes .gitkeep from archived evidence directory. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/10-freshness-and-portability-review/closeout.md | Removes archived sprint closeout from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/09-packaging-policy-and-skill-uplift/sprint.md | Removes archived sprint PRD from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/09-packaging-policy-and-skill-uplift/evidence/packaging-policy-and-targeted-uplift.md | Removes archived sprint evidence from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/09-packaging-policy-and-skill-uplift/evidence/.gitkeep | Removes .gitkeep from archived evidence directory. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/09-packaging-policy-and-skill-uplift/closeout.md | Removes archived sprint closeout from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/08-workflow-placeholder-hardening/sprint.md | Removes archived sprint PRD from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/08-workflow-placeholder-hardening/evidence/placeholder-contract-and-cli-proof.md | Removes archived sprint evidence from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/08-workflow-placeholder-hardening/evidence/.gitkeep | Removes .gitkeep from archived evidence directory. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/08-workflow-placeholder-hardening/closeout.md | Removes archived sprint closeout from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/07-ci-parity-and-regression-coverage/sprint.md | Removes archived sprint PRD from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/07-ci-parity-and-regression-coverage/evidence/ci-parity-and-fixture-coverage.md | Removes archived sprint evidence from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/07-ci-parity-and-regression-coverage/evidence/.gitkeep | Removes .gitkeep from archived evidence directory. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/07-ci-parity-and-regression-coverage/closeout.md | Removes archived sprint closeout from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/06-repo-integrity-validators/sprint.md | Removes archived sprint PRD from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/06-repo-integrity-validators/evidence/repo-integrity-validator-baseline.md | Removes archived sprint evidence from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/06-repo-integrity-validators/evidence/.gitkeep | Removes .gitkeep from archived evidence directory. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/06-repo-integrity-validators/closeout.md | Removes archived sprint closeout from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/05-inventory-alignment-and-agents-rename/sprint.md | Removes archived sprint PRD from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/05-inventory-alignment-and-agents-rename/evidence/inventory-and-metadata-alignment.md | Removes archived sprint evidence from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/05-inventory-alignment-and-agents-rename/evidence/.gitkeep | Removes .gitkeep from archived evidence directory. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/05-inventory-alignment-and-agents-rename/closeout.md | Removes archived sprint closeout from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/04-workflow-regression-and-resume-scenarios/sprint.md | Removes archived sprint PRD from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/04-workflow-regression-and-resume-scenarios/evidence/regression-and-resume-coverage.md | Removes archived sprint evidence from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/04-workflow-regression-and-resume-scenarios/closeout.md | Removes archived sprint closeout from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/03-helper-and-template-redesign/sprint.md | Removes archived sprint PRD from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/03-helper-and-template-redesign/evidence/helper-and-template-behavior.md | Removes archived sprint evidence from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/03-helper-and-template-redesign/closeout.md | Removes archived sprint closeout from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/02-skill-agent-and-reference-alignment/sprint.md | Removes archived sprint PRD from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/02-skill-agent-and-reference-alignment/evidence/reference-alignment-summary.md | Removes archived sprint evidence from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/02-skill-agent-and-reference-alignment/closeout.md | Removes archived sprint closeout from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/01-lifecycle-and-gate-redesign/sprint.md | Removes archived sprint PRD from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/01-lifecycle-and-gate-redesign/evidence/lifecycle-summary-and-gates.md | Removes archived sprint evidence from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/01-lifecycle-and-gate-redesign/closeout.md | Removes archived sprint closeout from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/sprints/.gitkeep | Removes .gitkeep from archived sprints directory. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/retained-note.md | Removes archived retained note from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/research/AGENTS.md | Removes archived research routing guidance from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/research/.gitkeep | Removes .gitkeep from archived research directory. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/README.md | Removes archived initiative status doc from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/exceptions/exception-template.yaml | Removes archived exception template from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/exceptions/AGENTS.md | Removes archived exception routing guidance from checked-in workflow state. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/exceptions/.gitkeep | Removes .gitkeep from archived exceptions directory. |
| .ub-workflows/archive/2026-04-16-repository-self-governance-hardening/AGENTS.md | Removes archived initiative-local agent guidance from checked-in workflow state. |
| .gitignore | Treats .ub-workflows/ as local workflow state to ignore (and clarifies comment). |
| .agents/skills/ub-workflow/scripts/check_workflow_options.py | Adds a new CLI to scan options boards for drift/staleness and emit summary/JSON. |
| .agents/skills/ub-workflow/scripts/check_scaffold_placeholders.py | Retargets placeholder scanning to scaffold_workflow.py and simplifies reporting. |
| .agents/skills/ub-workflow/references/trace-tokens.md | New reference defining trace token format, allowed owners, and routing tables. |
| .agents/skills/ub-workflow/references/scaffold-helper.md | Updates helper documentation to the new scaffold_workflow.py command set and behavior. |
| .agents/skills/ub-workflow/references/placeholder-contract.md | Updates placeholder rules/scope to the new workflow artifact set. |
| .agents/skills/ub-workflow/assets/operations-root/README.md | Removes old operations-root README (initiative index model). |
| .agents/skills/ub-workflow/assets/operations-root/operation-guide.md | Rewrites operation guide to the new wave/initiative/options-board model and options governance. |
| .agents/skills/ub-workflow/assets/operations-root/AGENTS.md | Updates operations-root agent orientation to align with new status/options/wave routing and checks. |
| .agents/skills/ub-workflow/assets/lightweight-spec-template/spec.md | Removes the lightweight spec template (no longer part of the new model). |
| .agents/skills/ub-workflow/assets/initiative-template/sprints/.gitkeep | Removes .gitkeep under initiative template sprints. |
| .agents/skills/ub-workflow/assets/initiative-template/sprint-template/sprint.md | Replaces sprint template with frontmatter + reviewed-mode routing/triage/validation structure. |
| .agents/skills/ub-workflow/assets/initiative-template/sprint-template/evidence/index.md | Adds an evidence index template with frontmatter and claim/evidence tables. |
| .agents/skills/ub-workflow/assets/initiative-template/sprint-template/evidence/.gitkeep | Removes .gitkeep from evidence template dir. |
| .agents/skills/ub-workflow/assets/initiative-template/sprint-template/evidence/.gitignore | Adds evidence scratch .gitignore template for generated runtime state. |
| .agents/skills/ub-workflow/assets/initiative-template/sprint-template/decision-log.md | Updates decision log template to frontmatter + simpler sections. |
| .agents/skills/ub-workflow/assets/initiative-template/sprint-template/closeout.md | Updates closeout template to frontmatter + outcome/forecast/evidence/validation/retro structure. |
| .agents/skills/ub-workflow/assets/initiative-template/rollup.md | Removes initiative rollup template. |
| .agents/skills/ub-workflow/assets/initiative-template/roadmap.md | Replaces roadmap template with objective/forecast/WIP/adaptive-plan model. |
| .agents/skills/ub-workflow/assets/initiative-template/retained-note.md | Simplifies retained note template to “Outcome/Evidence/Follow-up” minimal form. |
| .agents/skills/ub-workflow/assets/initiative-template/research/AGENTS.md | Removes research-local agent guidance template. |
| .agents/skills/ub-workflow/assets/initiative-template/research/.gitkeep | Removes .gitkeep from research template dir. |
| .agents/skills/ub-workflow/assets/initiative-template/README.md | Removes legacy initiative status README template. |
| .agents/skills/ub-workflow/assets/initiative-template/prd.md | Removes PRD template from initiative template set. |
| .agents/skills/ub-workflow/assets/initiative-template/options.md | Adds initiative-local options board template. |
| .agents/skills/ub-workflow/assets/initiative-template/initiative.md | Adds initiative owner document template (summary/bet framing/status/decisions). |
| .agents/skills/ub-workflow/assets/initiative-template/index.md | Adds triggered T3 initiative index template (artifact routes / trace routes). |
| .agents/skills/ub-workflow/assets/initiative-template/exceptions/exception-template.yaml | Removes exception template from initiative template assets. |
| .agents/skills/ub-workflow/assets/initiative-template/exceptions/AGENTS.md | Removes exceptions-local agent guidance template. |
| .agents/skills/ub-workflow/assets/initiative-template/exceptions/.gitkeep | Removes .gitkeep from exceptions template dir. |
| .agents/skills/ub-workflow/assets/initiative-template/AGENTS.md | Removes initiative-root AGENTS template. |
| .agents/skills/ub-quality/references/freshness-portability.md | Adds guidance about parallel research delegation during freshness/portability work. |
| .agents/skills/ub-python/SKILL.md | Adds strict-typing guidance around avoiding ambiguous constructor overloads for JSON-like mappings. |
| .agents/skills/ub-python/references/python-standards.md | Adds a strict-typing rationale/example for preferring {**mapping}/helpers over dict(mapping) in some typed contexts. |
| .agents/skills/ub-governance/SKILL.md | Clarifies wording around “host repository maintenance checks” vs governance commands. |
| .agents/skills/ub-governance/references/governance-commands.md | Aligns wording around host-repo maintenance wrappers vs governance commands. |
| .agents/skills/ub-governance/references/decision-memory-and-claims.md | Clarifies decision-memory/claim-register applicability vs workflow-native records. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+79
to
+83
| roots = payload.get("roots") | ||
| if isinstance(roots, list): | ||
| for index, root_payload in enumerate(roots): | ||
| if index: | ||
| print() |
Comment on lines
+193
to
+197
| - Before substantial work, read `.ub-workflows/status.md`. | ||
| - For non-trivial source work, read `SOURCE_ATLAS.md` and then the nearest relevant folder `AGENTS.md`. | ||
| - Use `.ub-workflows/vision.md` when product direction matters. | ||
| - Use `.ub-workflows/WORKFLOW_ATLAS.md` for workflow-artifact routing. | ||
| - Use `.ub-workflows/SOURCE_PACK_ATLAS.md` before opening retained source packs. |
Comment on lines
+59
to
+70
| return { | ||
| "status" : "fail" if required_count else "pass", | ||
| "scanRoot" : scan_root.resolve().as_posix(), | ||
| "workflowRoot" : workflow_root.as_posix(), | ||
| "mode" : mode, | ||
| "staleDays" : stale_days, | ||
| "includeHistory": include_history, | ||
| "requiredCount" : required_count, | ||
| "advisoryCount" : advisory_count, | ||
| "summary" : SCAFFOLD_MODULE.format_options_summary(workflow_root, findings), | ||
| "findings" : [finding_payload(finding) for finding in findings], | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
massive update to workflows