Activities - Plan Iteration

#	Name	Abbrev.	Guidance	Actions
Construction 5
1	Readiness Check	PIN-1	Purpose Validate all prerequisites before planning begins. User provides a goal sentence (e.g. "we aim …	Read the 'PIN-1 Readiness Check' activity from playbook 'Junior Edda' (workflow 'Plan Iteration'). Follow its guidance when assisting me. ## Purpose Validate all prerequisites before planning begins. User provides a goal sentence (e.g. "we aim to complete act-11"). Each gate is checked in order — if any fails, stop with specific remediation instructions. ## Input The user's stated goal sentence. Example: "we aim to complete act-11" or "implement team management features". ## Gates ### Gate 1 — BSP (Bootstrap) Check that the project has been bootstrapped: ```bash test -f Makefile && echo "PASS" \|\| echo "FAIL: Run BSP workflow — project not bootstrapped" test -f requirements.txt && echo "PASS" \|\| echo "FAIL: Run BSP workflow — requirements.txt missing" ``` If either fails: STOP — "Project not bootstrapped. Run the BSP (Bootstrap Project) workflow first." ### Gate 2 — User Journey Coverage Identify the target act from the user's goal (e.g. "act-11", "team management"). Check `docs/features/user_journey.md` for a matching section: ```bash grep -i "act-{N}" docs/features/user_journey.md && echo "PASS" \|\| echo "FAIL" ``` If missing: STOP — "No user journey section found for {target}. Add the act section to `docs/features/user_journey.md` before planning." ### Gate 3 — Feature Specs (BDD) Check that `docs/features/act-{N}/` exists and contains `.feature` files: ```bash ls docs/features/act-{N}/.feature 2>/dev/null && echo "PASS" \|\| echo "FAIL" ``` If missing: STOP* — "No feature specs found for act-{N}. Run the ESM (Envision the System) workflow to produce `.feature` files." ### Gate 4 — Architecture (SAO.md) ```bash test -f docs/architecture/SAO.md && echo "PASS" \|\| echo "FAIL" ``` If missing: STOP — "No `docs/architecture/SAO.md` found. Run the DTA (Define Architecture) workflow first." ### Gate 5 — AI IDE Config (DSP) ```bash test -f CLAUDE.md && echo "PASS" \|\| echo "FAIL" ``` If missing: STOP — "No `CLAUDE.md` found. Run the DSP (Deploy Software Process) workflow to configure the AI IDE." ### Gate 6 — Agent proof harness (optional; when SAO §17 applies) When `docs/architecture/SAO.md` §17 documents in-app LLM agents (not "Not applicable"): ```bash test -f tests/support/agent_story.py && echo "PASS" \|\| echo "FAIL: TFK-02 must bootstrap tests/support/agent_story.py before agent-feature BPE" ``` If SAO §17 is N/A: SKIP — record `agent_harness: n/a`. If SAO §17 applies and the file is missing: STOP — "Agent proof helper missing. Run TFK-02 (Bootstrap Test Harness) to create `tests/support/agent_story.py` and ScriptedLLM fixtures before planning agent features." ## Mockup Check (advisory, after all gates pass) ```bash ls docs/ux/mockups/act-{N}/ 2>/dev/null && echo "Mockups found" \|\| echo "No mockups" ``` If no mockups: ask — "No mockups found for {target}. Create them per ESM-04 before planning? (yes/no)" - Yes → run ESM-04, then return to PIN-01 after mockups are created - No → proceed with feature specs only ## Output When all gates pass: - `target_act`: extracted act identifier (e.g. "act-11") - `feature_files[]`: list of `.feature` files in `docs/features/act-{N}/` - `has_mockups`: boolean - `agent_harness`: `ready` \| `n/a` (from Gate 6) Proceed to PIN-02 Orient & Validate Scope. ## Success Criteria - All required gates pass (Gates 1–5; Gate 6 pass or skipped when SAO §17 N/A) - User has confirmed mockup status - `target_act` and `feature_files[]` identified - `agent_harness` recorded when SAO §17 applies
2	Orient & Validate Scope	PIN-2	Purpose Build the iteration orient summary from the feature files identified in PIN-01, using historical …	Read the 'PIN-2 Orient & Validate Scope' activity from playbook 'Junior Edda' (workflow 'Plan Iteration'). Follow its guidance when assisting me. ## Purpose Build the iteration orient summary from the feature files identified in PIN-01, using historical lesson data where available. Establishes what the iteration will deliver and any risk flags. ## Session Resume Check If `docs/plans/iterations/pin-orient-{today's date}.md` already exists → skip this activity, load it as the orient summary, proceed to PIN-03. ## Prerequisites - `target_act` and `feature_files[]` from PIN-01 - `docs/lessons_learned/ITER-.md` files (may not exist on first iteration) ## Steps ### Step 1: Read Feature Specs For each file in `feature_files[]`, read the BDD scenarios. Extract: - Scenario titles - Given/When/Then outlines (to understand scope boundaries) - Tags if present (e.g. `@wip`, `@smoke`) — optional; scenarios with no tags are treated as fully eligible ### Step 2: Read Learning Log ```bash ls -t docs/lessons_learned/ITER-.md 2>/dev/null \| head -5 ``` If no files found → first iteration. Create the directory and continue with first-iteration defaults: ```bash mkdir -p docs/lessons_learned ``` - `velocity_ratio`: unknown - `dominant_drift`: none - `footprint_accuracy`: unknown If files found → read the 5 most recent. Each file has YAML frontmatter. Extract: ```bash for f in $(ls -t docs/lessons_learned/ITER-.md \| head -5); do awk '/^---/{p++} p==1{print} p==2{exit}' "$f" done ``` Compute across the 5 most recent entries: - velocity_ratio trend: improving (trend up) / stable / degrading (trend down) - dominant_drift: most frequent non-none value (or "none" if all none) - footprint_accuracy trend: improving / stable / degrading Also scan the body of the most recent file for flagged SAO.md decisions. If any are present: > "Prior iteration flagged SAO.md decisions not yet applied: {list}. Verify they were committed before this iteration begins." Note:* `docs/lessons_learned/log.yaml` is deprecated. If it exists, ignore it. ### Step 3: Validate Scope - If `velocity_ratio` degrading AND >2 scenarios: flag scope risk - If `dominant_drift` was `footprint_violation` in 2+ of last 5: flag complexity risk ### Step 3b: Scope Bounding Count total scenarios across all `feature_files[]`. Assess whether the full scope fits your effective context window: - Estimate complexity: scan each scenario's step count and whether it touches new models, new pages, or new infrastructure. - If the full scope feels manageable (scenarios are simple CRUD / UI checks with predictable footprints), proceed with all scenarios. - If the scope is large and scenarios are complex (new models, cross-cutting concerns, unresolved system dependencies), ask: > "This iteration has {N} scenarios. Some appear complex — would you like to: > A) Proceed with all {N} > B) Take a subset (tell me which scenarios or feature files) > C) Split across multiple iterations — first file's scenarios now, remainder via a second PIN run" Handle user response: - A: Proceed with all scenarios; record `scope_override: confirmed` in orient summary - B: Filter to the user-selected subset; record deferred scenarios in `scenarios_deferred[]` - C: Take only the first feature file's scenarios (or user-specified first batch); record `scope_deferred_files[]` If the full scope is simple and clearly manageable, do not ask — just proceed and note `scope_override: not_needed`. ### Step 4: Write Orient Summary Create `docs/plans/iterations/pin-orient-{YYYYMMDD}.md`: ```markdown ## Orient Summary — {date} ### Target Act: {target_act} Feature files: {list} ### Scenarios in Scope {list of scenario titles — after scope bounding} ### Scenarios Deferred {list or "None"} ### Velocity Trend {improving/stable/degrading or "First iteration"} ### Dominant Drift {signal_type or "None — first iteration"} ### Scope Validation {per-scenario risk flags or "No risks detected"} ``` ## Success Criteria - Orient summary written to `docs/plans/iterations/pin-orient-{date}.md` - Scenarios in scope identified (after scope bounding — may be a subset of all feature file scenarios) - Deferred scenarios recorded if scope was reduced - Risk flags computed or noted as first iteration - Ready for PIN-03
3	Contract	PIN-3	Purpose For each BDD scenario in scope: run BPE-01 planning, create code skeletons (public + …	Read the 'PIN-3 Contract' activity from playbook 'Junior Edda' (workflow 'Plan Iteration'). Follow its guidance when assisting me. ## Purpose For each BDD scenario in scope: run BPE-01 planning, create code skeletons (public + private helpers), build the context map and do-not-do list, verify checkpoint commands (behavior and log-story when applicable). After all scenarios: derive the file-level conflict map and write the execution manifest YAML. ## Prerequisites - Orient summary from PIN-02 - `docs/architecture/SAO.md` - BDD feature specs from `docs/features/act-{N}/` ## Steps ### Step 1: Create Iteration Branch (once) ```bash # Safe for retries — checks before creating git show-ref --verify --quiet refs/heads/iteration/YYYYMMDD-{goal-slug} \ && git checkout iteration/YYYYMMDD-{goal-slug} \ \|\| git checkout -b iteration/YYYYMMDD-{goal-slug} ``` ### Steps 2–8 repeat for each scenario ### Step 2: Read Specification and Record Feature File Path Read the BDD feature spec for this scenario. Note the exact `.feature` file path — you will record it in the manifest. Record: `feature_file_path: docs/features/act-{N}/{filename}.feature` Read `docs/architecture/SAO.md`. Note governing sections. ### Step 3: Identify System Dependencies Before running BPE-01, scan the scenario's steps for capabilities that require external infrastructure (not part of this feature's codebase footprint): Common patterns to check for: - "receives a notification" → `notification_service` - "receives an email" → `email_backend` - "background task" → `task_queue` - "search index" → `search_backend` If any are found: record them as `system_dependencies` for this scenario. If the infrastructure doesn't exist in the codebase, choose a resolution before proceeding: \| Option \| When to use \| Action \| \|--------\|-------------\|--------\| \| A — Prerequisite scenario \| Infrastructure is reusable across multiple scenarios \| Create a separate scenario S0 covering the infrastructure; add it as a dependency to all affected scenarios. Ask user before doing this. \| \| B — Stub & proceed \| Infrastructure is minor and can be stubbed \| Note stub in BPE-01 plan; create a stub file named exactly after the dependency identifier (e.g. `notification_service` → `methodology/services/notification_service.py`) with a no-op implementation; include it in the skeleton commit; annotate the manifest entry as `notification_service [STUBBED]`. MIN-04 checks for this file by name — the naming must match or MIN-04 will falsely escalate. Decide autonomously, note in manifest. \| \| C — Skip this iteration \| Infrastructure is substantial and out of scope \| Remove scenario from `scenarios_in_scope[]`; add to `scenarios_deferred[]` in orient summary. Ask user before doing this. \| ### Step 4: Run BPE-01 Follow BPE/BPE-01 completely. Output must include: a) Context Map — 3–5 `file:line_range` references with one-line note each. b) Do-Not-Do List — derived from SAO.md sections: ``` - Do NOT create a new Django app - Do NOT add a manager/repository layer ``` c) Applicable SAO.md Sections — list by heading name. d) Checkpoint Command — pytest command that proves behavior done. e) Log Story Script — from BPE-01 Section E (Where / Beat / Trigger / Must include). f) Log-story tests + command — when Section E is non-empty: `log_tests[]` names/paths and `checkpoint.log_story_command`. Important: When running BPE-01 inside PIN-03, skip BPE-01 Step 9 (Submit for Approval) and BPE-01 Step 10 (GitHub/Issue Management). The implementation plan is captured in the manifest; GitHub/GitLab issues are created in PIN-04. Running those steps here would produce duplicates. ### Step 5: Create Thorough Skeleton Write skeletons for every class and method — public AND private helpers. The skeleton is the complete architecture; an implementor must not need to add new methods. Production skeleton example: ```python class FeatureService: def execute(self, id: int, user) -> dict: """ :param id: Feature ID. Example: 42 :param user: Requesting user. :return: dict. Example: {"id": 42, "name": "..."} :raises PermissionError: If user cannot access :raises ValueError: If not found """ raise NotImplementedError() def _validate(self, id, user) -> None: raise NotImplementedError() def _serialize(self, obj) -> dict: raise NotImplementedError() ``` ### Step 6: Verify Checkpoint Commands ```bash {checkpoint.command} 2>&1 \| tail -5 # When log_tests present: {checkpoint.log_story_command} 2>&1 \| tail -5 ``` Acceptable: `NotImplementedError` or `collected 0 items`. Not acceptable: `ImportError`, `SyntaxError`. ### Step 7: Commit Skeleton ```bash git add -A git commit -m "chore(pin): skeleton S{N} — {scenario title}" ``` ### Step 8: Record Footprint ```bash git diff HEAD~1 --name-only ``` Record as `codebase_footprint[]`. Record `skeleton_commit` hash. ### After All Scenarios: ### Step 9: Build Conflict Map For each scenario pair, check footprint intersection: ``` S1 ∩ S2 = {tools.py} → CONFLICT → serialize S1 ∩ S3 = {} → no conflict → parallel ``` ### Step 10: Assign Parallel Groups Non-conflicting → same group. Conflicting → different groups with dependency. ### Step 11: Write Execution Manifest Create `docs/plans/iterations/ITER-YYYYMMDD-HHmm-{goal-slug}.yaml`: ```yaml iteration: goal: "{iteration_goal}" doctrine_version: "2.0" created_at: "{ISO8601}" conflict_map: path/to/file.py: [S1, S2] parallel_groups: A: [S1] B: [S3] C: [S2] drift_thresholds: absorbed: checkpoint_fail_retry: 1 escalated: footprint_violation: true method_explosion: true sao_violation: true checkpoint_fail_after_retry: true scenarios: S1: title: "{title}" parallel_group: A skeleton_commit: "{hash}" codebase_footprint: [...] feature_file_paths: - docs/features/act-{N}/{filename}.feature system_dependencies: - notification_service # or empty list [] if none; append [STUBBED] if stubbed log_story_script: - {beat: entry, where: "LoginView.post", trigger: method_called, must_include: ["email="]} - {beat: branch, where: "LoginView.post", trigger: bad_credentials, must_include: ["authentication failed"]} log_tests: - {name: test_login_log_story_reject, path: src/yggdrasil/auth/tests/test_login_view.py} checkpoint: command: "pytest ...::test_login_post_failure_rerenders_with_error -x" expected_exit_code: 0 log_story_command: "pytest ...::test_login_log_story_reject -x" # required when log_tests non-empty dependencies: [] context_map: [...] do_not_do: [...] sao_sections: [...] ``` Rules: - If `log_tests` is non-empty, `checkpoint.log_story_command` is required - Omit `log_story_script` / `log_tests` / `log_story_command` only when BPE-01 Section E is empty (document why) - PIN-04 consumers may embed both commands in the issue SCENARIO block ## Rules Before running BPE-01 inside this activity and writing the manifest, read each Rule below in this playbook (by slug), then apply it. Do not rely on memory of the rule text. Required: - `do-plan-before-doing` - `do-skeletons-first` - `do-test-first` - `do-informative-logging` - `do-assert-log-story` - `do-follow-commit-convention` - `do-small-increments` - `pytest` Activity-specific (not a substitute for the rules above): - When BPE-01 Section E (Log Story Script) is non-empty, the manifest must include `log_story_script[]`, `log_tests[]`, and `checkpoint.log_story_command`. ## Success Criteria - Skeleton committed for every scenario - `feature_file_paths[]` recorded per scenario (paths to .feature files) - `system_dependencies[]` recorded per scenario (empty list if none) - All system_dependencies resolved (stubbed, prerequisite scenario, or deferred) before proceeding - Stub files named to match their dependency identifier so MIN-04's codebase check succeeds - Execution manifest YAML written to `docs/plans/iterations/` - Conflict map derived from actual skeleton commits - All checkpoint commands verified (NotImplementedError or 0 items), including `log_story_command` when declared
4	Publish	PIN-4	Purpose Create the Milestone and Issues from the execution manifest, on GitHub or GitLab. Ask …	Read the 'PIN-4 Publish' activity from playbook 'Junior Edda' (workflow 'Plan Iteration'). Follow its guidance when assisting me. ## Purpose Create the Milestone and Issues from the execution manifest, on GitHub or GitLab. Ask user before creating. The Milestone becomes MIN's operational ground truth — it must contain the full YAML manifest inline. ## Prerequisites - Execution manifest YAML from PIN-03 (`ITER-.yaml`) with `milestone_number: null` placeholder - All skeleton commits on iteration branch - GitHub CLI (`gh`) or GitLab CLI (`glab`) authenticated ## Step 0 — Platform Detection ```bash REMOTE=$(git remote get-url origin 2>/dev/null \|\| echo "") if echo "$REMOTE" \| grep -q "github.com"; then PLATFORM=github gh auth status \|\| { echo "Run: gh auth login"; exit 1; } elif echo "$REMOTE" \| grep -q "gitlab"; then PLATFORM=gitlab glab auth status \|\| { echo "Run: glab auth login"; exit 1; } else echo "Cannot detect platform from git remote. Set PLATFORM=github or PLATFORM=gitlab manually." exit 1 fi echo "Platform: $PLATFORM" ``` ## Step 1 — User Gate Ask: "Platform detected: {github\|gitlab}. Create milestone and issues from the manifest? (yes/no)" - No* → write manifest to `docs/plans/iterations/` only. Stop. Inform user: "Manifest saved. Invoke MIN manually when ready." - Yes → continue. ## Step 2 — Bootstrap Labels GitHub: See GitHub Issue Operations skill — Bootstrap Labels section. GitLab: See GitLab Issue Operations skill — Bootstrap Labels section. ## Step 3 — Create Milestone GitHub: ```bash MILESTONE_NUMBER=$(gh api repos/{owner}/{repo}/milestones \ --method POST \ --field title="ITER-YYYYMMDD \| {iteration_goal}" \ --field description="<!-- MANIFEST --> $(cat {manifest_path}) <!-- /MANIFEST --> ## Iteration Goal {iteration_goal} ## Scenarios {list}" \ --jq '.number') echo "Milestone: #$MILESTONE_NUMBER" ``` GitLab: ```bash PROJECT=$(glab api projects/:fullpath --jq '.id') MILESTONE_NUMBER=$(glab api "projects/$PROJECT/milestones" \ --method POST \ --field title="ITER-YYYYMMDD \| {iteration_goal}" \ --field description="<!-- MANIFEST -->$(cat {manifest_path})<!-- /MANIFEST -->" \ --jq '.iid') echo "Milestone: #$MILESTONE_NUMBER" ``` ## Step 4 — Create Issues (one per scenario) For each scenario in manifest order: GitHub: See GitHub Issue Operations skill — Pattern 2. GitLab: See GitLab Issue Operations skill — Pattern 2. Issue body must include inline: - `<!-- SCENARIO -->` YAML block - `<!-- FEATURE_EXECUTION_GRAPH -->` YAML block (full graph for this scenario) - Context Map table - Do Not Do list - SAO.md Sections - Implementation Plan (full text from BPE-01) - Acceptance Criteria checklist — one checkbox per graph node plus scenario rollup checkpoint Labels: `status-queued, parallel-group-{X}` Dependency issues reference each other in body. ## Step 5 — Update Manifest with Milestone Number and Issue Numbers After the milestone is created (Step 3) and all issues are created (Step 4), update the manifest: ```bash # Write milestone_number into the iteration block python3 -c " import re content = open('{manifest_path}').read() content = re.sub(r'milestone_number: null', 'milestone_number: {milestone_number}', content, count=1) open('{manifest_path}', 'w').write(content) " # Also add github_issue or gitlab_issue per scenario (as before) # Edit the manifest YAML to add the issue number under each scenario key ``` Commit both updates together: ```bash git add docs/plans/iterations/ git commit -m "chore(pin): add milestone #{milestone_number} and issue numbers to manifest ITER-YYYYMMDD" ``` Verification: `milestone_number` in the manifest must now be an integer, not `null`. MIN-01 uses this field to locate the correct manifest. Do not proceed to PIN-05 if it is still `null`. ## Step 6 — Verify GitHub: ```bash gh milestone view {milestone_number} gh issue list --milestone {milestone_number} ``` GitLab: ```bash glab api "projects/:fullpath/milestones" --jq '.[] \| select(.title \| contains("ITER"))' glab issue list --milestone "{milestone_title}" --label "status-queued" ``` ## Success Criteria - Milestone created with full `<!-- MANIFEST -->` YAML block - One Issue per scenario with inline `<!-- SCENARIO -->` + `<!-- FEATURE_EXECUTION_GRAPH -->` + context map + do-not-do + implementation plan - All issues labelled `status-queued` + `parallel-group-{X}` - `milestone_number` written back to manifest (not null) - Local manifest updated with milestone number + issue numbers and committed ## Skills - GitHub Issue Operations (gh CLI) - GitLab Issue Operations (glab CLI)
5	Human Acceptance	PIN-5	Purpose Verify CLAUDE.md iteration protocol sections are current, obtain explicit human approval, and deliver the …	Read the 'PIN-5 Human Acceptance' activity from playbook 'Junior Edda' (workflow 'Plan Iteration'). Follow its guidance when assisting me. ## Purpose Verify CLAUDE.md iteration protocol sections are current, obtain explicit human approval, and deliver the single activation instruction for MIN. This is the final gate — do not proceed without explicit human go. STOP — mandatory human gate. ## Prerequisites - All skeleton commits on iteration branch - Execution manifest finalized (`ITER-.yaml`) with `milestone_number` populated - GitHub/GitLab Milestone + Issues published (PIN-04 complete) ## Steps ### Step 1: Verify CLAUDE.md Iteration Protocol Sections Read the `## Iteration Protocol`, `## Drift Handling`, `## Session Resume Protocol`, and `## Authority Model` sections of CLAUDE.md. Required sections must exist and contain: - Iteration Protocol* — references `<!-- MANIFEST -->` block, `status-queued`, fresh subagent per `feature_execution_graph` node with pytest gates - Drift Handling — absorbed and escalated thresholds (checkpoint_fail retry once; escalate on footprint_violation, method_explosion, sao_violation) - Session Resume Protocol — find `status-in-progress` → re-run checkpoint → PASS: close and continue / FAIL: retry - Authority Model — can-decide / must-escalate / cannot-do bounds for the iteration runner If any section is missing or substantially absent: update CLAUDE.md and commit: ```bash git commit -m "docs(claude): sync iteration protocol to current MIN workflow" ``` Do NOT compare against a `doctrine_version` field in the manifest — protocol version is managed by the Edda playbook release, not the manifest. ### Step 2: Present Review Summary ``` === PIN COMPLETE — REVIEW REQUIRED === Iteration: {iteration_goal} Milestone: #{milestone_number} — {milestone_title} Scenarios: {N} \| Groups: {A,B,...} {for each scenario:} S{N} [{group}] {title} Checkpoint: {command} Graph nodes: {N} (BPE-02...06) Footprint: {N} files Depends on: {deps or "none"} Sample: review one scenario's feature_execution_graph in Plan mode Conflict map: {file} -> [{S_N}, {S_M}] (serialized) {or "No conflicts — all scenarios parallel"} Platform: {github\|gitlab} Milestone: #{milestone_number} CLAUDE.md protocol: {current / updated at {timestamp}} Activate MIN with: "Work on Milestone #{milestone_number}" ====================================== ``` ### Step 3: Await Human Decision GO — "Approved" or "Work on Milestone #{N}" ```bash # GitHub: gh issue comment {first_issue} --body "PIN approved at {timestamp}. MIN authorized." # GitLab: glab issue note {first_issue} --message "PIN approved at {timestamp}. MIN authorized." ``` NO-GO options: - Skeleton issue on S{N} → return to PIN-03 for that scenario only - Re-sequencing needed → return to PIN-03 Step 8-9 to revise conflict map - Drop S{N} → close issue (won't-fix), remove from manifest, update Milestone description ## Success Criteria - CLAUDE.md iteration protocol sections are current (no doctrine_version comparison) - Explicit human go/no-go decision obtained - If go: approval comment posted on GitHub/GitLab - Human has the activation instruction with the concrete milestone number ## Rules - Never skip this gate regardless of time pressure - If human is unavailable: pause PIN, do not proceed to MIN - A no-go with a fix takes minutes; a bad MIN run wastes an hour

Activities in Plan Iteration