portfolio-weekly-brief

portfolio-weekly-brief — reporting skill (Phase 9 Wave 1)

Multi-project LOCAL aggregator. Reads projects/_portfolio/portfolio.config.json v1.1, iterates active_projects[], and for each project emits a 7-day delta (tasks_added, tasks_done, work_events) plus a freshness_flag (fresh | stale) computed from last_sync_at versus slas.weekly_sync_max_days.

This skill follows the convention authority established by skills/planning/master-task-sync/SKILL.md (Phase 8 Wave 2 — pure function transform + READ-ONLY discipline + plugin-agnostik). The discipline (DURUR raises, no silent fallback, schema-first, plugin agnostik, append-only state contract) is reused verbatim. Deviate only with an ADR.

Unlike Phase 8 master_task_sync, this skill never writes to any project's master.xlsx or _state/events.jsonl. Outputs land exclusively under the portfolio workspace (projects/_portfolio/outputs/reports/ + inbox/local/).

Inputs (frontmatter contract)

Name	Type	Default	Notes
portfolio_root	string	—	Optional. Defaults to projects/_portfolio/ under workspace root.
week_end	string	—	Optional ISO date override (YYYY-MM-DD).

workspace_root is resolved via PSEO_WORKSPACE_ROOT env or explicit test override (mirrors workflow_runner / events_writer / W-D1).

Outputs (artifacts produced)

• master.xlsx#none — sentinel acknowledging that the skill READS master.xlsx#master_task from each active project but writes ZERO cells anywhere. The frontmatter outputs[] entry is intentional schema documentation (no openpyxl mutation, no transaction layer call).
• projects/_portfolio/outputs/reports/{week_end}-portfolio-weekly-brief.md — human-readable Markdown brief (multi-project delta table + freshness flag column + totals).
• projects/_portfolio/inbox/local/{week_end}-portfolio-weekly-brief.json — drift-recovery snapshot; full PortfolioBrief envelope including per-project deltas + totals + sla band.

Consumed (READ-ONLY)

#	Source	Discipline
1	portfolio.config.json v1.1	active_projects + cadence + slas
2	per-project master.xlsx#master_task	created_date / done_date in window
3	per-project _state/events.jsonl	event_kind=work, last 7 days
4	per-project last_sync_at (config field)	freshness vs weekly_sync_max_days

Schema authority

schemas/portfolio-config.schema.json v1.1:

• cadence.weekly_brief.day — enum [Monday..Sunday] (drives default week_end).
• cadence.weekly_brief.hour — integer 0-23 (advisory, used by the scheduler — not by this transform).
• slas.weekly_sync_max_days — integer 1-30 (drives the freshness threshold).
• active_projects[].last_sync_at — ISO timestamp expected; null → always stale.
• editorial_overrides.sla_days — per-project SLA override (1-30); takes precedence over slas.weekly_sync_max_days.

The transform raises PortfolioConfigSchemaError (DURUR) if any of these fields drift from the schema. Tests assert the cadence/sla branches against the canonical Draft 7 schema.

Transform contract

scripts/reporting/portfolio_weekly_brief.py (pure function, < 600 lines — transform size gate; ADR-027 sets the < 1500L policy):

• build_portfolio_brief(portfolio_config, workspace_root, now, week_end=None) -> PortfolioBrief — top-level idempotent aggregator.
• aggregate_project(...) -> ProjectDelta — one project's 7-day rollup.
• compute_freshness_flag(last_sync_at, sla_days, now) -> str — isolated freshness logic (test sentinel).
• read_events_in_window(events_path, ...) — fault-tolerant events.jsonl reader.
• read_master_task_delta(workbook_path, window_start, window_end) — openpyxl thin wrapper, read_only=True, INLINE (no shared excel helper imported).
• render_brief_markdown(brief, template_path) — string.Template $var substitution, matches scripts/reporting/render_template.py engine.

Template

templates/reports/portfolio-weekly-brief.template.md — Markdown with YAML frontmatter (week_start, week_end, generated_at, scope, sla_weekly_sync_max_days, projects_count). Body includes:

• $totals_summary — single-line rollup sentence.
• $projects_delta_table — multi-row Markdown table with columns slug | tasks_added | tasks_done | last_sync_at | freshness_flag.
• Totals breakdown table (tasks_added / tasks_done / work_events / fresh / stale projects).

string.Template engine (NOT jinja2) — same as scripts/reporting/render_template.py (Phase 1 mirası). All variables are stringified by build_template_vars() so the template engine never sees a non-string value.

Freshness flag semantics

last_sync_at = None or "":          → "stale"  (never synced)
sla_days < 1 or > 30:               → FreshnessFlagInputError (DURUR)
now - last_sync_at > sla_days:      → "stale"
otherwise:                          → "fresh"

now is passed in (UTC, timezone-aware) so the computation is reproducible across machines + test harnesses. The acceptance gate sentinel: last_sync_at = (now - 8 days), sla = 7 → flag == "stale" is asserted by tests/skills/test_portfolio_weekly_brief.py.

DURUR conditions

Stop and flag the manager — do not patch, do not fall back.

1. PortfolioConfigSchemaError — portfolio.config.json missing cadence or slas, or cadence.weekly_brief.day not in the weekday enum, or slas.weekly_sync_max_days out of [1, 30], or active_projects empty / missing slug.
2. WeekEndParseError — caller-supplied week_end is not a valid ISO date OR the cadence-derived week_end could not be computed.
3. WorkspaceRootUnsetError — PSEO_WORKSPACE_ROOT env var unset AND no explicit workspace_root passed.
4. FreshnessFlagInputError — last_sync_at malformed, OR sla_days out of range, OR now is naive (timezone-unaware).

Idempotency contract

Same portfolio.config.json + same per-project master.xlsx snapshot + same per-project events.jsonl snapshot + same now → byte-identical PortfolioBrief tuple → byte-identical Markdown + JSON output. deltas.sort(key=lambda d: d.slug) enforces deterministic project order; generated_at is microsecond-truncated to second precision.

READ-ONLY discipline

• NO transaction.append / transaction.update calls anywhere.
• NO events_writer.append_* calls anywhere (REVIZE 3 of the Phase 9 brief; Q-RP-01 governance refinement deferred to Phase 14).
• openpyxl.load_workbook(read_only=True, data_only=True) for every master.xlsx open.
• master.xlsx#none outputs[] entry documents the READ-ONLY contract: no logical sheet is touched.

Plugin agnostik

• Project slugs flow in via portfolio.config.json.active_projects[].slug.
• Zero hardcoded slug literals in the transform module (asserted by the worker brief acceptance gate #9 + the skill test suite's base64-obfuscated grep guard).

Audit Event Emit (Q-RP-01 RESOLVED 2026-05-06 Phase B post-closeout)

Schema-first override Section 4c paterni reuse (drift-check Phase 5 doğum belgesi). event_kind=audit row append per rules/events-writer.md Section 4c — event_type field YASAK per Section 6 disambiguation.

import os
import sys
from pathlib import Path

sys.path.insert(0, os.getcwd())

project_slug = os.environ.get("PSEO_PROJECT_ID")
if not project_slug:
    print("PSEO_PROJECT_ID not set — audit event skip")
    sys.exit(0)
report_date = os.environ.get("REPORT_DATE", "2026-05-06")

workspace_root_env = os.environ.get("PSEO_WORKSPACE_ROOT")
workspace_root = (
    Path(workspace_root_env) if workspace_root_env
    else Path.home() / "Documents" / "platinum-seo-workspace"
)

from scripts.state import events_writer
events_writer.append_audit(
    project_id=project_slug,
    audit_action="accessed",
    audit_target=f"reports:portfolio-weekly-brief:{report_date}",
    actor="agent:portfolio-weekly-brief",
    workspace_root=workspace_root,
    notes=f"local_aggregation report-only (portfolio-weekly-brief; date={report_date})",
)

Cross-references

• Schemas: schemas/portfolio-config.schema.json v1.1 (cadence/slas/active_projects branches), schemas/skill-frontmatter.schema.json (this frontmatter validates against it), schemas/events.schema.json (READ-only awareness; event_kind="work" filter).
• Cross-modules (IMPORT-only): scripts/reporting/render_template.py (string.Template engine reuse — actually re-instantiated locally in render_brief_markdown for purity). NO transaction.py, NO events_writer.py, NO workflow_runner.py imports.
• Transform: scripts/reporting/portfolio_weekly_brief.py.
• Template: templates/reports/portfolio-weekly-brief.template.md.
• Tests: tests/skills/test_portfolio_weekly_brief.py (≥6 cases incl. cadence/sla schema validate, freshness sentinel, empty events tolerance, cross-project delta merge, natural_language min length, forbidden tokens guard).
• Pattern reference: skills/planning/master-task-sync/SKILL.md (Phase 8 W-D1 — local aggregation + plugin-agnostik discipline).

Discipline checklist

• TODO/fallback YASAK — every DURUR raises, none silently downgrade.
• Schema-first — frontmatter validates against schemas/skill-frontmatter.schema.json Draft 7; cadence + sla branches validated against portfolio-config.schema.json v1.1.
• Plugin-agnostik — no slug literals; slugs flow from portfolio.config.json.
• ADR-013: Use when / Also use when / Do not use when are STRING content inside description, not separate fields.
• READ-ONLY — zero transaction.* / events_writer.* imports in the transform module.
• Append-only state — events.jsonl is READ-only consumed; this skill does NOT append (REVIZE 3, Q-RP-01 defer Phase 14).
• Idempotency contract — same inputs + same now → byte-stable output (asserted by smoke test).
• Forbidden tokens (4 grep CLEAN): the four Phase 7+ lesson tokens (per-call / per-url credit-cost-per-X fields, the Q-CO-01 metric naming token, hardcoded slugs) are absent; transform contains no leftover task markers in code.
• natural_language phrases ≥ 30 char (min length sentinel asserted by test).
• line count gate < 600 (transform).