sddflow 2.7.60__tar.gz → 2.7.77__tar.gz

{sddflow-2.7.60 → sddflow-2.7.77}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sddflow
-Version: 2.7.60
+Version: 2.7.77
 Summary: SDD Framework CLI — initialize and upgrade Spec-Driven Development packs
 Project-URL: Homepage, https://github.com/sunil1983us/universalguide
 Project-URL: Repository, https://github.com/sunil1983us/universalguide
@@ -647,6 +647,49 @@ your own `~/.sdd/config.yml`.
 
 ---
 
+### `sdd token-log`
+
+Logs **real** token usage for one command — reads Claude Code's own local
+session transcript (`~/.claude/projects/{project}/{session-id}.jsonl`,
+including any subagent transcripts spawned during the command) for actual
+measured `input_tokens`/`output_tokens`/cache-token counts the Anthropic
+API reported, not an estimate.
+
+```bash
+sdd token-log --command specify-brd              # log real usage for this command
+sdd token-log --command specify-brd --feature auth
+sdd token-log --command specify-brd --dry-run     # print without writing
+```
+
+Requires `.specify/memory/token-pricing.yml` to exist (same opt-in gate as
+the estimate — see "Token Usage Logging" in `HOW-TO-USE.md`). Writes/creates
+`.specify/features/{feature}/token-usage.md`, appending a row per model used
+and updating its Running Totals table.
+
+**This is Claude Code-only.** No other AI tool this framework supports
+(GitHub Copilot, Cursor, Windsurf, copy-paste "any AI") has a local,
+readable equivalent — the transcript path/format is undocumented,
+reverse-engineered from observed file layout, not a published API, and
+could change in a future Claude Code release. Exit codes tell a calling
+prompt exactly what happened, so it can fall back to the character-count
+estimate cleanly instead of surfacing a raw error:
+
+| Exit code | Meaning |
+|---|---|
+| `0` | Logged successfully — or nothing new since the last logged row (also `0`, no row added) |
+| `1` | Unexpected error (e.g. no feature name resolvable, or an existing `token-usage.md` doesn't match the expected table shape) |
+| `2` | `token-pricing.yml` doesn't exist — logging is off entirely |
+| `3` | No Claude Code session transcript found for this project — not running under Claude Code, or no session has touched it yet |
+
+Each command's usage window is bounded by the previous logged row's
+timestamp (or the whole current session, for the very first command
+logged for a feature) — never re-sums usage already logged. A
+pre-existing `token-usage.md` from before this column existed (7-column
+rows, no `Source` column) is left untouched; new rows are only ever
+appended, never used to rewrite old ones.
+
+---
+
 ### `sdd pr create`
 
 Create a git branch and a PR for a task, linked back to its Jira issue — on

{sddflow-2.7.60 → sddflow-2.7.77}/README.md

@@ -612,6 +612,49 @@ your own `~/.sdd/config.yml`.
 
 ---
 
+### `sdd token-log`
+
+Logs **real** token usage for one command — reads Claude Code's own local
+session transcript (`~/.claude/projects/{project}/{session-id}.jsonl`,
+including any subagent transcripts spawned during the command) for actual
+measured `input_tokens`/`output_tokens`/cache-token counts the Anthropic
+API reported, not an estimate.
+
+```bash
+sdd token-log --command specify-brd              # log real usage for this command
+sdd token-log --command specify-brd --feature auth
+sdd token-log --command specify-brd --dry-run     # print without writing
+```
+
+Requires `.specify/memory/token-pricing.yml` to exist (same opt-in gate as
+the estimate — see "Token Usage Logging" in `HOW-TO-USE.md`). Writes/creates
+`.specify/features/{feature}/token-usage.md`, appending a row per model used
+and updating its Running Totals table.
+
+**This is Claude Code-only.** No other AI tool this framework supports
+(GitHub Copilot, Cursor, Windsurf, copy-paste "any AI") has a local,
+readable equivalent — the transcript path/format is undocumented,
+reverse-engineered from observed file layout, not a published API, and
+could change in a future Claude Code release. Exit codes tell a calling
+prompt exactly what happened, so it can fall back to the character-count
+estimate cleanly instead of surfacing a raw error:
+
+| Exit code | Meaning |
+|---|---|
+| `0` | Logged successfully — or nothing new since the last logged row (also `0`, no row added) |
+| `1` | Unexpected error (e.g. no feature name resolvable, or an existing `token-usage.md` doesn't match the expected table shape) |
+| `2` | `token-pricing.yml` doesn't exist — logging is off entirely |
+| `3` | No Claude Code session transcript found for this project — not running under Claude Code, or no session has touched it yet |
+
+Each command's usage window is bounded by the previous logged row's
+timestamp (or the whole current session, for the very first command
+logged for a feature) — never re-sums usage already logged. A
+pre-existing `token-usage.md` from before this column existed (7-column
+rows, no `Source` column) is left untouched; new rows are only ever
+appended, never used to rewrite old ones.
+
+---
+
 ### `sdd pr create`
 
 Create a git branch and a PR for a task, linked back to its Jira issue — on

{sddflow-2.7.60 → sddflow-2.7.77}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sddflow"
-version = "2.7.60"
+version = "2.7.77"
 description = "SDD Framework CLI — initialize and upgrade Spec-Driven Development packs"
 readme = "README.md"
 requires-python = ">=3.9"

sddflow-2.7.77/sdd/__init__.py

@@ -0,0 +1 @@
+__version__ = "2.7.77"

{sddflow-2.7.60 → sddflow-2.7.77}/sdd/__main__.py

@@ -9,6 +9,7 @@ from sdd.commands.review import review_command
 from sdd.commands.cr import cr_command
 from sdd.commands.pr import pr_command
 from sdd.commands.dashboard import dashboard_command
+from sdd.commands.token_log import token_log_command
 
 
 @click.group()
@@ -26,6 +27,7 @@ cli.add_command(review_command,      name="review")
 cli.add_command(cr_command,          name="cr")
 cli.add_command(pr_command,          name="pr")
 cli.add_command(dashboard_command,   name="dashboard")
+cli.add_command(token_log_command,   name="token-log")
 
 
 if __name__ == "__main__":

{sddflow-2.7.60 → sddflow-2.7.77}/sdd/commands/confluence.py

@@ -10,13 +10,14 @@ from sdd.utils.confluence_client import ConfluenceClient
 from sdd.utils.md_to_cf import md_to_storage
 from sdd.utils.cf_to_md import cf_to_md
 from sdd.utils.manifest import read_manifest
-from sdd.utils.validate import resolve_doc_path, LIVING_SERVICE_DOCS
+from sdd.utils.validate import resolve_doc_path, LIVING_SERVICE_DOCS, PROJECT_SCOPED_DOCS
 
 console = Console()
 
 _DRAFTS_FILE = Path(".specify") / ".confluence-drafts.json"
 
 _CONTEXT_PAGE_TITLE = "{feature} — Context"
+_CONSTITUTION_PAGE_TITLE = "{project} — Constitution"
 
 
 def _load_drafts() -> dict:
@@ -62,11 +63,11 @@ def resolve_feature_parent_id(client: ConfluenceClient, cf_cfg, project_name: st
 
 def resolve_doc_parent_id(client: ConfluenceClient, cf_cfg, project_name: str,
                            feature_name: str, doc: str) -> str:
-    """Like resolve_feature_parent_id(), except living/service-level docs
-    (LIVING_SERVICE_DOCS) nest directly under the Project page instead of
-    a Feature page, since they're shared across every feature, not
-    per-feature."""
-    if doc in LIVING_SERVICE_DOCS:
+    """Like resolve_feature_parent_id(), except living/service-level docs,
+    "constitution", and "runbook" (PROJECT_SCOPED_DOCS) nest directly
+    under the Project page instead of a Feature page, since they're
+    shared across every feature, not per-feature."""
+    if doc in PROJECT_SCOPED_DOCS:
         return _ensure_container_page(client, cf_cfg.space_key, project_name, cf_cfg.parent_page_id)
     return resolve_feature_parent_id(client, cf_cfg, project_name, feature_name)
 
@@ -84,17 +85,48 @@ def upload_diagram_attachments(client: ConfluenceClient, page_id: str,
         try:
             client.upload_attachment(page_id, filename, content, media_type)
         except Exception as e:
-            console.print(f"  [yellow]!  {filename} — diagram attachment upload failed: {e}[/yellow]")
+            console.print(
+                f"  [yellow]!  {filename} — diagram attachment upload failed: "
+                f"{e}{_response_detail(e)}[/yellow]"
+            )
+
+
+def _response_detail(e: Exception) -> str:
+    """Confluence's own error message (the actual reason for a 4xx) lives
+    in the HTTP response body -- requests.HTTPError's default str() only
+    includes the status code and URL, which is why a bare '400 Client
+    Error: Bad Request for url: ...' told the user nothing about WHY.
+    Pulls the real reason out of the JSON error body (Confluence returns
+    {"message": "..."} or {"data": {"errors": [...]}} depending on
+    version) so a failure is actually diagnosable, not just visible."""
+    response = getattr(e, "response", None)
+    if response is None:
+        return ""
+    try:
+        body = response.json()
+    except ValueError:
+        text = (response.text or "").strip()
+        return f" -- {text[:300]}" if text else ""
+    message = body.get("message")
+    if not message:
+        errors = body.get("data", {}).get("errors") if isinstance(body.get("data"), dict) else None
+        if errors:
+            message = "; ".join(
+                err.get("message", str(err)) if isinstance(err, dict) else str(err)
+                for err in errors
+            )
+    return f" -- {message}" if message else ""
 
 
 def _resolve_page_title(doc: str, project_name: str, feature: str,
                          page_map: dict) -> str:
     """Build the Confluence page title for a doc key.
 
-    Living/service-level docs (LIVING_SERVICE_DOCS) always resolve to ONE
-    page for the whole project — {feature} is stripped even if present in
-    the template, since these documents are shared across every feature,
-    never per-feature.
+    Living/service-level docs and "runbook" (PROJECT_SCOPED_DOCS, minus
+    "constitution" which is handled separately above) always resolve to
+    ONE page for the whole project — {feature} is stripped even if
+    present in the template, since these documents are shared across
+    every feature, never per-feature.
 
     Per-feature docs substitute {feature} into the title ONLY if the
     user's own page_map template contains that placeholder. This is
@@ -108,9 +140,11 @@ def _resolve_page_title(doc: str, project_name: str, feature: str,
     """
     if doc == "context":
         return _CONTEXT_PAGE_TITLE.replace("{project}", project_name).replace("{feature}", feature)
+    if doc == "constitution":
+        return _CONSTITUTION_PAGE_TITLE.replace("{project}", project_name)
     template = page_map.get(doc, f"{{project}} — {doc.upper()}")
     title = template.replace("{project}", project_name)
-    if doc in LIVING_SERVICE_DOCS:
+    if doc in LIVING_SERVICE_DOCS or doc == "runbook":
         title = title.replace(" — {feature}", "").replace("{feature}", "")
         return title.strip().rstrip("—").strip()
     return title.replace("{feature}", feature)
@@ -126,8 +160,11 @@ def confluence_command():
 @click.option("--feature", default=None, help="Feature name (default: from manifest.yml)")
 @click.option("--doc",     default=None,
               help="Push a single doc only (e.g. hld, brd, arch, runbook)")
+@click.option("--summary", is_flag=True, default=False,
+              help="Push each doc's .summary.md to its own page (title suffixed "
+                   "' — Summary') instead of the full .md")
 @click.option("--dry-run", is_flag=True, help="Print page titles without calling the API")
-def confluence_push(profile, feature, doc, dry_run):
+def confluence_push(profile, feature, doc, summary, dry_run):
     """Publish SDD documents to Confluence pages (create or update)."""
     console.print()
     console.print("[bold]━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━[/bold]")
@@ -167,10 +204,14 @@ def confluence_push(profile, feature, doc, dry_run):
         except ValueError as e:
             console.print(f"  [red]✗  {e}[/red]")
             raise SystemExit(1)
+        if summary:
+            md_path = md_path.parent / f"{md_path.stem}.summary.md"
         if not md_path.exists():
-            console.print(f"  [dim]·[/dim]  {key}.md not found — skipped")
+            console.print(f"  [dim]·[/dim]  {md_path.name} not found — skipped")
             continue
         title = _resolve_page_title(key, project_name, feature_name, page_map)
+        if summary:
+            title = f"{title} — Summary"
         available.append((key, md_path, title))
 
     if not available: