progress-hygiene-rules

name	progress-hygiene-rules
description	Progress file hard constraints. MUST maintain exactly one progress root per project per the location matrix, valid frontmatter with absolute dates on every progress doc, NN- numeric prefix only for time-ordered children in progress/ and research/ trees (never skill references), archive when files exceed ~200 lines preserving content verbatim, relative paths in all cross-file references. NEVER place progress under .claude/, maintain two progress files with mutual references, use relative dates, duplicate child content into parent, summarize archived content, or discard completed history. Activates on any progress file edit, migration, or new-session handoff. MUST read SKILL.md BEFORE editing, creating, moving, or archiving any progress or research tree file.
license	MIT
metadata	{"author":"motiful","version":"1.0"}

Progress Hygiene Rules — Hard Constraints

Companion rule-skill to progress-hygiene. This file enforces; the capability skill teaches. Treat every MUST/NEVER below as equivalent authority to platform-native rule files. Meta-rule protocol (rules-as-skills) raises load priority to MUST-level automatically on any -rules suffix skill. Immutable by agent self-modification.

Scope

Applies to every file that participates in a project progress tree or research tree. Specifically:

• progress/ directories and their descendants
• progress.md files (flat, Archetype A2)
• research/<topic>/ trees
• <project>-backstage/progress/ under split-repo archetypes
• Any PROGRESS.md or progress.md file currently existing (migration targets)

Does not apply to: skill references/ directories, skill scripts/, design documents, or code files.

Location Constraints

• MUST locate exactly one progress root per project, determined by the project archetype per the progress-hygiene location matrix. Two roots cause drift; non-matrix locations cause confusion.
• NEVER place progress files under any .claude/, .agents/, or other agent-workspace directory. Those directories are for skill/rule/setting config, not project state.
• NEVER maintain two progress files in the same project with mutual cross-references. The design-playbook 2026-04-18 incident is the reference failure mode.
• MUST declare "Source of Truth" explicitly at the top of the authoritative progress root when the project legitimately has multiple related repos (e.g., skill + backstage). Agents editing other repos must see this declaration and edit the SoT only.

Frontmatter Constraints

• MUST include a YAML frontmatter block with title, created, updated, status on every progress, research, and tree-entry document.
• MUST use absolute ISO dates (YYYY-MM-DD). NEVER use relative phrasing (yesterday, Thursday, last week) in these fields.
• MUST use exactly one of the four status values: draft, active, stale, archived. No synonyms or custom states.
• MUST update the updated field on every substantive edit.
• NEVER use filesystem mtime as a substitute for the updated field. mtime is clobbered by git clone, editor auto-save, and indexers.

Naming Constraints

• MUST use lowercase directory names (progress/, not Progress/ or PROGRESS/).
• MUST name tree entry files README.md, not index.md or redundant PROGRESS.md.
• MUST use zero-padded two-digit NN-<slug>.md prefix for children of progress/ and research/<topic>/ trees. Order reflects creation sequence, not current priority.
• NEVER apply NN- prefix to skill references/, scripts/, or design/ directories. Those are functional modules, not timelines — prefixing them misrepresents the structure.
• NEVER rename files to reflect priority changes. Use the status field and parent summary line instead; the prefix preserves chronology.

Tree Structure Constraints

• MUST open a child subtree before the parent progress file exceeds ~150 lines, or when a subtask is complex enough to spawn its own session.
• MUST reference children from parents by pointer — summary line plus relative link. NEVER duplicate child content into parent text; copy-style references always drift.
• MUST use relative paths in all parent-child and archive links. Absolute paths break when the repo is cloned or moved.
• MUST update the parent summary line when a child's status transitions (active → archived, etc.) within the same commit.
• NEVER exceed 3 levels of nesting below the progress root. Level-3 children usually indicate a task decomposition failure, not a depth requirement.

Archive Constraints

Inherited from the deprecated progress-archive skill and extended:

• MUST archive completed phases when a progress file exceeds ~200 lines. Long files waste agent context and bury current state.
• MUST preserve archived text verbatim. Archive is a historical record, not a summary.
• MUST archive a section only when all its sub-tasks are complete. Sections with open sub-tasks must be restructured first — move the incomplete tasks to an active section, then archive the rest.
• MUST keep all incomplete tasks and their context untouched in the main file. Removing context that open tasks depend on breaks continuity.
• MUST name archive files with a date suffix: {original-stem}-{milestone}-{YYYY-MM-DD}.md.
• NEVER summarize, paraphrase, or rewrite content when archiving. Lossy compression destroys decisions and rationale that future work depends on.
• NEVER delete completed content. Archive is move, not delete.
• SHOULD keep recent update-log entries (last ~2 weeks of changes) in the main file and move older entries with the archive. The main file carries current-momentum signal; deep history belongs in the archive. Inherited verbatim from the deprecated progress-archive skill's line 23.

Compression Stub Template

When a section is archived, leave this stub in the main file:

## [Phase/Milestone Name] — Archived

**Completed**: YYYY-MM-DD
**Archive**: `relative/path/to/archive-file.md`

**Summary** (headline only, not content):
- Key output 1
- Key output 2

**Decisions carried forward** (affecting open work):
- Decision 1
- Decision 2

The stub exists to give context to open work, not to reproduce archived detail. If you find yourself copying content into the stub, stop — the archive file is one click away.

Handoff Constraints

• MUST generate a handoff prompt from the progress tree, not from chat history. The tree carries state; chat history is ephemeral.
• MUST name specific files for the incoming session to read (3-5 files). NEVER instruct the new session to "read everything" or "continue where we left off".
• MUST include a first-step confirmation gate in the handoff prompt: incoming session reads, summarizes understanding, waits for user confirmation. NEVER instruct the new session to begin work immediately.
• MUST save the handoff prompt as a file in the progress tree (typically NN-session-prompt-<slug>.md), not as inline chat text. The prompt itself becomes tree history.

Verification Procedure (for Agents)

Before finalizing any edit to a progress-tree file:

def verify_compliance(file, tree):
    # Location
    assert tree.root_is_unique(), "multiple progress roots detected"
    assert not file.path.contains(".claude/"), "progress must not live under .claude/"

    # Frontmatter
    fm = file.frontmatter
    assert fm is not None, "frontmatter missing"
    assert {"title", "created", "updated", "status"} <= fm.keys()
    assert fm.dates_are_absolute()
    assert fm.status in {"draft", "active", "stale", "archived"}

    # Naming
    if file.is_child_of(["progress/", "research/"]):
        assert file.name matches r"^\d{2}-[a-z0-9-]+\.md$"
    if file.is_child_of(["references/", "scripts/", "design/"]):
        assert not file.name matches r"^\d{2}-"

    # Tree structure (if file has a parent)
    if file.parent_progress_doc:
        parent = file.parent_progress_doc
        assert parent.references_child_as_pointer(file)
        assert not parent.duplicates_child_content(file)

    # Archive (if archiving)
    if action == "archive":
        assert all_subtasks_complete(section)
        assert archive_path ends with f"-{today:YYYY-MM-DD}.md"
        assert archive_content == original_content  # verbatim

Fail any check → do not commit. Fix the underlying violation first.

Deprecation of progress-archive

The standalone progress-archive skill was archived on 2026-04-21. Its archive-threshold and verbatim-preservation rules are absorbed into §Archive Constraints above. Existing installations should:

1. Uninstall progress-archive (npx skills remove motiful/progress-archive or remove symlinks)
2. Install this rule-skill paired with progress-hygiene
3. The original GitHub repo is archived but remains available for historical reference

Relationship to progress-hygiene (Capability)

This rule-skill and progress-hygiene are an Augmented Skill collection (per skill-forge publishing strategy):

• progress-hygiene is the primary capability — intent-triggered ("create a progress file", "open a subtree", "hand off to new session")
• This rule-skill is the augmenter — environment-triggered (activates on any progress file edit regardless of user intent phrasing)
• Forking the primary without this rule-skill silently breaks the methodology — the MUST/NEVER boundaries stop being enforced

The collection is installed together. Maintenance-dependency is uni-directional: this rule-skill exists to constrain progress-hygiene's iterations and cannot stand alone (it has no meaning without the capability's vocabulary).