Map Monthly Tax Report workflow to operator-ready docs and metadata

[alexeygrigorev]

Map Monthly Tax Report workflow to operator-ready process docs and metadata

Status: pending
Tags: docs, process-docs, work-engine, data, P1
Depends on: None
Blocks: None

Scope

Turn the Monthly Tax Report process from a docs/Trello-derived checklist into an operator-ready DataOps workflow that can be generated automatically, shown on the dashboard as due/overdue/follow-up work, completed only with required proof, and opened with the right SOPs in context.

This issue covers the Git-backed process docs and executable workflow metadata only. Update the DataOps repo; do not edit ../dtc-operations, ../datatasks, or ../podcast-assistant.

Primary files to inspect and update:

• content/tasks/templates/tax-report.md
• work-engine/scripts/seed-templates.ts
• work-engine/docs/templates.md
• content/finance/tax-reporting/sops/monthly-tax-report.md
• Related finance docs as needed, especially:
  • content/finance/bookkeeping/sops/preparing-a-zip-archive-with-invoices-and-send-reports-to-the-accountant.md
  • content/finance/bookkeeping/sops/sending-reports-to-accountants-for-bookkeeping.md
  • content/finance/bookkeeping/sops/for-update-converting-usd-to-eur-for-revolut-transcations.md
  • content/finance/reference/invoices-receipts-and-statements.md

Bring the tax-report task template up to the same operator-ready standard as richer templates such as content/tasks/templates/podcast.md: include workflow definition, phases, reminders, risk/waiting semantics, task execution matrix, sample instantiation, required proof, contextual SOP references, and reconciliation notes.

Operator JTBD

When the operations manager opens DataOps at the start of each month, they should see the Monthly Tax Report workflow generated automatically and know exactly what to do next without opening Trello or reconstructing the process from scattered Google Docs.

Concrete operator actions to encode:

• Recurring schedule: generate the Monthly Tax Report workflow from the tax-report template at 0 9 1 * * with triggerLeadDays: 0.
• Due tasks: create the monthly workflow with sequential due dates from day 1 through day 8 of the month, using the first day as the anchor date.
• Contextual SOPs: every task that has an SOP must expose it through instructionsUrl or the task-template context matrix, so the workflow remains primary and docs are opened only at the moment of need.
• Required proof/files/links: completion must require the evidence that proves the external finance action happened, especially monthly spreadsheet/report link, Finom statement file, Revolut statement file, tax ZIP file, accountant upload/share link, and accountant email/thread proof.
• Follow-ups: if missing receipts/invoices/statements, unclear EUR amounts, or accountant acknowledgment block completion, the operator must be able to move the relevant task to waiting with waitingFor, followUpAt, and a note. Follow-up reminders must use existing follow-up-due semantics.
• Completion criteria: the workflow can reach done only after all required proof is present, the accountant package has been uploaded/sent, required folders have been organized, no TODO values remain for reportable transactions, and no waiting follow-up is due.
• Reminders: due and overdue reminders should naturally come from task due dates; missing-evidence reminders should be described for tasks that require files/links; accountant/missing-document follow-ups should use waiting-task reminders.
• Data safety: documentation and metadata must tell implementers/operators not to hardcode accountant upload URLs as secrets, not to attach real sensitive finance files to Git, and to rely on runtime file/link proof plus portable export/restore safety for workflow state.

Workflow Mapping Requirements

Keep existing task refs stable unless a change is necessary and documented in reconciliation notes. The current seed has 9 tasks; preserving 9 tasks is acceptable if the operator matrix and proof gates make the process complete. If tasks are split or renamed, update all seed/export/docs tests accordingly and explain the change in content/tasks/templates/tax-report.md.

Minimum task semantics:

Ref ID	Due Offset	Operator action	Required proof / completion gate	Waiting or follow-up path	Context
open-bookkeeping-report	0	Open the monthly bookkeeping/tax report for the specific month and attach the relevant report or spreadsheet link to the workflow.	URL proof for the month-specific report/spreadsheet range, or clear explanation if the fixed reference is reused.	Waiting if access to the report is missing.	Monthly Tax Report SOP and bookkeeping spreadsheet reference.
review-update-todos	1	Review Dropbox documents, receipts, invoices, and spreadsheet rows; replace TODO values with actual numbers.	Completion comment or external-status proof that no reportable transaction has unresolved TODO; missing documents are listed.	Waiting for Alexey, Valeriia, invoice owner, or document provider when a document/value is missing.	Monthly Tax Report SOP and invoices/receipts/statements reference.
convert-currencies	2	Convert USD/non-EUR transactions to EUR using Wise/Revolut evidence and update the spreadsheet.	Completion comment with conversion source/date or linked conversion evidence when needed.	Waiting for transaction screenshot/source value when the EUR amount cannot be determined.	Currency conversion SOP.
create-bank-statements-finom	3	Download/create the Finom bank statement for the month.	File required.	Waiting if Finom access or statement export is unavailable.	Finom bank statement SOP.
create-bank-statements-revolut	3	Download/create the Revolut bank statement for the month.	File required.	Waiting if Revolut access or statement export is unavailable.	Revolut bank statement SOP.
cross-check-revolut-finom	4	Cross-check Finom and Revolut transactions against the bookkeeping spreadsheet and add missing income/expenses.	Completion comment or external-status proof that Finom/Revolut counts and monthly report rows were reconciled; unresolved exclusions are documented.	Waiting for missing invoice/receipt, income invoice, Alexey clarification, or accountant/accounting rule clarification.	Monthly Tax Report SOP plus invoices/receipts/statements reference.
prepare-zip-send-accounting	5	Prepare the datatalksclub-YYYY-MM.zip package and upload it to the accountant handoff destination.	File required for the ZIP plus required URL/link proof for upload/share confirmation.	Waiting if a required file is still missing or upload destination is unavailable.	Zip/archive SOP.
notify-accountants	6	Send the accountant email with the monthly report summary and uploaded package reference, cc Alexey.	Required proof should be a Gmail thread URL, sent-email link, or explicit completion comment if URL capture is not supported.	Waiting for accountant acknowledgment or clarification, with follow-up due date.	Sending reports SOP and email template.
organize-invoices-folders	7	Move processed expense and incoming invoice files into the correct processed folders and close the monthly workflow.	Completion comment or external-status proof that folders were organized; this task moves the bundle to done.	Waiting if cleanup is blocked by unresolved missing files.	Zip/archive SOP and Dropbox folder guidance.

Required bundle/runtime links should include at least the month-specific report/spreadsheet link, accountant upload/share confirmation, and accountant email thread if supported by existing bundleLinkDefinitions/requiredLinkName fields. Fixed SOP/reference links should remain references, not bundle links.

Acceptance Criteria

• content/tasks/templates/tax-report.md is self-contained and operator-ready: it has stable frontmatter, workflow definition, phases/stages, recurring schedule, bundle title pattern, done criteria, reminder/risk/waiting semantics, data-safety notes, task execution matrix, sample instantiation, and updated task definitions.
• work-engine/scripts/seed-templates.ts encodes the tax-report workflow metadata needed by runtime generation: automatic trigger 0 9 1 * *, correct default assignee, references, bundle link definitions, instructions URLs, required links, required files, and stageOnComplete: 'done' on the final closure task.
• Required proof gates are explicit and enforced by existing fields where available: Finom statement file, Revolut statement file, tax ZIP file, upload/share link, and accountant email/thread proof or documented completion comment fallback.
• The monthly workflow docs explain how due, overdue, missing-evidence, and waiting/follow-up reminders should behave for this process using the existing work-engine task status model (todo, waiting, done, archived) and follow-up-due notifications.
• SOP context is mapped from each task to the relevant process document or template. Empty instruction links are either filled with local content docs/known process docs or documented as intentional gaps for later follow-up.
• Finance SOPs touched by this issue include concrete validation/troubleshooting/reference content instead of placeholder - sections where those sections are needed to complete the operator flow.
• The seed/template docs and content/tasks/templates/tax-report.md agree on task count, ref IDs, offsets, required proof, and stage transition behavior.
• Tests are updated or added so seeded tax-report metadata fails if the schedule, task refs, required files/links, instructions URLs, bundle links, or done stage regress.
• No real finance files, account secrets, accountant credentials, or private monthly report data are committed to Git. Only process docs, metadata, stable references, and non-secret examples are stored in the repo.
• Labels on the GitHub issue are updated to remove needs grooming and keep/add the implementation labels: docs, process-docs, work-engine, data, P1.

Test Scenarios

Scenario: Automatic monthly workflow is generated with due tasks

Given: The seeded Tax Report template is loaded.
When: The work-engine cron runner evaluates 0 9 1 * * for the first day of a month.
Then: A tax-report bundle is generated once for that schedule window, its source is automatic/template-driven, and its tasks are due on offsets 0 through 7 from the monthly anchor date.

Scenario: Required proof blocks premature completion

Given: A Monthly Tax Report bundle exists.
When: The operator tries to complete Finom statement, Revolut statement, ZIP/upload, or accountant-email proof tasks without the required file/link/comment proof defined by the template.
Then: Completion is blocked where the current work-engine supports blocking, or the docs clearly identify the manual proof/comment fallback where blocking is not yet modeled.

Scenario: Missing document becomes a follow-up

Given: During reconciliation, an invoice/receipt/EUR value/accountant reply is missing.
When: The operator sets the relevant task to waiting with waitingFor, followUpAt, and a note.
Then: The task remains active, appears as a due follow-up when followUpAt arrives, and the workflow cannot be considered done while the follow-up is unresolved.

Scenario: SOPs are available in context

Given: The operator opens any Monthly Tax Report task in the workflow.
When: The task requires process guidance.
Then: The task exposes the relevant SOP/template/reference link directly, including monthly report, document classification, currency conversion, bank statements, ZIP preparation, accountant email, and folder cleanup guidance.

Scenario: Done only after accountant handoff and cleanup

Given: All report values are reconciled and required statements/ZIP/upload/email proof are present.
When: The operator completes organize-invoices-folders.
Then: The bundle moves to done, completed tasks remain available for audit, and no required proof or waiting follow-up is missing.

Scenario: Data safety is preserved

Given: The implementation updates process docs and metadata.
When: A reviewer inspects the diff and portable export behavior.
Then: No real sensitive finance files or secrets are in Git, required runtime file/link proof remains portable, and export/restore validation still protects required-link, required-file, waiting, and follow-up records.

Out of Scope

• Implementing new finance integrations with Finom, Revolut, Wise, Dropbox, Gmail, Google Sheets, or accountant upload systems.
• Sending real accountant emails, uploading real tax packages, downloading live bank statements, or validating production credentials.
• Changing source repos outside dataops.
• Building new UI primitives for task statuses, follow-up notifications, or file upload unless existing tests show the current primitives cannot represent this workflow at all.
• Migrating historical monthly tax reports or backfilling completed workflow runs.
• Legal/tax advice or changing accountant reporting rules.

Dependencies

• Existing work-engine task/template fields: triggerType, triggerSchedule, triggerLeadDays, references, bundleLinkDefinitions, instructionsUrl, requiredLinkName, requiresFile, stageOnComplete, status, waitingFor, and followUpAt.
• Existing content/search metadata conventions for task templates, SOPs, references, and templates.
• Existing finance process docs listed in Scope. If a referenced SOP is missing or too incomplete, document the gap in the tax-report template reconciliation notes and keep implementation scoped to available docs.

Verification Commands

Run the relevant docs/content and work-engine verification before handing to Tester:

npm --prefix work-engine test
npm --prefix work-engine run typecheck
npm --prefix work-engine run build
npm --prefix work-engine run test:e2e
uv run --project lambda-functions --extra search --with pytest python -m pytest tests/docs_app
cd lambda-functions && uv run --extra search python -m lambda_functions.build_search_index --docs-dir ../content --output ../.tmp/dataops-content-search.index

If full E2E is intentionally narrowed during development, explain why in the implementation handoff and still run focused seed/template/cron/proof-gate tests that cover every acceptance criterion touched by this issue.

[alexeygrigorev]

PM grooming complete. I rewrote the issue as a self-contained implementation spec covering the Monthly Tax Report operator workflow, recurring schedule, task/proof metadata, SOP context, follow-up/reminder behavior, data-safety boundaries, acceptance criteria, test scenarios, dependencies, labels, and verification commands. Removed needs grooming; the issue is ready for Software Engineer implementation.

[alexeygrigorev]

READY FOR TEST

Implemented the Monthly Tax Report workflow mapping locally in the issue #37 worktree. No commit/push/merge/close performed.

Changed files:

• content/tasks/templates/tax-report.md
• work-engine/scripts/seed-templates.ts
• work-engine/tests/seed.test.ts
• work-engine/docs/templates.md
• content/finance/tax-reporting/sops/monthly-tax-report.md
• content/finance/bookkeeping/sops/preparing-a-zip-archive-with-invoices-and-send-reports-to-the-accountant.md
• content/finance/bookkeeping/sops/sending-reports-to-accountants-for-bookkeeping.md
• content/finance/bookkeeping/sops/for-update-converting-usd-to-eur-for-revolut-transcations.md
• content/finance/bookkeeping/templates/sending-reports-to-accountants-for-bookkeeping-email-template.md
• content/finance/reference/invoices-receipts-and-statements.md

Verification:

• npm ci
• npm --prefix work-engine test (664 passed)
• npm --prefix work-engine run typecheck
• npm --prefix work-engine run build
• npm --prefix work-engine run test:e2e (305 passed)
• uv run --project lambda-functions --extra search --with pytest python -m pytest tests/docs_app (93 passed, 3 skipped)
• uv run --project lambda-functions --extra search python -m lambda_functions.validate_docs_links --repo-root . --content-root content
• uv run --project lambda-functions --extra search python -m lambda_functions.build_search_index --docs-dir content --output .tmp/dataops-content-search.index (357 documents indexed)
• git diff --check

Notes:

• Preserved the 9 existing tax-report task refs.
• Encoded automatic trigger 0 9 1 * * with triggerLeadDays 0.
• Added runtime bundle links/proof gates for monthly report, accountant upload/share proof, accountant email thread, Finom statement file, Revolut statement file, and tax ZIP file.
• Added waiting/follow-up semantics using existing waitingFor/followUpAt/follow-up-due behavior.
• Removed hardcoded accountant upload destination guidance from touched docs; proof remains runtime state, not Git content.

[alexeygrigorev]

CHANGES REQUESTED

Tester review for issue #37 in /home/alexey/git/dataops/.tmp/worktrees/issue-37.

Required verification commands run:

• git diff --check -> exit 0, no whitespace errors.
• npm --prefix work-engine test -> exit 0, 664 passed, 0 failed.
• npm --prefix work-engine run typecheck -> exit 0.
• npm --prefix work-engine run build -> exit 0.
• uv run --project lambda-functions --extra search --with pytest python -m pytest tests/docs_app -> exit 0, 93 passed, 3 skipped.
• uv run --project lambda-functions --extra search python -m lambda_functions.validate_docs_links --repo-root . --content-root content -> exit 0, docs link validation passed.
• uv run --project lambda-functions --extra search python -m lambda_functions.build_search_index --docs-dir content --output .tmp/dataops-content-search.index -> exit 0, indexed 357 documents.
• npm --prefix work-engine run test:e2e -> exit 1, 303 passed / 2 failed. Failures:
  • e2e/home-dashboard.spec.js:572 Dashboard task rows save external status evidence from the queue timed out on .task-status-checkbox.check() after proof was present.
  • e2e/home-dashboard.spec.js:608 Dashboard task rows save file proof from the queue timed out on .task-status-checkbox.check() after proof was present.
• Focused retry: npm --prefix work-engine run test:e2e -- e2e/home-dashboard.spec.js -g "Dashboard task rows save external status evidence|Dashboard task rows save file proof" --workers=1 -> exit 0, 2 passed.
• Second full retry: npm --prefix work-engine run test:e2e -> exit 1, 304 passed / 1 failed. Failure:
  • e2e/home-dashboard.spec.js:536 Dashboard task rows save comment evidence from the queue timed out on .task-status-checkbox.check() after proof was present.

Failure artifacts inspected:

• work-engine/test-results/home-dashboard-Home-dashbo-860df-tus-evidence-from-the-queue/test-failed-1.png
• work-engine/test-results/home-dashboard-Home-dashbo-4838a-e-file-proof-from-the-queue/test-failed-1.png
• work-engine/test-results/home-dashboard-Home-dashbo-9bdcf-ent-evidence-from-the-queue/test-failed-1.png

The screenshots show the dashboard, not a 404 or app error page, but the required full E2E workflow is not clean. Because the issue explicitly requires focused/full E2E for workflow behavior and the normal full suite failed twice in proof-completion flows, this cannot be TEST PASS.

Per-AC findings:

1. content/tasks/templates/tax-report.md is self-contained and operator-ready: verified. It includes stable frontmatter, workflow definition, phases/stages, recurring schedule, bundle title pattern, done criteria, reminder/risk/waiting semantics, data-safety notes, task execution matrix, sample instantiation, and updated task definitions.
2. work-engine/scripts/seed-templates.ts encodes runtime metadata: verified. Tax Report has triggerSchedule: '0 9 1 * *', triggerLeadDays: 0, default Grace assignee, references/source doc IDs, bundle link definitions, instructions URLs, required links/files, and final stageOnComplete: 'done'.
3. Required proof gates are explicit: verified in metadata/tests for Finom file, Revolut file, tax ZIP file, accountant upload/share link, monthly report link, and accountant email thread. However the full E2E proof-completion command failed in dashboard proof flows, so end-to-end proof completion is not fully clean.
4. Reminder semantics: verified. The docs and metadata describe due/overdue, missing-evidence, waiting/follow-up, waitingFor, followUpAt, and follow-up-due behavior.
5. SOP context mapping: verified. Each tax-report task has an instructions URL and/or instruction doc context; empty instruction links were filled rather than left blank.
6. Finance SOP placeholder sections: verified. Touched SOP/reference/template docs now have concrete validation, troubleshooting, references, and runtime-proof guidance instead of placeholder - sections where needed.
7. Agreement between seed/template docs/content: verified. Task count remains 9, refs and offsets match, required proof and final done transition are aligned across content/tasks/templates/tax-report.md, work-engine/docs/templates.md, seed-templates.ts, and seed.test.ts.
8. Tests added/updated: verified. work-engine/tests/seed.test.ts covers schedule, task refs/offsets, source doc IDs, required bundle links, required files/links, proof requirements, instructions context, due-date instantiation, and done stage. Unit tests pass.
9. No sensitive finance files/secrets/private production links committed: verified from the diff. Added lines contain only process docs, stable references, placeholder ZIP naming, and data-safety guidance; the previous hardcoded accountant upload URL is removed from touched docs. Playwright generated local untracked artifacts (work-engine/e2e/.auth-state.json, work-engine/test-results/) during testing and they must not be committed.
10. Issue labels: verified. Issue labels are docs, process-docs, work-engine, data, P1; needs grooming is absent.

Requested fix:

Make the required full Playwright E2E workflow pass under the normal npm --prefix work-engine run test:e2e command. The failures are timeouts in dashboard task completion after proof evidence is present, affecting comment, external-status, and file-proof variants across two full runs.