specthis 0.0.1__py3-none-any.whl

specthis/__init__.py

@@ -0,0 +1,3 @@
+"""specthis — spec-driven research workflow tooling."""
+
+__version__ = "0.0.1"

specthis/audit.py

@@ -0,0 +1,29 @@
+"""Spec consistency audit (operation 1 from specs/AGENTS.md).
+
+Status: **stub**. The reference implementation is index-based: it
+reads ``specs/_index.json`` and ``specs/_routing.json`` (produced by
+:mod:`specthis.export`) and reports each entry's script existence,
+contract-in-spirit, output schema, export routing, and freshness in a
+single markdown table.
+
+Port plan:
+- ``walk_index(specs_dir) -> list[EntryReport]``
+- ``check_compute_entry(entry, index) -> EntryReport``
+- ``check_report_entry(entry, index, routing) -> EntryReport``
+- ``format_table(reports) -> str``
+
+Until ported, invoke the bundled ``spec-auditor`` subagent in Claude
+Code instead — it implements the same checks by reading the index
+files directly.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def run_audit(specs_dir: Path) -> str:  # pragma: no cover - stub
+    raise NotImplementedError(
+        "specthis.audit is not yet ported. Use the spec-auditor subagent "
+        "(installed by `specthis install`) in the meantime."
+    )

specthis/cache.py

@@ -0,0 +1,26 @@
+"""S3-backed compute cache for spec entries.
+
+Status: **stub**. The reference implementation provides four
+operations keyed by an entry's ``inputs_certified`` hash:
+
+- ``push <entry>``: tar the entry's ``results/<entry>/`` directory and
+  upload to ``s3://<bucket>/cache/<input_sig>/<entry>.tar.gz``.
+- ``fetch <entry>``: download and unpack into ``results/<entry>/``.
+- ``has <entry>``: HEAD-check S3 for the artefact.
+- ``list``: list cached entries with their input signatures.
+
+Requires ``specthis[s3]`` extra (boto3) and AWS credentials available
+in the standard chain (env, profile, instance role).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def push(entry: str, bucket: str, specs_dir: Path) -> None:  # pragma: no cover - stub
+    raise NotImplementedError("specthis.cache is not yet ported.")
+
+
+def fetch(entry: str, bucket: str, specs_dir: Path) -> None:  # pragma: no cover - stub
+    raise NotImplementedError("specthis.cache is not yet ported.")

specthis/cli.py

@@ -0,0 +1,132 @@
+"""specthis command-line entry point."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from . import __version__
+from .install import install_agents, init_specs_dir
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, prog_name="specthis")
+def main() -> None:
+    """Spec-driven research workflow: dashboard, agents, refresh pipeline."""
+
+
+@main.command("install")
+@click.option(
+    "--path",
+    "project_path",
+    type=click.Path(file_okay=False, path_type=Path),
+    default=Path.cwd(),
+    show_default="current directory",
+    help="Project root in which to install .claude/agents/.",
+)
+@click.option(
+    "--force",
+    is_flag=True,
+    help="Overwrite existing agent files.",
+)
+@click.option(
+    "--agent",
+    "selected",
+    multiple=True,
+    type=click.Choice(["spec-auditor", "spec-implementer", "experiment-runner"]),
+    help="Install only the named agent(s). Repeatable. Default: all three.",
+)
+def install_cmd(project_path: Path, force: bool, selected: tuple[str, ...]) -> None:
+    """Copy the specthis subagent templates into <project>/.claude/agents/."""
+    installed, skipped = install_agents(
+        project_path=project_path,
+        force=force,
+        agents=list(selected) if selected else None,
+    )
+    for name in installed:
+        click.echo(f"  installed  {name}")
+    for name, reason in skipped:
+        click.echo(f"  skipped    {name}  ({reason})", err=True)
+    if not installed and skipped:
+        click.echo("\nNothing changed. Re-run with --force to overwrite.", err=True)
+        sys.exit(1)
+
+
+@main.command("init")
+@click.option(
+    "--path",
+    "project_path",
+    type=click.Path(file_okay=False, path_type=Path),
+    default=Path.cwd(),
+    show_default="current directory",
+    help="Project root in which to create specs/.",
+)
+@click.option(
+    "--force",
+    is_flag=True,
+    help="Overwrite existing template files in specs/.",
+)
+def init_cmd(project_path: Path, force: bool) -> None:
+    """Create specs/ with README.md and AGENTS.md spec-format templates."""
+    created, skipped = init_specs_dir(project_path=project_path, force=force)
+    for path in created:
+        click.echo(f"  created    {path}")
+    for path, reason in skipped:
+        click.echo(f"  skipped    {path}  ({reason})", err=True)
+
+
+@main.command("audit")
+@click.option(
+    "--specs",
+    "specs_dir",
+    type=click.Path(file_okay=False, exists=True, path_type=Path),
+    default=Path("specs"),
+    show_default=True,
+    help="specs/ directory to audit.",
+)
+def audit_cmd(specs_dir: Path) -> None:
+    """Run the consistency audit over specs/. (stub — port pending)"""
+    click.echo(
+        f"specthis audit: not yet implemented. Would audit {specs_dir}.\n"
+        "Until then, invoke the spec-auditor subagent in Claude Code.",
+        err=True,
+    )
+    sys.exit(2)
+
+
+@main.command("refresh")
+@click.option(
+    "--specs",
+    "specs_dir",
+    type=click.Path(file_okay=False, exists=True, path_type=Path),
+    default=Path("specs"),
+    show_default=True,
+)
+def refresh_cmd(specs_dir: Path) -> None:
+    """Re-run stale entries respecting the lock file. (stub — port pending)"""
+    click.echo("specthis refresh: not yet implemented.", err=True)
+    sys.exit(2)
+
+
+@main.command("serve")
+@click.option("--host", default="127.0.0.1", show_default=True)
+@click.option("--port", type=int, default=8765, show_default=True)
+def serve_cmd(host: str, port: int) -> None:
+    """Serve the specs.html dashboard with live reload. (stub — port pending)"""
+    click.echo("specthis serve: not yet implemented.", err=True)
+    sys.exit(2)
+
+
+@main.command("lock")
+@click.argument("subcommand", type=click.Choice(["status", "record", "clear"]))
+@click.argument("entry", required=False)
+def lock_cmd(subcommand: str, entry: str | None) -> None:
+    """Manage the spec inputs_certified content-hash lock. (stub — port pending)"""
+    click.echo(f"specthis lock {subcommand}: not yet implemented.", err=True)
+    sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()

specthis/export.py

@@ -0,0 +1,30 @@
+"""Dashboard renderer: builds specs/specs.html + _index.json + _routing.json.
+
+Status: **stub**. The reference implementation walks ``specs/*.md``,
+parses each frontmatter + entry block, joins against the working tree
+(script existence, output existence + top-level keys, export
+artefacts, host-doc routing), and emits three artefacts:
+
+- ``specs/specs.html`` — a single-file browsable dashboard of every
+  spec, entry, and pairing.
+- ``specs/_index.json`` — per-spec frontmatter + per-entry facts,
+  consumed by :mod:`specthis.audit` and the auditor subagent.
+- ``specs/_routing.json`` — per host-doc, per label section, the
+  ``\\input{}`` / ``\\includegraphics{}`` lines found inside, plus
+  ``\\sectionversion`` proximity flags.
+
+Port plan:
+- ``parse_spec(path) -> SpecFile``
+- ``join_against_worktree(specs, project_root) -> IndexData``
+- ``walk_host_docs(reports_dir) -> RoutingData``
+- ``render_html(index, routing) -> str``
+- ``write_artefacts(specs_dir, index, routing, html) -> None``
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def render(specs_dir: Path, project_root: Path) -> None:  # pragma: no cover - stub
+    raise NotImplementedError("specthis.export is not yet ported.")

specthis/install.py

@@ -0,0 +1,69 @@
+"""Scaffolder: copy bundled templates into a project directory."""
+
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+AGENT_NAMES = ("spec-auditor", "spec-implementer", "experiment-runner")
+SPEC_TEMPLATE_NAMES = ("README.md", "AGENTS.md")
+
+
+def _read_template(subdir: str, filename: str) -> str:
+    """Read a bundled template file from the installed package."""
+    package = f"specthis.templates.{subdir}"
+    return resources.files(package).joinpath(filename).read_text(encoding="utf-8")
+
+
+def install_agents(
+    project_path: Path,
+    force: bool = False,
+    agents: list[str] | None = None,
+) -> tuple[list[str], list[tuple[str, str]]]:
+    """Copy agent templates into ``<project_path>/.claude/agents/``.
+
+    Returns ``(installed, skipped)`` where ``installed`` is a list of agent
+    names written and ``skipped`` is a list of ``(name, reason)``.
+    """
+    selected = agents or list(AGENT_NAMES)
+    target_dir = project_path / ".claude" / "agents"
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    installed: list[str] = []
+    skipped: list[tuple[str, str]] = []
+    for name in selected:
+        if name not in AGENT_NAMES:
+            skipped.append((name, "unknown agent"))
+            continue
+        target = target_dir / f"{name}.md"
+        if target.exists() and not force:
+            skipped.append((name, "already exists; use --force"))
+            continue
+        body = _read_template("agents", f"{name}.md")
+        target.write_text(body, encoding="utf-8")
+        installed.append(name)
+    return installed, skipped
+
+
+def init_specs_dir(
+    project_path: Path,
+    force: bool = False,
+) -> tuple[list[Path], list[tuple[Path, str]]]:
+    """Create ``<project_path>/specs/`` with the README and AGENTS templates.
+
+    Returns ``(created, skipped)``.
+    """
+    target_dir = project_path / "specs"
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    created: list[Path] = []
+    skipped: list[tuple[Path, str]] = []
+    for filename in SPEC_TEMPLATE_NAMES:
+        target = target_dir / filename
+        if target.exists() and not force:
+            skipped.append((target, "already exists; use --force"))
+            continue
+        body = _read_template("specs", filename)
+        target.write_text(body, encoding="utf-8")
+        created.append(target)
+    return created, skipped

specthis/lock.py

@@ -0,0 +1,29 @@
+"""Content-hash lock for spec entries.
+
+Status: **stub**. The reference implementation maintains
+``specs/_lock.json`` keyed by entry name, recording:
+
+- ``inputs_certified``: SHA-256 of (spec body + script body + workflow
+  files) at the moment the entry was certified ``script ready``.
+- ``depends_on``: the entry's resolved dependency list at certification
+  time.
+- ``author``, ``ts``: who certified, when.
+
+The refresh orchestrator (:mod:`specthis.refresh`) compares the live
+hash against ``inputs_certified`` before re-running an entry; a
+mismatch surfaces as ``spec audit needed`` and blocks the rerun.
+
+Port plan:
+- ``compute_inputs_hash(entry) -> str``
+- ``record_inputs(entry, author) -> None``
+- ``status(entry) -> Literal["certified", "drifted", "uncertified"]``
+- ``clear(entry) -> None``
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def record_inputs(entry: str, author: str, specs_dir: Path) -> None:  # pragma: no cover - stub
+    raise NotImplementedError("specthis.lock is not yet ported.")

specthis/refresh.py

@@ -0,0 +1,28 @@
+"""Refresh orchestrator: re-runs stale entries respecting the lock.
+
+Status: **stub**. The reference implementation:
+
+1. Reads ``specs/_index.json`` (built by :mod:`specthis.export`) and
+   ``specs/_lock.json`` (managed by :mod:`specthis.lock`).
+2. For each entry, classifies state as one of: ``fresh``, ``stale``,
+   ``unbound`` (uncertified), or ``spec audit needed`` (live inputs
+   hash diverged from ``inputs_certified``).
+3. For ``stale`` entries, optionally fetches from S3 cache
+   (:mod:`specthis.cache`) before falling back to a local rerun via
+   the project's Makefile or a per-entry ``run:`` command.
+4. After a successful rerun, optionally pushes the new artefacts to
+   the S3 cache.
+
+Port plan:
+- ``classify(entry, index, lock) -> EntryState``
+- ``plan(entries) -> RefreshPlan``
+- ``execute(plan, dry_run) -> RefreshReport``
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def run(specs_dir: Path, dry_run: bool = False) -> None:  # pragma: no cover - stub
+    raise NotImplementedError("specthis.refresh is not yet ported.")

specthis/serve.py

@@ -0,0 +1,22 @@
+"""Local dev server for specs.html with file-watch reload.
+
+Status: **stub**. The reference implementation serves
+``specs/specs.html`` over HTTP, watches ``specs/*.md`` for changes,
+and reruns the export pipeline (:func:`specthis.export.render`) on
+each change before triggering a browser reload via SSE.
+
+Port plan:
+- ``serve(host, port, specs_dir, project_root) -> None``
+- ``_watch(paths) -> Iterator[Event]``
+- ``_sse_handler(...) -> AsgiApp``
+
+Requires ``specthis[serve]`` extra (uvicorn + starlette).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def serve(host: str, port: int, specs_dir: Path, project_root: Path) -> None:  # pragma: no cover - stub
+    raise NotImplementedError("specthis.serve is not yet ported.")

specthis/templates/agents/experiment-runner.md

@@ -0,0 +1,87 @@
+---
+name: experiment-runner
+description: Kicks off a long-running experiment (a `make <target>` or a script under experiments/) in the background and monitors its log for milestones, NaN/error lines, and completion. Use whenever the user says "run experiment X", "kick off the fit", "rerun <target>", or "monitor the running job". Frees the main thread from training-step log noise — reports only milestone/completion/error lines. Does NOT edit code, does NOT touch specs, does NOT analyse the result JSON beyond confirming it landed.
+tools: Read, Glob, Grep, Bash, ToolSearch
+color: orange
+---
+
+You are the experiment-runner. You launch one experiment (a Makefile
+target or a direct script invocation), monitor its log without
+flooding the parent's context, and report milestones / errors /
+completion.
+
+## Inputs you need
+
+- The experiment to run, given as either a `make <target>` name OR a
+  script path with any args.
+- A log path the parent wants you to use (default:
+  `/tmp/<experiment-name>.log`).
+
+## Procedure
+
+1. **Inspect first**: Read the Makefile target (or the script) to
+   confirm the expected output path and any milestone-log markers
+   (search for `print(`, `logger.info`, `tqdm`). If output already
+   exists and is newer than the script, ask the parent whether to skip
+   or force-rerun before launching anything.
+2. **Launch in the background.** The project's `CLAUDE.md` or
+   `README.md` should document any required env vars (e.g.
+   `LD_LIBRARY_PATH`, `PYTHONUNBUFFERED`). Wrap the launch with
+   `> /tmp/<name>.log 2>&1 &` and pass `run_in_background: true` on
+   the Bash call so you get the PID back and the call returns
+   immediately. NEVER tail in the foreground.
+3. **Monitor for milestones, not raw training steps.** Load the
+   `Monitor` tool via `ToolSearch` (it is a deferred tool) and use it
+   with a regex that catches:
+   - error / traceback lines
+     (`Error|Traceback|RuntimeError|AssertionError|OOM|CUDA out of memory`)
+   - NaN / Inf indicators (`nan|inf|NaN|Inf`)
+   - milestone markers (`epoch \d|iter \d+|step \d+|cell \d+|saved`)
+   - completion markers (the script's final-line pattern, e.g. `done`,
+     `Wrote `, `Saved JSON to `)
+
+   If `Monitor` cannot be loaded, fall back to periodic
+   `grep -E "<regex>" /tmp/<name>.log | tail -n 5` polls with the
+   `Bash` tool — but spaced out (≥ 270s between polls so the prompt
+   cache stays warm; see harness guidance).
+4. **Report only the interesting lines** back to the parent. Do not
+   paste large slabs of training output. A heartbeat every ~10 minutes
+   ("still running, last milestone: epoch 42, loss=...") is enough.
+5. **On NaN or error**: report immediately, including the last ~20
+   lines of context. Do NOT auto-kill the job unless the parent told
+   you to.
+6. **On completion**: confirm the expected output JSON exists at the
+   path the spec / Makefile declared. Report the path, the file's
+   mtime, and the file size. Do NOT open the JSON to inspect numbers
+   — that is the parent's job.
+
+## Hard rules
+
+- Do NOT edit any source file. You have no Edit/Write tools.
+- Do NOT touch specs or `reports/`.
+- Do NOT analyse the result JSON's contents — just confirm it landed.
+- Do NOT poll faster than ~270 s between log checks. Faster polling
+  wastes the parent's prompt cache without making the experiment
+  finish sooner.
+- Do NOT kill the job without being asked.
+- Respect any hardware limits documented in the project's `CLAUDE.md`
+  / `README.md`. If you hit one (e.g. `CUDA out of memory`), report it
+  and let the parent decide.
+
+## Report-back shape
+
+While running:
+```
+[experiment-runner] <name>  PID=<pid>  last milestone: <line>  elapsed: <hh:mm:ss>
+```
+
+On completion:
+```
+[experiment-runner] <name>  DONE  output: <path>  size: <bytes>  elapsed: <hh:mm:ss>
+```
+
+On failure:
+```
+[experiment-runner] <name>  FAILED  reason: <one line>  log tail:
+<last ~20 lines>
+```

specthis/templates/agents/spec-auditor.md

@@ -0,0 +1,126 @@
+---
+name: spec-auditor
+description: Read-only consistency audit of specs/ against the working tree. Use whenever the user says "audit the specs", "check the specs", "are the specs in sync", or after editing a spec file to verify scripts/outputs/exports/routing still line up. Returns a single markdown table per specs/AGENTS.md operation 1. Never runs scripts, never edits anything.
+tools: Read, Glob, Grep
+color: blue
+---
+
+You are the spec-auditor. Your one job is operation 1 ("Audit") from
+`specs/AGENTS.md`. You are strictly read-only.
+
+## Index-first workflow
+
+**Always start by reading `specs/_index.json` and `specs/_routing.json`**
+— these are precomputed by the specthis dashboard renderer and contain,
+in queryable form, everything the audit needs from the spec files
+themselves:
+
+- `_index.json`: per spec file, frontmatter (`kind`, `depends_on`,
+  `host_doc`, `section_label`, `mtime`) and per entry: `name`, `kind`,
+  `status`, `export_status`, `script` + `script_exists`, `output` +
+  `output_exists`, `export_outputs` + `export_outputs_exist`,
+  `output_top_level_keys`, `workflows`.
+- `_routing.json`: per host doc, per `\label{...}` found in that doc:
+  `label_line`, `section_line`, `inputs` (all `\input{}` files in that
+  section), `includegraphics`, `sectionversion_present_within_10_lines`.
+
+Treat the index as authoritative for the cheap mechanical checks
+(script existence, output existence, status, depends_on listing,
+routing presence, sectionversion proximity, top-level JSON keys). Only
+fall back to `Read` on the underlying spec/script/host-doc files when:
+
+1. The contract docs themselves (`specs/README.md`,
+   `specs/AGENTS.md`) — read once per session to know what to check.
+2. A flagged inconsistency where the index says something is wrong and
+   you need the spec/script body to characterise the failure (e.g. "the
+   JSON exists but a required key is missing" — go open the JSON to see
+   what's actually there).
+3. The spec body needs to confirm an unindexed claim — e.g. verifying
+   `depends_on` targets actually appear in the prose, or the script
+   body matches the spec's "contract in spirit" (only for entries the
+   index flagged as suspicious).
+4. The index is missing or out of date (`mtime` of `_index.json` older
+   than the youngest `specs/*.md`) — in that case, fall back to
+   globbing `specs/*.md` and reading each one. Note this in your output
+   as a "stale index" warning so the user can rerun
+   `specthis serve --index-only` (or the project's equivalent
+   index-export command).
+
+The whole point of the index is to replace ~80% of the per-audit Reads
+with two cheap JSON lookups. A well-run audit should average ≤10 Read
+calls, not 60+.
+
+## Procedure
+
+Follow `specs/AGENTS.md` §1 verbatim. The condensed checklist (each
+step now leans on the index — only Read when noted):
+
+1. Read `specs/README.md` and `specs/AGENTS.md` first (the audit
+   contract).
+2. Read `specs/_index.json` and `specs/_routing.json`. (If either is
+   missing or older than the youngest `specs/*.md`, flag stale-index
+   and fall back to spec walking.)
+3. For each entry in `_index.json[spec][entries]` that declares
+   `Script:` / `Output:`:
+   - `script_exists` → ✓/✗ directly from the index.
+   - Contract-in-spirit: only Read the script body when the index
+     flags something off (e.g. `script ready` but
+     `script_exists=false`, or output exists but schema keys look
+     wrong).
+   - `output_exists` and `output_top_level_keys` from the index → check
+     against the schema declared in the entry contract without opening
+     the JSON.
+   - If the entry has `export_outputs`, `export_outputs_exist` is a
+     parallel list — ✓/✗ per artefact directly from the index.
+4. For each entry that declares `host_doc` + `section_label`, look up
+   `_routing.json[host_doc][sections][section_label]`:
+   - Label presence: section is present iff the label key exists.
+   - For each artefact in the entry's `export_outputs`, check if it
+     appears in the section's `inputs` or `includegraphics` (basename
+     match acceptable for `inputs`, full-path or basename for
+     `includegraphics`). Mismatch on either side → **orphaned export**
+     (entry exports it but no `\input`) or **stale routing** (host doc
+     inputs something the entry doesn't export).
+   - `sectionversion_present_within_10_lines` from the index gives the
+     `\sectionversion` proximity check directly.
+5. Frontmatter check: every spec in `_index.json` has `kind` ∈
+   {meta, definitions, templates, compute, report, figure}, and every
+   `depends_on` entry is a known spec filename (lookup against
+   `_index.json` keys). Verifying that `depends_on` entries appear in
+   the body is a Read only if an entry looks suspicious.
+6. Document conventions: the project's report convention (declared in
+   `specs/README.md` / `specs/AGENTS.md`) — version file presence,
+   per-section `\sectionversion` proximity (already in the routing
+   index), and any other top-level `.tex` requirements. Use Grep, not
+   full Reads.
+
+## Output format
+
+Return exactly one markdown table, one row per entry:
+
+```
+| entry | spec status | script ✓ | contract ✓ | output ✓ | output schema ✓ | export status | export script ✓ | export output ✓ | report routing ✓ | notes |
+```
+
+Use `✓`, `✗`, or `n/a`. Keep notes short ("required key missing",
+"schema mismatch on `<key>`", "spec lies: status says `script ready`
+but script does not exist", "export script writes outside `reports/`").
+
+After the table, append at most a 5-line **summary** section listing:
+- count of entries with `script TBD`
+- count of contract mismatches
+- count of orphaned exports / stale routings
+- any frontmatter or document-convention violations
+
+Do not propose actions in the audit output unless the user explicitly
+asked for "audit + next steps" — in that case append a short
+**proposed next steps** block (operation 2 from AGENTS.md). Default is
+audit-only.
+
+## Hard rules
+
+- Do NOT run scripts (no project run commands, no `make`, no Python).
+- Do NOT edit any file. You have no Edit/Write tools.
+- Do NOT open large result JSONs in full — key existence is enough.
+- Do NOT compile any document under `reports/`.
+- Do NOT transcribe result numbers into the report.