perhapsspy/project-legibility / plugins/project-legibility/skills/project-context
project-context
UnverifiedResume, handoff, and long-running repo work by keeping durable context across threads or agents: task briefs, logs, and reusable reference notes.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.9 KB |
| agents/openai.yaml | config | 228 B |
| scripts/check_runtime_shape.py | script | 13.8 KB |
| scripts/task_logs.py | script | 14.2 KB |
scripts/check_runtime_shape.py
View on GitHub#!/usr/bin/env python3
"""Thin checks for current runtime shape and latest log blocks."""
from __future__ import annotations
import argparse
from collections.abc import Iterator
from dataclasses import dataclass
from datetime import datetime
from pathlib import Path
import re
import sys
SKILL_ROOT = Path(__file__).resolve().parents[1]
REPO_ROOT = SKILL_ROOT.parents[1]
DEFAULT_CWD = Path.cwd().resolve()
DISPLAY_ROOT = DEFAULT_CWD
SCRIPT_ROOT = Path(__file__).resolve().parent
if str(SCRIPT_ROOT) not in sys.path:
sys.path.insert(0, str(SCRIPT_ROOT))
from task_logs import LogToolError, read_latest_block, read_latest_block_for_log
CORE_TASK_FILES = (
"BRIEF.md",
"logs/DECISIONS.md",
"logs/WORKLOG.md",
)
KEBAB_NAME_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
TASK_YEAR_RE = re.compile(r"^[0-9]{4}$")
TASK_DATE_RE = re.compile(r"^(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$")
SECRET_LIKE_MARKERS = (
re.compile(r"BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY"),
re.compile(r"(?i)(api[_-]?key|access[_-]?token|secret)\s*[:=]\s*[A-Za-z0-9_\-]{16,}"),
)
ENVIRONMENT_PATH_MARKERS = (
re.compile(r"(?<![A-Za-z0-9])~/"),
re.compile(r"\$HOME(?:/|\\)"),
re.compile(r"\$\{HOME\}(?:/|\\)"),
re.compile(r"%USERPROFILE%(?:\\|/)"),
re.compile(r"file:///[^\s)]+"),
re.compile(r"/Users/[^/\s`]+(?:/[^\s`)]+)+"),
re.compile(r"/home/[^/\s`]+(?:/[^\s`)]+)+"),
re.compile(r"[A-Za-z]:\\Users\\[^\\\s`]+(?:\\[^\s`)]+)+"),
)
@dataclass(frozen=True)
class RuntimePaths:
repo_root: Path
docs_root: Path
reference_root: Path
task_root: Path
def detect_repo_root(start: Path | None = None) -> Path:
current = (start or Path.cwd()).resolve()
git_root: Path | None = None
for candidate in (current, *current.parents):
docs_root = candidate / "docs"
if (docs_root / "reference").exists() or (docs_root / "tasks").exists():
return candidate
if git_root is None and (candidate / ".git").exists():
git_root = candidate
return git_root or current
def runtime_paths(repo_root: Path) -> RuntimePaths:
repo_root = repo_root.resolve()
docs_root = repo_root / "docs"
return RuntimePaths(
repo_root=repo_root,
docs_root=docs_root,
reference_root=docs_root / "reference",
task_root=docs_root / "tasks",
)
def main(
argv: list[str] | None = None,
runtime: RuntimePaths | None = None,
) -> int:
args = parse_args(argv)
if runtime is None:
repo_root = (
Path(args.repo_root).resolve()
if args.repo_root is not None
else detect_repo_root(Path.cwd())
)
runtime = runtime_paths(repo_root)
set_display_root(runtime.repo_root)
failures = run_runtime_shape_checks(runtime, args.task_root)
return report_failures(failures, runtime.repo_root)
def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
parser = argparse.ArgumentParser(
description=(
"Thin checks for current runtime shape and latest log blocks only. "
"Does not validate semantic quality, full historical consistency, "
"completeness, or migration correctness. "
"Infers the target repo from the current working directory."
)
)
parser.add_argument(
"--repo-root",
help=(
"explicit repo root to validate when current-working-directory "
"detection would be ambiguous"
),
)
parser.add_argument(
"--task-root",
type=Path,
help="check only this task; relative paths are resolved from the repo root",
)
return parser.parse_args(argv)
def run_runtime_shape_checks(
runtime: RuntimePaths | None = None,
task_root: Path | None = None,
) -> list[str]:
runtime = runtime or runtime_paths(detect_repo_root(Path.cwd()))
set_display_root(runtime.repo_root)
if task_root is not None:
selected = (runtime.repo_root / task_root).resolve()
try:
parts = selected.relative_to(runtime.task_root.resolve()).parts
except ValueError:
parts = ()
if (
len(parts) != 3
or not TASK_YEAR_RE.fullmatch(parts[0])
or not TASK_DATE_RE.fullmatch(parts[1])
or not is_valid_task_date(parts[0], parts[1])
or not KEBAB_NAME_RE.fullmatch(parts[2])
):
return [f"Expected task under docs/tasks/yyyy/mm-dd/<task-slug>: {rel(selected)}"]
if not selected.is_dir():
return [f"Missing task directory: {rel(selected)}"]
return [
*task_failures(selected),
*check_portable_path_scan(runtime, selected),
*check_secret_marker_scan(selected),
]
return [
*check_reference_contract(runtime.reference_root),
*check_task_contract(runtime.task_root),
*check_portable_path_scan(runtime),
*check_secret_marker_scan(runtime.docs_root),
]
def report_failures(failures: list[str], repo_root: Path | None = None) -> int:
repo_label = f"repo root: {(repo_root or detect_repo_root(Path.cwd())).resolve()}"
if failures:
print("[FAIL] project-context current runtime shape checks")
print(repo_label)
for item in failures:
print(f"- {item}")
return 1
print("[OK] project-context current runtime shape checks")
print(repo_label)
return 0
def check_reference_contract(reference_root: Path | None = None) -> list[str]:
reference_root = reference_root or runtime_paths(detect_repo_root(Path.cwd())).reference_root
if not reference_root.exists():
return [f"Missing required runtime directory: {rel(reference_root)}"]
if not reference_root.is_dir():
return [f"Required runtime directory is not a directory: {rel(reference_root)}"]
failures: list[str] = []
for path in sorted(reference_root.rglob("*.md")):
failures.extend(reference_path_failures(path, reference_root))
return failures
def reference_path_failures(
path: Path,
reference_root: Path | None = None,
) -> list[str]:
reference_root = reference_root or runtime_paths(detect_repo_root(Path.cwd())).reference_root
parts = path.relative_to(reference_root).parts
return reference_parts_failures(parts, rel(path))
def reference_parts_failures(parts: tuple[str, ...], display: str) -> list[str]:
if not parts:
return [f"Invalid reference path: {display}"]
*directories, filename = parts
failures: list[str] = []
for directory in directories:
failures.extend(kebab_name_failures(directory, "reference directory", display))
failures.extend(kebab_name_failures(Path(filename).stem, "reference topic", display))
return failures
def kebab_name_failures(name: str, label: str, display: str) -> list[str]:
if KEBAB_NAME_RE.match(name):
return []
return [f"Invalid {label} (kebab-case required): {display}"]
def check_task_contract(task_root: Path | None = None) -> list[str]:
task_root = task_root or runtime_paths(detect_repo_root(Path.cwd())).task_root
if not task_root.exists():
return [f"Missing required runtime directory: {rel(task_root)}"]
if not task_root.is_dir():
return [f"Required runtime directory is not a directory: {rel(task_root)}"]
tasks, layout_failures = collect_tasks(task_root)
failures = list(layout_failures)
for task_dir in tasks:
failures.extend(task_failures(task_dir))
return failures
def collect_tasks(task_root: Path) -> tuple[list[Path], list[str]]:
failures: list[str] = []
tasks: list[Path] = []
for year_dir in visible_children(task_root):
if not year_dir.is_dir():
failures.append(f"Unexpected file in task root: {rel(year_dir)}")
continue
if not TASK_YEAR_RE.match(year_dir.name):
failures.append(f"Invalid task year directory (expected yyyy): {rel(year_dir)}")
continue
for date_dir in visible_children(year_dir):
if not date_dir.is_dir():
failures.append(f"Unexpected file in task year directory: {rel(date_dir)}")
continue
if not TASK_DATE_RE.match(date_dir.name):
failures.append(f"Invalid task date directory (expected mm-dd): {rel(date_dir)}")
continue
if not is_valid_task_date(year_dir.name, date_dir.name):
failures.append(f"Invalid task date directory (not a real date): {rel(date_dir)}")
continue
for task_dir in visible_children(date_dir):
if not task_dir.is_dir():
failures.append(f"Unexpected file in task date directory: {rel(task_dir)}")
continue
if not KEBAB_NAME_RE.match(task_dir.name):
failures.append(f"Invalid task slug (kebab-case required): {rel(task_dir)}")
continue
tasks.append(task_dir)
return tasks, failures
def task_failures(task_dir: Path) -> list[str]:
failures: list[str] = []
for rel_name in CORE_TASK_FILES:
candidate = task_dir / rel_name
if not candidate.exists():
failures.append(f"Missing task core file: {rel(candidate)}")
continue
if not candidate.is_file():
failures.append(f"Task core file is not a file: {rel(candidate)}")
decisions_path = task_dir / "logs" / "DECISIONS.md"
if decisions_path.is_file():
failures.extend(decisions_log_failures(decisions_path))
worklog_path = task_dir / "logs" / "WORKLOG.md"
if worklog_path.is_file():
failures.extend(worklog_file_failures(worklog_path))
return failures
def decisions_log_failures(path: Path) -> list[str]:
block = latest_log_block(path, "DECISIONS")
if isinstance(block, str):
return [block]
return []
def worklog_file_failures(path: Path) -> list[str]:
block = latest_log_block(path, "WORKLOG")
if isinstance(block, str):
return [block]
return []
def latest_log_block(path: Path, log_name: str) -> list[str] | str:
try:
block = read_latest_block_for_log(path, log_name)
return list(block.bullet_lines) if block is not None else []
except LogToolError as exc:
return f"{rel(path)}: {exc}"
def check_secret_marker_scan(docs_root: Path | None = None) -> list[str]:
docs_root = docs_root or runtime_paths(detect_repo_root(Path.cwd())).docs_root
if not docs_root.exists():
return []
failures: list[str] = []
for path in iter_scannable_files(docs_root):
text = read_text_if_scannable(path)
if text is None:
continue
for pattern in SECRET_LIKE_MARKERS:
if pattern.search(text):
failures.append(f"Possible secret-like marker found in {rel(path)}")
break
return failures
def check_portable_path_scan(
runtime: RuntimePaths | None = None,
task_root: Path | None = None,
) -> list[str]:
runtime = runtime or runtime_paths(detect_repo_root(Path.cwd()))
if not runtime.docs_root.exists():
return []
repo_markers = tuple(repo_root_markers(runtime.repo_root))
failures: list[str] = []
for path in iter_portable_path_files(runtime, task_root):
text = read_text_if_scannable(path)
if text is None:
continue
if contains_portable_path_marker(text, repo_markers):
failures.append(
f"Possible absolute or environment-specific path marker found in {rel(path)}"
)
return failures
def repo_root_markers(repo_root: Path) -> Iterator[re.Pattern[str]]:
markers = {str(repo_root.resolve()), repo_root.resolve().as_posix()}
for marker in sorted(markers):
if marker and marker not in {".", "/"}:
yield re.compile(re.escape(marker))
def contains_portable_path_marker(
text: str,
repo_markers: tuple[re.Pattern[str], ...],
) -> bool:
for pattern in repo_markers:
if pattern.search(text):
return True
return any(pattern.search(text) for pattern in ENVIRONMENT_PATH_MARKERS)
def iter_portable_path_files(
runtime: RuntimePaths,
task_root: Path | None = None,
) -> Iterator[Path]:
if task_root is not None:
tasks = [task_root]
else:
if runtime.reference_root.exists():
yield from sorted(runtime.reference_root.rglob("*.md"))
if not runtime.task_root.exists():
return
tasks, _ = collect_tasks(runtime.task_root)
for task_dir in tasks:
yield from sorted(task_dir.glob("*.md"))
logs_dir = task_dir / "logs"
if logs_dir.exists():
yield from sorted(logs_dir.glob("*.md"))
def iter_scannable_files(docs_root: Path) -> Iterator[Path]:
for path in sorted(docs_root.rglob("*")):
if path.is_file():
yield path
def read_text_if_scannable(path: Path) -> str | None:
sample = path.read_bytes()[:4096]
if b"\x00" in sample:
return None
return path.read_text(encoding="utf-8", errors="ignore")
def visible_children(path: Path) -> list[Path]:
return [child for child in sorted(path.iterdir()) if not child.name.startswith(".")]
def is_valid_task_date(year: str, month_day: str) -> bool:
try:
datetime.strptime(f"{year}-{month_day}", "%Y-%m-%d")
except ValueError:
return False
return True
def count_lines(path: Path) -> int:
return len(read_text(path).splitlines())
def read_text(path: Path) -> str:
return path.read_text(encoding="utf-8")
def rel(path: Path) -> str:
try:
return str(path.relative_to(DISPLAY_ROOT))
except ValueError:
return str(path)
def set_display_root(repo_root: Path) -> None:
global DISPLAY_ROOT
DISPLAY_ROOT = repo_root.resolve()
if __name__ == "__main__":
raise SystemExit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |