Activities - Build Feature

#	Name	Abbrev.	Guidance	Actions
Construction 9
1	Plan Feature	BPE-1	Purpose Plan a new feature implementation by analyzing requirements, assessing codebase state, creating detailed implementation …	Read the 'BPE-1 Plan Feature' activity from playbook 'Junior Edda' (workflow 'Build Feature'). Follow its guidance when assisting me. ## Purpose Plan a new feature implementation by analyzing requirements, assessing codebase state, creating detailed implementation plan, and preparing for execution. ## Prerequisites - Feature specification or idea for what needs to be built - Access to codebase and documentation ## Steps ### Step 0: Reset and Prepare Reset your task plan. If there was work in progress on another task, create a TODO.md file documenting what was being worked on, what was completed, what remains to be done, and any blockers or notes. ### Step 1: Understand Architecture Read `docs/architecture/SAO.md` (if exists) to identify architectural patterns and principles relevant to this implementation. Note which section headings govern this feature — you will need these in Step 6. ### Step 2: Understand User Journey Check `docs/features/user_journey.md` (if exists) to understand what you're building and how it integrates with other parts of the system. ### Step 3: Analyze Feature Specification Read the feature specification thoroughly. If none exists, propose creating one first. Follow BDD/Gherkin format: one scenario = one user goal; 5–10 steps max; GIVEN-WHEN-THEN structure; independently executable. Step phrases must reuse patterns from `docs/features/CATALOG.md` or explicitly add a new catalogued step via TFK-07. ### Step 4: Assess Codebase State a) Identify reusable components: list components/services/models that can be reused; verify they're not stubs. b) Check test coverage: for any reusable components without tests, add test creation to the plan. c) Build context map: identify 3–5 `file:line_range` locations an implementor must read. Format: ``` \| file \| lines \| one-line note \| ``` If you cannot identify 3 meaningful references, the codebase assessment in step (a) is incomplete. d) Detect MCP / Agent surface: - Check SAO §18 — is MCP in scope for this feature? If yes: locate `mcp/server.py` (or equivalent). Verify `initialize_mcp()` exists and is called on startup. If missing: add initialization to the plan before any tool registration step. - Check SAO §17 — does this feature add or extend agent capabilities? If yes: locate `ToolExecutor` (artifact 56 §4.3). Verify it is instantiated and injected into the agent loop. If missing: add ToolExecutor initialization to the plan before service wiring. - Record findings as additional one-liners in the Context Map: `mcp/server.py \| <line> \| FastMCP singleton — register new tools here` `llm/executor.py \| <line> \| ToolExecutor — wire service callables here` Skip a row if that surface is not in scope. ### Step 5: Clarification Questions Ask clarification questions scenario-by-scenario. If >5 questions total, create `FEAT_X.Y.Z_Clarifications.md` for batch answers. ### Step 6: Create Implementation Plan Mandatory Section A — Context Map (from Step 4c) Mandatory Section B — Do-Not-Do List (derived from SAO.md sections) Mandatory Section C — SAO.md Sections That Apply Mandatory Section D — Tests to Create (each row must state what it asserts). When Section E has rows, also list `test__log_story_happy` and/or `test__log_story_reject` (pytest + caplog; integration or view level). When Section G has rows (SAO §17 in scope), also list `test__agent_story_happy` and/or `test__agent_story_reject` (`@pytest.mark.agent_proof`; ScriptedLLM + `assert_agent_story`). Mandatory Section E — Log Story Script (formerly Logs to Emit). Each row is a beat the implementor must emit and prove with caplog. Never defer logging to a final slice. ``` ## Log Story Script \| Where \| Beat \| Trigger \| Must include \| \|-------\|------\|---------\|--------------\| \| `LoginView.post` \| entry \| method called \| email= (never password) \| \| `LoginView.post` \| branch \| bad credentials \| authentication failed \| \| `LoginView.post` \| exit \| success \| login success, user_pk= \| ``` Beats vocabulary: `entry \| config \| validation \| processing \| branch \| exit \| error`. Do not cite dropped rule `add-logging`. Mandatory Section F — MCP Tools to Expose (skip with "Not applicable" if MCP not in scope): ``` ## MCP Tools to Expose \| Tool name \| Service method \| Write? \| HITL? \| Auth injection \| \|-----------\|---------------\|--------\|-------\|----------------\| \| `create_foo` \| `FooService.create` \| Yes \| No \| server-side user_id \| ``` Rules: artifact 57 §3.2 (tool schema), §3.3 (auth injection — never accept user_id from args), §3.4 (write-tool policy) Mandatory Section G — Agent proofs (skip with "Not applicable" if SAO §17 is N/A or this feature does not touch agent capabilities): ``` ## Agent Proof Table \| PRF ID \| Workflow \| Script path \| Trace beats to assert \| Adverse? \| \|--------\|----------\|-------------\|----------------------\|----------\| \| PRF-SC01-04 \| munin_chat \| tests/fixtures/llm_scripts/PRF-SC01-04/happy.json \| tools_blocked: list_entities \| yes \| ``` Rules: - Map only PRF rows from SAO §17 / DTA-19 §13 that this feature affects. - Script paths under `tests/fixtures/llm_scripts/<prf-id>/` (`happy.json`, `reject_.json`). - Section D must name matching `test__agent_story_` tests for every selected PRF row. - TASK- golden tasks (lane 4) belong in SAO §17 / nightly eval — list in plan only when this slice introduces or changes a golden task fixture. - Reference: artifact 56 Part 4.5, skill Agent Integration Proof Patterns, rule `do-assert-agent-story`. Implementation Steps: 1. Backend Implementation: models, admin, services, views, URLs. Follow the Rules section below. 6. MCP Tool Registration (if SAO §18 in scope): - Declare the tool in `mcp/tools/` wrapping the service method; apply server-side auth injection. - Register with `initialize_mcp()`. - Apply stdout hygiene if stdio transport (artifact 57 §6). - Reference: artifact 57 §3–§4 7. ToolExecutor Wiring (if SAO §17 in scope): - Register the service callable in `ToolExecutor` under the tool name expected by the agent loop. - Ensure the return envelope matches the stable format. - Mark as HITL if destructive. - Reference: artifact 56 §4.3 2. Frontend Implementation: Django templates, HTMX, partials, `data-testid` attributes. 3. Testing — prove what's working: behavior tests red → green → refactor. Unit, integration (no mocks), view tests. Then log-story tests red → green in the same slice (caplog / `assert_log_story`). When Section G has rows: agent-proof tests red → green in the same slice (`@agent_proof` / `assert_agent_story` / CAP-004 ScriptedLLM). MCP tools (if Section F populated): Tests to Create table must include T1 + T2 per new tool; T3 required if stdio: - T1 (FastMCP Client): `async with Client(transport=mcp) as c: await c.call_tool(...)` — proves schema, registration - T2 (Direct service): call service with real DB — proves service/ORM wiring - T3 (subprocess JSON-RPC): proves entrypoint cleanliness (no stdout noise) - Full recipes: artifact 57 §7 4. Observability: emit INFO at decision points matching the Log Story Script (who/what/when/why, never raw secrets). Prove with caplog tests — ban deferred "informative logging pass" slices. 5. Commit Strategy: Angular convention after every principal step. Behavior + log-story (+ agent-proof when Section G populated) green in the same commit. When GitHub issue #N will hand off this plan: list one commit per implementation slice in the plan; first commit is plan/docs handoff only (`docs(plan): … Refs #N`); slice commits use `Refs #N`; final slice uses `Closes #N`. Each slice requires `gh issue comment N` with commit SHA (rule `do-github-issues`). ### Steps 7–10: Rule Confirmation, No Time Estimates, Submit for Approval, GitHub Issue Issue body must contain all seven mandatory sections inline (A–G, not linked). Each section must be self-sufficient for a cold-start implementor. When used under PIN, note that `checkpoint.log_story_command` and `checkpoint.agent_proof_command` (when Section G populated) must pass alongside the behavior checkpoint. ### Step 7: Write Lessons Learned Before creating the GitHub issue, add a `## Lessons Learned` section to the issue body. The question is open-ended: Completing this story — what difficulties did you encounter? How could the task definition, tools, and artifacts you received have been improved to make accomplishing this task easier, without creating extra duplicates or contradictions elsewhere? This is not a finite list of categories. Write freely. If something matters, write it down. Areas that often surface signal (use them if they apply, ignore if they don't): - Missing or unclear artifacts (mockups, SAO sections, feature files, skills) - Activity steps that contradicted each other, the feature spec, or `user_journey.md` - Technical decisions made during planning not yet in `docs/architecture/SAO.md` - Deviations from the written BDD scenarios (scope narrowed, step reworded, constraint added) If nothing to note: `## Lessons Learned — None.` One honest sentence beats four empty bullet points. The reader is MIN-05 closing the iteration and PIN-02 opening the next one. ### Step 8: GitHub Issue Handoff (hard gate — blocks BPE-02 / MIN-04 code) After user approves the plan and before any implementation slice (including spec/Gherkin): 1. Create GitHub issue #N — body inlines sections A–G + `## Lessons Learned` placeholder + checkpoint YAML when used under PIN. 2. Update plan INDEX with issue #N and plan link. 3. Commit docs/plan only: `docs(plan): {wave} plan and GitHub issue #N` with footer `Refs #N`. 4. Post issue comment citing handoff commit SHA and listing slice order from the plan. Do not modify `src/`, `tests/` implementation, or production templates until step 3 is committed and step 4 is posted. ## Rules Before planning and writing the implementation plan, read each Rule below in this playbook (by slug), then apply it when filling Mandatory Sections D–G and the Implementation Steps. Do not rely on memory of the rule text. Required: - `do-plan-before-doing` - `do-skeletons-first` - `do-test-first` - `do-not-mock-in-integration-tests` - `do-informative-logging` - `do-assert-log-story` - `do-assert-agent-story` (when SAO §17 in scope) - `do-write-concise-methods` - `do-docstring-format` - `do-semantic-versioning-on-ui-elements` - `do-follow-commit-convention` - `do-small-increments` - `pytest` - `do-github-issues` Activity-specific (not a substitute for the rules above): - Mandatory Section E is a Log Story Script (Where / Beat / Trigger / Must include); Section D must name matching `_log_story_` tests when Section E is non-empty. - Mandatory Section G is an Agent Proof Table when SAO §17 applies; Section D must name matching `_agent_story_` tests when Section G is non-empty. - Logging and agent proofs ship in the same green slice as behavior — ban deferred logging or agent-testing passes. ## Success Criteria - Feature specification exists and is clear - Codebase assessment complete with context map (3–5 file:line_range references) - Plan contains all seven mandatory sections: Context Map, Do-Not-Do, SAO Sections, Tests to Create, Log Story Script, MCP Tools to Expose, Agent proofs (or explicit N/A for G) - All tests explicitly listed with what they prove, including `_log_story_` when Section E has rows and `_agent_story_` when Section G has rows - All log decision points listed with Beat + required context fields - When SAO §17 in scope: PRF rows mapped with script paths and trace beats; Section D lists agent_story tests - If MCP tools added: Tests to Create table contains T1+T2 rows per new tool (T3 if stdio) - Plan reviewed and approved by user - GitHub issue created/updated with all mandatory sections inline - `## Lessons Learned` section present in the issue body - Handoff commit `docs(plan): … Refs #N` exists before any implementation commit for this feature - Plan lists slice commit boundaries; issue #N created with A–G inline before BPE-02
2	Implement Backend	BPE-2	Purpose Implement backend services, models, and views following test-first development and small increments approach. Steps …	Read the 'BPE-2 Implement Backend' activity from playbook 'Junior Edda' (workflow 'Build Feature'). Follow its guidance when assisting me. ## Purpose Implement backend services, models, and views following test-first development and small increments approach. ## Steps ### 1. Create Skeletons Create all class and method skeletons with full docstrings following your language's documentation conventions. The core principle: the developer who has no knowledge of the system can implement methods/properties etc. following only documentation in the skeleton. - Create class and method/function stubs and document them - Include full docstrings, return types, and sample return values - Use appropriate placeholder (e.g., `NotImplementedError`, `TODO`, `panic!`, etc.) - Do not skip type hints or documentation - Add comments inside the methods pointing attention to the logic flow, exception handling, logging etc. ### 2. Write Behavior Tests Before Logic Write unit tests before writing method logic using your test framework. Use real dependencies in integration scenarios - no mocking. ### 3. Implement Incrementally (behavior green) Work method-by-method. Each method/property should be: implemented → behavior-tested → log-story tested (step 4) → agent-proof tested (step 4b when declared) → committed. ### 4. Log Story — Caplog in the Same Slice For each footprint method covered by the plan's Log Story Script: 1. Write `test__log_story_happy` and/or `test__log_story_reject` (red) 2. Emit INFO logs that satisfy story beats (`entry → config → validation → processing → branch → exit → error`) per `do-informative-logging` 3. Make log-story tests green using skill Pytest Log Story Assertions (`tests/support/log_story.py` → `assert_log_story`) once TFK-02 has bootstrapped the helper — per `do-assert-log-story` 4. Never defer logging to a later "informative logging pass" slice ### 4b. Agent Proof — Same Slice (when SAO §17 / plan Section G in scope) For each PRF row in the plan's Agent Proof Table: 1. Write `test__agent_story_happy` and/or `test__agent_story_reject` marked `@pytest.mark.agent_proof` (red) 2. Queue ordered LLM scripts from `tests/fixtures/llm_scripts/<prf-id>/` via CAP-004 ScriptedLLM — only the LLM may be scripted; real DB, real tool registry 3. Make agent-story tests green using skill Agent Integration Proof Patterns (`tests/support/agent_story.py` → `assert_agent_story(...)`) per `do-assert-agent-story` 4. Assert control-plane trace beats (workflow, tools offered/called, domain effects, blackboard/plan state) — not assistant prose 5. Never defer agent proofs to a later "agent testing pass" slice ### 5. Commit After Each Step Write → run → test (behavior + log story + agent proof when declared) → evaluate → fix. Commit using Angular-style commit messages. Behavior, log-story, and agent-proof green in the same commit when declared. Issue #N (when active): footer `Refs #N` on every slice commit; immediately `gh issue comment N` with `` `{short-sha}` ``, slice summary, next slice. Do not start the next plan slice until both are done. See rule `do-github-issues`. ### 6. Backend Architecture - Services Layer: Business logic shared between different interfaces (API, Web UI, CLI, etc.) - Repository Pattern: Data access abstraction (can be swapped) - Views/Controllers: Return appropriate responses for your framework - API Endpoints: Follow RESTful or your framework's conventions - Context/State: Always validate and document ### 7. Route Registration Register new routes/endpoints with descriptive names. Follow your framework's conventions for URL/route structure. ### 8. Testing Views/Controllers Use your framework's test client. Test responses, validate context/state, check templates/views used, test dynamic endpoints. Include caplog assertions for Log Story Script rows on those views. ### 9. Scan Skills Query Playbook Skills where `capability_domain` in: - `BACKEND_FRAMEWORK` — Backend implementation patterns for your tech stack - `TEST_FRAMEWORK` — Testing patterns and best practices - `LOGGING_PATTERN` — Logging implementation for your language - `LOG_STORY_TESTING` — Pytest Log Story Assertions / caplog helpers - `AGENT_PROOF_TESTING` — Agent Integration Proof Patterns / agent_story helpers - `DOCSTRING_FORMAT` — Documentation format for your language Apply reference implementations and patterns from matched Skills. ## Rules Before implementing, read each Rule below in this playbook (by slug), then apply it to every change in this activity's footprint. Do not rely on memory of the rule text; do not paraphrase the rule body into this activity. Required: - `do-skeletons-first` - `do-test-first` - `do-not-mock-in-integration-tests` - `do-informative-logging` - `do-assert-log-story` - `do-assert-agent-story` (when plan Section G / SAO §17 PRF rows in scope) - `do-import-on-module-level` - `do-write-concise-methods` - `do-docstring-format` - `do-follow-commit-convention` - `do-small-increments` - `pytest` - `do-github-issues` Activity-specific (not a substitute for the rules above): - Log-story tests (`_log_story_` / caplog) ship in the same red→green slice as behavior — no deferred logging pass. - Agent-proof tests (`_agent_story_` / `@agent_proof`) ship in the same red→green slice as behavior when Section G declares PRF rows — no deferred agent-testing pass. ## Success Criteria - All skeletons created with full documentation - Behavior tests written before implementation and passing - Log Story Script rows proven by passing `_log_story_` caplog tests in the same commit as behavior - Agent Proof Table rows proven by passing `_agent_story_` tests in the same commit as behavior (when Section G populated) - No deferred logging or agent-proof slice in the plan - Code committed with proper messages - Every slice commit for issue #N referenced in a GitHub issue comment with SHA - Routes/endpoints properly registered - Services layer properly structured
3	Implement Frontend	BPE-3	Purpose Implement frontend templates and interactions following your framework's patterns with appropriate rendering approach. Prerequisites …	Read the 'BPE-3 Implement Frontend' activity from playbook 'Junior Edda' (workflow 'Build Feature'). Follow its guidance when assisting me. ## Purpose Implement frontend templates and interactions following your framework's patterns with appropriate rendering approach. ## Prerequisites - Backend implementation completed with passing tests - Routing defined - Review UX/design guidelines to identify sections applicable to the page/component ## Steps ### 1. Review Routing and Template Structure Check routing patterns - does anything need to be added or changed? Plan template/component hierarchy (base templates, partials, pages/components). Identify dynamic interactions needed. ### 2. Implement Templates/Components A. Page Templates/Components: Full pages (inherit from base or layout) B. Partials/Components: Reusable fragments for dynamic updates C. Dynamic Attributes: Use your framework's patterns for interactions D. Forms: Forms with appropriate validation and submission handling E. Visualizations: Embed visualizations as appropriate for your stack Add test IDs (`data-testid` or equivalent) to all interactive elements. Work in small increments. ### 3. Interaction Patterns - Navigation: Follow your framework's navigation patterns - Forms: Handle submission with validation feedback - Dynamic Lists: Refresh/update lists dynamically - Modals/Dialogs: Implement dialogs with dynamic content loading Add minimal client-side code only for: * Framework-specific enhancements * Client-side validation enhancement * Interactive effects (tooltips, hover, etc.) ### 4. Development Testing Start your development server Test in browser Check console for errors Verify forms submit correctly Test visualizations render properly Validate dynamic updates work as expected ### 5. Add Semantic Test IDs Add `data-testid` attributes using kebab-case. Use semantic names that describe purpose, not structure. Required on: buttons, links, form inputs, containers, error messages. ### 6. Styling Read `docs/ux/IA_guidelines.md` to identify what applies to the page/component and apply them. Use simple CSS, keep styles in static/css/, use semantic HTML elements, ensure responsive design. ### 7. Commit Changes Commit frontend changes using Angular-style commit messages. ### 8. Integration Validation Verify all views/controllers return correct templates/components, check dynamic interactions update correct elements, ensure forms handle validation errors properly, test visualizations render correctly, validate test IDs are present for testing. ### 9. Scan Skills Query Playbook Skills where `capability_domain` in: - `FRONTEND_FRAMEWORK` — Frontend implementation patterns for your tech stack - `UI_TESTING` — UI testing patterns and semantic naming conventions Apply reference implementations and patterns from matched Skills. ## Rules to Follow ### I. Semantic Naming for UI Elements Test Selector Hierarchy: 1. Test IDs (`data-testid` or framework equivalent) - Primary choice for all components 2. Semantic attributes (`aria-label`, role) - Secondary for semantic elements 3. Label association - For form inputs 4. Text content - Only for static, stable content 5. Avoid CSS selectors or XPath when possible Every interactive element MUST have: - Proper test ID attribute - `aria-label` or descriptive text for buttons - Associated label elements for form inputs - Unique accessible names for dialogs Hierarchical Test ID Naming: - Page-Level: `{domain}-page` - Feature Components: `{domain}-card` - Action Elements: `{action}-{domain}-button` - Form Elements: `{domain}-{field}-input` - Status/Feedback: `{type}-message` ### II. Small Increments Work in small vertical slices. After every change: write → run → test → evaluate → fix. No large PRs or 1000-line commits. ### III. UI Design Rules Action Buttons and Links: - Every action button/link should have an appropriate icon - If no icon specified in requirements, propose 3 icon options for user to choose - Icons should be semantically appropriate for the action Tooltips/Help Text: - Every action button should have helpful tooltip or help text - Active buttons: Explain clearly what will happen when clicked - Disabled buttons: Explain why it's disabled and what needs to be done to enable it - Use your framework's tooltip/help text patterns - Keep text concise but informative ### IV. Validation Checklist Before committing any component, verify all interactive elements have proper attributes and accessibility features. ## Success Criteria - All templates/components implemented with semantic markup - Dynamic interactions working as expected - All interactive elements have test ID attributes - Forms handle validation errors properly - Responsive design verified - Code committed with proper messages ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - User Journey (Document, Required) — produced by Define User Journey (#36). - IA Guidelines (Document, Required) — produced by Define Information Architecture (#37). - Screen Flow / Dialogue Map (Diagram, Required) — produced by Create Dialogue Maps (#38). - Feature Files (Document, Required) — produced by Write Feature Files (#39). - HTML Mockups (Code, Optional) — produced by Create Mockups (#40). - System Architecture Overview Template (Template, Required) — produced by Write SAO.md (#59). - Implementation Plan Template (Template, Required) — produced by Plan Feature (#96). - Definition of Done Checklist Template (Template, Required) — produced by Check Definition of Done (#101).
4	Implement Feature Acceptance Tests	BPE-4	APPEND TO GUIDANCE: TFK Integration: Behave-Based Acceptance Tests Feature acceptance tests are executed via behave-django …	Read the 'BPE-4 Implement Feature Acceptance Tests' activity from playbook 'Junior Edda' (workflow 'Build Feature'). Follow its guidance when assisting me. APPEND TO GUIDANCE: --- ## TFK Integration: Behave-Based Acceptance Tests Feature acceptance tests are executed via behave-django against `.feature` files in `docs/features/` (spec + AT runner — single source of truth). There is no separate `tests/acceptance/` tree and no promote/copy step. ### Updated Process 1. Locate spec: Find the feature's BDD scenarios in `docs/features/act-/`. 2. Verify steps exist: Check that all steps used in the spec have implementations in `docs/features/steps/`. If any are missing, invoke TFK-07. 3. Remove `@wip` when ready: Tag unimplemented scenarios `@wip` during ESM; remove the tag when implementation is complete so CI runs them (`behave.ini` uses `tags = ~@wip`). 4. Prepare fixtures: Check the Fixture Library Catalog for needed test data. If presets are missing, invoke TFK-07. 5. Run acceptance tests: `make test-at` (runs `docs/features/` via `behave.ini`). 6. The dual approach remains: Django test client unit/integration tests remain valuable for fast feedback. Behave AT runs the same scenarios through the BDD layer. Both must pass. ### Key Principle Acceptance tests are the real thing minus the GUI (Django test client — not Playwright). No mocking. The `.feature` file in `docs/features/` IS the grounding executable requirements document for AT. ## Skills (additional) - Behave-Django BDD Runner* (BDD_RUNNER) ## Inputs (additional) - Step Library Catalog (Document, Required) — produced by TFK-03. - Fixture Library Catalog (Document, Required) — produced by TFK-04. - Behave Configuration (Code, Required) — produced by TFK-02 (Artifact #51). --- ## TFK Integration: Behave-Based Acceptance Tests Feature acceptance tests are executed via behave-django against `.feature` files in `docs/features/` (spec + AT runner — single source of truth). There is no separate `tests/acceptance/` tree and no promote/copy step. ### Updated Process 1. Locate spec: Find the feature's BDD scenarios in `docs/features/act-/`. 2. Verify steps exist: Check that all steps used in the spec have implementations in `docs/features/steps/`. If any are missing, invoke TFK-07. 3. Remove `@wip` when ready: Tag unimplemented scenarios `@wip` during ESM; remove the tag when implementation is complete so CI runs them (`behave.ini` uses `tags = ~@wip`). 4. Prepare fixtures: Check the Fixture Library Catalog for needed test data. If presets are missing, invoke TFK-07. 5. Run acceptance tests: `make test-at` (runs `docs/features/` via `behave.ini`). 6. The dual approach remains: Django test client unit/integration tests remain valuable for fast feedback. Behave AT runs the same scenarios through the BDD layer. Both must pass. ### Key Principle Acceptance tests are the real thing minus the GUI (Django test client — not Playwright). No mocking. The `.feature` file in `docs/features/` IS the grounding executable requirements document for AT. ## TFK boundary: AT (user-visible) vs `@agent_proof` pytest Do not* express agent orchestration proofs as Behave scenarios. \| Concern \| Layer \| Runner \| Marker / location \| \|---------\|-------\|--------\|-------------------\| \| User-visible behavior, screens, HTMX, API responses humans see \| AT \| behave-django (`make test-at`) \| `.feature` in `docs/features/` \| \| Agent control-plane wiring (PRF-): tool allowlists, blackboard, plan handoff, HITL gates, 429 retry \| Integration \| pytest `@pytest.mark.agent_proof` \| `tests/integration/agent/` \| \| Deterministic shell (lane 2): D0 pre-filter, JSON parse, validate-before-LLM \| Integration \| pytest (no `@agent_proof`) \| `tests/integration/` \| \| Model quality / golden tasks (TASK-, lane 4) \| Eval \| pytest `@pytest.mark.quality` + `@pytest.mark.live_llm` \| `tests/fixtures/agent_tasks/` — nightly, not AT \| Rules: - AT proves what the user sees — forms, redirects, ChangeSet approval UI, error messages. - `@agent_proof` proves what the agent loop did under CAP-004 ScriptedLLM — trace beats via `assert_agent_story`, not chat prose assertions in Gherkin. - When a feature touches both surfaces, BPE-04 adds/updates `.feature` scenarios and BPE-02 (or the agent slice) adds `@agent_proof` tests — both green before DoD; neither substitutes for the other. - Skip `@agent_proof` rows in BPE-04 when SAO §17 is N/A. ## Skills (additional) - Behave-Django BDD Runner (BDD_RUNNER) - Agent Integration Proof Patterns (TEST_INTEGRATION) — when SAO §17 in scope; AT does not replace this skill ## Inputs (additional) - Step Library Catalog (Document, Required) — produced by TFK-03. - Fixture Library Catalog (Document, Required) — produced by TFK-04. - Behave Configuration (Code, Required) — produced by TFK-02 (Artifact #51). - Agent Proof Table (from BPE-01 Section G, when SAO §17) — PRF rows map to pytest, not `.feature` files.
5	Implement Journey Certification Tests	BPE-5	APPEND TO GUIDANCE: TFK Integration: E2E Infrastructure Journey certification tests that require browser-based Playwright execution …	Read the 'BPE-5 Implement Journey Certification Tests' activity from playbook 'Junior Edda' (workflow 'Build Feature'). Follow its guidance when assisting me. APPEND TO GUIDANCE: --- ## TFK Integration: E2E Infrastructure Journey certification tests that require browser-based Playwright execution use TFK's E2E infrastructure under `tests/e2e/`. ### E2E vs AT (clarification) - AT (BPE-04): Proves one particular feature works. `docs/features/` via Django test client (`behave --simple`). Fast. Every CI run. - E2E (BPE-05): Proves the ability to fulfill a goal using system means. `tests/e2e/` via Playwright + LiveServer. Sequential. Screenshots. Staging / release certification. Same Gherkin phrases (catalog); separate step implementations and `environment.py`. ### Using TFK E2E Infrastructure 1. Locate journey intent: Read `docs/features/user_journey.md` for the multi-screen goal. 2. Write E2E `.feature`: Add journey scenarios to `tests/e2e/` (optionally tag `@e2e`). 3. Write as multi-phase .feature: One long sequential `.feature` file with multiple scenarios. 4. Environment targeting: Use `--base-url` to point at any environment. 5. Screenshots: `tests/e2e/environment.py` automatically captures screenshots after every step. 6. Data preparation: E2E tests use `--db-uri` to load initial data via loaddump. 7. Run: `make test-e2e` → `manage.py behave tests/e2e/`. ## Inputs (additional) - E2E Test Configuration (Code, Required) — produced by TFK-06. - Fixture Library Catalog (Document, Required) — produced by TFK-04.
6	Check Definition of Done	BPE-6	Purpose Validate that feature/story implementation complies with all project rules and standards by examining current …	Read the 'BPE-6 Check Definition of Done' activity from playbook 'Junior Edda' (workflow 'Build Feature'). Follow its guidance when assisting me. ## Purpose Validate that feature/story implementation complies with all project rules and standards by examining current state and outputs. ## Core Development Rules Checklist ### Test-First Development - [ ] Every function/method has corresponding test(s) - [ ] Feature files in `docs/features/` exist and comply with scenarios - [ ] Tests use pytest framework - [ ] Mocking is minimal ### Continuous Testing - [ ] All tests are runnable via `pytest tests/` - [ ] Tests are pytest compatible with proper fixtures - [ ] `tests.log` file exists and contains test output ### Concise Methods - [ ] Top-level (public) methods are 20-30 lines maximum - [ ] Supporting logic is in well-named private methods - [ ] Helper methods have single, focused responsibilities - [ ] Method names are descriptive and clear ## Code Quality Rules Checklist ### Import Management - [ ] All imports are at module level - [ ] No imports inside functions/methods - [ ] Dependencies are properly declared ### Log Story Verification - [ ] Implementation plan / issue contains a Log Story Script (Where / Beat / Trigger / Must include) - [ ] Every script row is proven by a passing `_log_story_` caplog test (or `checkpoint.log_story_command` from the iteration manifest) - [ ] Happy and reject paths covered when the scenario has both - [ ] Log levels are appropriate (DEBUG, INFO, WARNING, ERROR) - [ ] No secrets/tokens/passwords appear at INFO in asserted lines - [ ] No deferred logging slice remains in the plan Grep of `logs/app.log` is an audit aid, not the DoD gate. Caplog (or `log_story_command`) is the gate. ### Agent Proof Verification (when SAO §17 / plan Section G in scope) - [ ] Implementation plan / issue contains an Agent Proof Table (PRF ID, workflow, script path, trace beats) - [ ] Every PRF row is proven by a passing `_agent_story_` test marked `@pytest.mark.agent_proof` (or `checkpoint.agent_proof_command` from the iteration manifest) - [ ] Happy and reject paths covered when the PRF is adverse or has a reject sketch - [ ] Tests use CAP-004 ScriptedLLM only — no `FakeLLM`, no `@patch` on ToolExecutor or domain services in `@agent_proof` tests - [ ] LLM scripts exist under `tests/fixtures/llm_scripts/<prf-id>/` for every asserted path - [ ] Trace asserts control-plane beats (tools, domain writes, plan/blackboard state) — not assistant wording - [ ] No secrets/tokens/passwords in trace or asserted log lines - [ ] No deferred agent-proof slice remains in the plan - [ ] TASK-* lane 4 evals (if any) are not required for story DoD — confirm they remain on nightly/promotion band only Grep of run logs is an audit aid, not the DoD gate. `assert_agent_story` (or `agent_proof_command`) is the gate. ## Testing and Quality Assurance Checklist ### Integration Test Standards - [ ] Integration tests in `tests/integration/` exist - [ ] Integration tests avoid mocking (except CAP-004 ScriptedLLM in `@agent_proof` tests) - [ ] Real dependencies are used in integration scenarios ### Commit Conventions - [ ] Recent commit messages follow Angular conventional format - [ ] Commits are atomic and focused - [ ] Breaking changes are documented in commit messages ## UI and Frontend Rules Checklist ### Django Views + HTMX - [ ] No DRF views exist for new web UI features - [ ] Django views return HTML templates - [ ] HTMX attributes used for dynamic interactions - [ ] Services layer is shared between MCP and Web UI ### Semantic Naming - [ ] All interactive elements have `data-testid` attributes - [ ] Naming follows kebab-case convention - [ ] Form inputs have proper name and id attributes ## Documentation Checklist ### Scenario Writing - [ ] BDD scenarios exist for features - [ ] Feature files are well-structured - [ ] Scenarios cover edge cases and error conditions - [ ] Review GUI - do scenarios match behavior, fields, URLs, design rules? Report inconsistencies to user ### TODO Management - [ ] TODO comments exist for incomplete implementations - [ ] TODO items have clear descriptions - [ ] TODOs in dependencies can be ignored ### Document Updates - [ ] Review code: new packages, patterns, approaches worth documenting? - [ ] Review conversation: need to update feature files/corrections? - [ ] Review modus operandi against workflows and rules - can we improve? ## Final Validation Checklist ### Overall Quality Check - [ ] Feature meets acceptance criteria - [ ] Code is production-ready - [ ] Documentation exists and is accurate ### Integration Validation - [ ] Feature integrates with existing system - [ ] No breaking changes introduced - [ ] Dependencies properly declared in requirements.txt ### Deployment Readiness - [ ] Database migrations exist if needed - [ ] Environment variables are documented - [ ] Configuration changes are documented ### Cleanup - [ ] Remove temporary files like debug_.py - [ ] Scan file structure for stray misplaced files - [ ] Remove .log files from repository ## Rules Before validating DoD, read each Rule below in this playbook (by slug), then apply it as the acceptance criterion for the matching checklist items. Do not rely on memory of the rule text. Required: - `do-test-first` - `do-continuous-testing` - `do-write-concise-methods` - `do-import-on-module-level` - `do-informative-logging` - `do-assert-log-story` - `do-assert-agent-story` (when SAO §17 / Section G in scope) - `do-not-mock-in-integration-tests` - `do-follow-commit-convention` - `do-semantic-versioning-on-ui-elements` - `do-write-scenarios` - `do-add-todos-for-incomplete-items` - `pytest` Activity-specific (not a substitute for the rules above): - Observability DoD is Log Story Verification (caplog / `log_story_command`), not "logging statements exist". - Agent DoD is Agent Proof Verification (`agent_proof_command` / `@agent_proof`), not "the agent loop exists" or Behave AT alone. ## Actions All checkboxes must be completed before considering the story "Done". Any deviations must be presented to user. If user says "collect for cleanup but defer" - create a Backlog item in GitHub as Issue with "deferred" tag. Otherwise resolve deviations as directed by user, commit following Angular convention, and send Pull Request. ## Success Criteria - All checklist items verified - No deviations or all approved by user - Code production-ready - Ready for PR ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - Feature Files (Document, Required) — produced by Write Feature Files (#39). - Implementation Plan Template (Template, Required) — produced by Plan Feature (#96). ## Defects Found During DoD When DoD review reveals a defect (behavior does not match feature files or acceptance criteria) — not a deferred cleanup item: 1. File a Bug Report via `report_bug` MCP tool or Feedback UI (see Bug Report artifact for body structure) 2. Invoke Fix Bug (BPE-09) with the Bug Report as input 3. Do not mark the story done until blockers are resolved and BPE-09 success criteria are met
7	Finalize Feature	BPE-7	Purpose Finalize feature with testing, validation, and deployment preparation. Steps 0. Run All Tests Run …	Read the 'BPE-7 Finalize Feature' activity from playbook 'Junior Edda' (workflow 'Build Feature'). Follow its guidance when assisting me. ## Purpose Finalize feature with testing, validation, and deployment preparation. ## Steps ### 0. Run All Tests Run all tests and ensure none are broken. If there are discrepancies between test expectations and implementation - ask user to clarify what takes precedence. Mark scenarios with "done" emoji and add "completed" tag. ### 1. Identify E2E Test Identify Playwright E2E test for this feature/scenario. If there is none - ask user if they want to create one. ### 2. Run Development Server and Validate Auto-run: Start the server: `python manage.py runserver` Execute Playwright tests to ensure they pass. Fix any issues found during testing. ### 3. Run Full Test Suite Auto-run: Execute all unit tests, integration tests, and E2E tests. Ensure no regressions were introduced. Fix any failing tests. ### 4. Update Project Dependencies Add any new packages to requirements.txt that were added during feature development. Use `pip install <package>` to add new dependencies. Ensure version constraints are appropriate. Test that `pip install -r requirements.txt` works in a fresh venv. ### 5. Present Completed Work Summarize implemented features and changes. Show test results and coverage. Demonstrate functionality if possible. ### 6. Final Commit Check if there is a corresponding issue. Update the status with the latest changes and associate commit. Commit all remaining changes using Angular-style commit messages. Ensure commit message clearly describes the completed feature. ### 7. Handle Feature Branch If on feature branch - ask user if they want to send a PR or merge into main. ### 8. Update Screen Flow Diagram Update `docs/ux/2_dialogue-maps/screen-flow.drawio` to mark completed screens with green borders: - Change `strokeColor=#1565c0` to `strokeColor=#22c55e` (green) - Add `strokeWidth=3` if not present - Add ✅ emoji prefix to screen labels - This indicates feature completion per the diagram legend ### 9. Close and Mark Complete Close issue if exists, review and mark all todos as "done" in the implementation plan, and update scenario and/or feature with "done" emoji. ## Rules to Follow ### I. 100% Test Pass Rate Required Only 100% test pass rate can be reported as "success" or "complete". 92%, 95%, 99% are NOT success. Any failing tests must be fixed before declaring feature complete. Cannot mark features as "done" or "production-ready" with failing tests. Test failures must be resolved, not deferred or ignored. Exception: Only if user explicitly approves deferring specific test scenarios can they be excluded from the count. ### II. Fix Tests Immediately Failing tests are major problem - we don't start new development until we fix them. ### III. Commit Convention Follow Angular convention with proper type, scope, subject, body, and footer. ## Success Criteria - All tests passing (100% pass rate) - Dependencies updated in requirements.txt - Final commit made with clear message - Issue updated and closed - Implementation plan marked complete - Feature file updated with completion markers ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - Screen Flow / Dialogue Map (Diagram, Optional) — produced by Create Dialogue Maps (#38). - Implementation Plan Template (Template, Required) — produced by Plan Feature (#96). - Definition of Done Checklist Template (Template, Required) — produced by Check Definition of Done (#101). ## Defects Found During Finalization When testing or validation reveals a defect (failing test that exposes a real bug, user-reported issue during demo, or ERROR in `logs/app.log` tied to broken behavior): 1. File a Bug Report via `report_bug` MCP tool or Feedback UI (see Bug Report artifact for body structure) 2. Invoke Fix Bug (BPE-09) — do not patch ad hoc without the test-first workflow 3. Do not declare the feature complete until BPE-09 success criteria are met (100% regression green)
8	Process Change Request	BPE-8	Purpose Process an enhancement or change request by reconciling requirements across the spec stack, agreeing …	Read the 'BPE-8 Process Change Request' activity from playbook 'Junior Edda' (workflow 'Build Feature'). Follow its guidance when assisting me. ## Purpose Process an enhancement or change request by reconciling requirements across the spec stack, agreeing a target state with the user, then closing with an approved reconciliation record and in-place spec updates. This activity does not implement code. ## Requirements Sources Reconcile across all layers that exist in this project. Read what is present; skip absent layers and note the gap in the matrix. For each affected Screen ID, build a reconciliation matrix: \| Layer \| Typical source \| Activity \| Current state \| Drift? \| Notes \| \|-------\|----------------\|----------\|---------------\|--------\|-------\| \| User journey \| User Journey document \| Define User Journey \| — \| Y/N \| Screen narrative \| \| Scenarios \| Feature files (Gherkin) \| Write Feature Files \| — \| Y/N \| Executable requirements \| \| Mockups \| HTML mockups / prototypes \| Create Mockups \| — \| Y/N \| UX validation screens \| \| Screen flow \| Dialogue map \| Create Dialogue Maps \| — \| Y/N \| Navigation flow \| \| IA guidelines \| IA guidelines \| Define Information Architecture \| — \| Y/N \| Design system rules \| \| Prior plan \| Implementation plan \| Plan Feature \| — \| Y/N \| What was planned \| \| Architecture \| SAO.md \| Write SAO.md \| — \| Y/N \| As-designed constraints \| \| As-built \| Code, templates, tests \| BPE-02–07 \| — \| Y/N \| What shipped \| ## Steps ### 1. Reconcile Requirements (read-only first) - Read inputs per ## Inputs below - Read the change request thoroughly; identify affected Screen IDs and scope - Read user journey — locate affected screen sections - Read feature files — locate affected scenarios - Read mockups — locate affected prototype screens - Read screen flow and IA guidelines when UI or navigation is in scope - Read SAO.md for architectural constraints touched by the change - Inspect as-built code and tests for the same Screen IDs - Flag conflicts between layers; do NOT assume — list open questions - If you don't understand user intent or UX details — ASK Fast path: If the matrix shows zero drift across all present spec layers and the change is purely cosmetic with no scenario impact, document the empty matrix and note minimal delta in the reconciliation document. ### 2. Propose Target State - Draft in-place revisions to canonical consumed artifacts (only layers where drift was found). Do not create parallel "Updated " copies — revise the same User Journey, Feature Files, Mockups, Screen Flow, and IA documents the project already uses. - Create Change Reconciliation Document* at `docs/plans/{FEAT}_CHANGE_RECONCILIATION.md` containing: - Trigger (change request summary) - Reconciliation matrix (from Step 1) - Proposed spec diffs (summary + file paths) - Open questions for user - Fast-path justification (if applicable) - Present target state to user; ask clarification questions - Gate: User must approve target state before closing this activity ### 3. Close Reconciliation - Ensure approved Change Reconciliation Document is saved at `docs/plans/{FEAT}_CHANGE_RECONCILIATION.md` - Ensure in-place revisions to canonical spec artifacts are complete (Step 2) - Technical replanning and implementation are out of scope for this activity — the human may invoke Plan Feature (Activity 96) separately when ready ## Rules to Follow ### I. Do Not Assume If unclear — ASK. Never guess user intent or implementation details. ### II. Spec Before Code Reconcile and update requirements artifacts before any implementation planning or coding. ### III. No Execution in Process Change Request Implementation, testing, and commits happen in later Build Feature activities after separate planning approval. ### IV. Traceability Every affected Screen ID must appear consistently across all present spec layers. Verify with project grep conventions. ## Success Criteria - Change request captured and understood - Reconciliation matrix complete for all affected Screen IDs - Canonical spec artifacts revised in place or explicitly marked unchanged (fast path) - Change Reconciliation Document created, saved, and user-approved - No code changes made during this activity ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - User Journey (Document, Required) — produced by Define User Journey (#36). - Screen Flow / Dialogue Map (Diagram, Required) — produced by Create Dialogue Maps (#38). - Feature Files (Document, Required) — produced by Write Feature Files (#39). - HTML Mockups (Code, Optional) — produced by Create Mockups (#40). - IA Guidelines (Document, Optional) — produced by Define Information Architecture (#37). - System Architecture Overview Template (Document, Required) — produced by Write SAO.md (#59). - Implementation Plan Template (Template, Required) — produced by Plan Feature (#96). - Definition of Done Checklist Template (Template, Required) — produced by Check Definition of Done (#101).
9	Fix Bug	BPE-9	Purpose Fix a reported defect using a test-first workflow: prove the bug with a failing …	Read the 'BPE-9 Fix Bug' activity from playbook 'Junior Edda' (workflow 'Build Feature'). Follow its guidance when assisting me. ## Purpose Fix a reported defect using a test-first workflow: prove the bug with a failing test, implement the fix, prove green, run full regression, then gate integration/PR/hotfix decisions with the user. This activity implements code. It does not reconcile requirements — use Process Change Request (#103) for scope or spec changes. ## Prerequisites - A Bug Report (GitHub Issue) filed via `report_bug` MCP tool or the Feedback UI - Bug may have been filed during Check Definition of Done (#101), Finalize Feature (#102), or Acceptance, Bug Reports & Deploy Fixes (#183) ## Steps ### 1. Analyze Why Tests Missed the Bug - Read the Bug Report thoroughly (Description, Reproduction, Environment, severity if present) - Identify affected feature files, scenarios, Screen IDs, and code paths - Determine why existing tests did not catch the defect — missing scenario, weak assertion, wrong test layer, integration gap, flaky test, etc. - Document the gap briefly (issue comment or working notes) ### 2. Add or Extend Tests (Red) - Write or extend tests that reproduce the bug — they must fail before the fix - Prefer the lowest appropriate layer per SAO Test Strategy: unit → integration → AT (`docs/features/`) → E2E (`tests/e2e/`) - Follow `do-test-first` and `do-not-mock-in-integration-tests` - Run the new or extended test(s) and confirm they fail for the expected reason ### 3. Implement the Fix - Implement the minimal correct fix - Keep scope focused — no unrelated refactors ### 4. Prove the Fix (Green) - Run the new or extended test(s) — must pass - If UI or journey behavior changed, re-run relevant BPE-04 / BPE-05 checkpoints for the affected scenario ### 5. Full Regression - Run the full test suite: `pytest tests/` - Run E2E suite when UI or journey paths changed: `pytest tests/e2e/` - 100% pass rate required before closing — same standard as Finalize Feature (#102) ### 6. Commit and User Gate - Commit with Angular convention: ```bash git add -A git commit -m "fix({scope}): {bug title}" ``` - Ask the user: 1. Integrate or submit PR? — merge to main locally, or open / submit a pull request? 2. Hotfix deployment needed? — if production is affected, coordinate a patch release per MIN-06 / deployment playbook - Do not push until the user approves ## Rules to Follow Before fixing, read each Rule below in this playbook (by slug), then apply it: - `do-test-first` - `do-not-mock-in-integration-tests` - `do-follow-commit-convention` - `do-small-increments` - `do-informative-logging` (when the fix touches decision points) ## Success Criteria - Root cause of the test gap identified and documented - Failing test proves the bug before the fix - Fix implemented; proving tests pass - Full regression green (100% pass rate) - Commit made; user decision recorded on integrate / PR / hotfix ## Inputs Read these before starting this activity. - Bug Report (Document, Required) — produced by Check Definition of Done (#101), Finalize Feature (#102), or Acceptance, Bug Reports & Deploy Fixes (#183) via `report_bug` MCP tool or Feedback UI.

Activities in Build Feature