How `case-init.ps1` and `scope.md` Interact to Initialize a New Analysis Project in reverse-skill

case-init.ps1 creates the case directory structure and programmatically writes scope.md as the authoritative contract that gates all downstream ACT operations in the reverse-skill framework.

The reverse-skill repository provides a structured workflow for security analysis projects. At its heart lies the interaction between case-init.ps1—the bootstrap script in skills/scripts/case-init.ps1—and scope.md, the analysis contract that lives in every new case directory. This article explains exactly how these two components collaborate to initialize a reproducible, auditable project.

---

What case-init.ps1 Creates

When invoked, case-init.ps1 generates three core artefacts in work/<case-name>/:

File	Purpose	Lines in Source
scope.md	Analysis contract defining meta, auth, assets, network profile, constraints, and ACT readiness checklist	74–89, 94–108, 112–126, 136–158, 168–191, 197–226
timeline.md	Append-only log of case actions	238–247
workitems.md	Structured table driving investigation tasks	250–265

The scope.md file is the most critical: downstream automation treats it as the single source of truth for whether an ACT step may proceed.

---

Step-by-Step: How the Two Files Interact

1. Case Name Resolution

case-init.ps1 first determines the directory name. If -CaseName is omitted, it constructs a slug from -Hint (lowercased, alphanumeric-only, truncated to 32 characters) and prefixes it with a timestamp【source 1†L38-L44】.

# Example: -Hint "web pentest" → work/20250115-webpentest/

2. Directory Structure Creation

The script creates work/<CaseName>/ plus subdirectories evidence/, notes/, and report/【source 2†L55-L61】.

3. Contract Value Resolution

Before writing scope.md, case-init.ps1 resolves three key values:

• Auth status — from -AuthGranted, -AuthStatus, or defaults to pending【source 3†L64-L73】
• In-scope assets — from -TargetUrl, -InScopeAssets, or extracted from hint URL if no explicit assets provided【source 4†L87-L96】
• Network profile — from -NetworkProfile or derived from assets plus auth state (defaults: authorized_target_only or offline)【source 5†L99-L105】【source 6†L107-L115】

These resolved values are interpolated into the final scope.md.

4. scope.md Content Construction

The script builds a multi-section markdown string ($scope) compliant with skills/ops/scope-contract.md. Key sections include:

• meta — case ID, timestamp, operator, project root, primary skill, hint【source 7†L74-L84】
• auth — status, basis, evidence; enforces auth.status = granted before ACT【source 8†L88-L93】
• in_scope — bullet list of assets gathered earlier【source 9†L94-L99】
• network_profile — resolved mode with note that changes require granted auth【source 10†L100-L108】
• constraints — timebox, stealth level, data-handling policy【source 11†L116-L120】
• signoff — ready_for_act checkbox and checklist mirroring contract requirements【source 12†L122-L129】

The file is written with UTF-8 encoding【source 13†L71-L73】.

---

How scope.md Gates Downstream Operations

The interaction extends beyond initialization. Two enforcement mechanisms link scope.md to the rest of the workflow:

Routing Validation — verify-routing-coherence.ps1 explicitly checks that case-init preceded any ACT step and that scope.md exists. Without this file, the workflow cannot progress【source 14†L83-L98】.

Next-Step Guidance — After generation, case-init.ps1 prints conditional instructions:

• If ready_for_act is true: proceed to skills/<primary> and begin ACT
• If false: edit scope.md to grant auth and populate assets first【source 15†L76-L91】

---

Practical Examples

Ready-for-ACT Invocation

powershell -File skills/scripts/case-init.ps1 `
    -Hint "web pentest" `
    -CaseName "my-pentest-case" `
    -AuthGranted `
    -TargetUrl "https://target.example/" `
    -NetworkProfile authorized_target_only

Result: work/my-pentest-case/scope.md contains auth.status = granted, assets populated, network_profile = authorized_target_only, and ready_for_act: [x]. Script outputs: "NEXT: open PRIMARY SKILL.md and ACT within scope."

Minimal Offline Invocation

powershell -File skills/scripts/case-init.ps1 -Hint "static analysis"

Result: scope.md shows auth.status = pending, empty asset list, network_profile = offline, and ready_for_act: [ ]. Script instructs editing scope.md before any ACT step.

---

Key Implementation Files

File	Role
skills/scripts/case-init.ps1	Generates case directory and writes scope.md, timeline.md, workitems.md
skills/pentest-tools/templates/scope.md	Baseline template for new scope.md files
skills/scripts/verify-routing-coherence.ps1	Enforces case-init + valid scope.md before ACT
skills/ops/scope-contract.md	Formal schema for scope.md sections and checklist

---

Summary

• case-init.ps1 is the sole authorized generator of scope.md—no manual creation path exists in the workflow.
• scope.md serves as the immutable contract that records auth state, assets, network constraints, and ACT readiness.
• The gating logic in verify-routing-coherence.ps1 makes scope.md presence mandatory for ACT operations.
• All values in scope.md are resolved at initialization time from parameters, hints, or defaults—never guessed later.

---

Frequently Asked Questions

What happens if I delete scope.md after initialization?

verify-routing-coherence.ps1 will block any ACT step and report the case as invalid. The workflow treats scope.md as the authoritative contract; its absence breaks the audit chain. Re-run case-init.ps1 with the same case name to regenerate (though this overwrites timeline and workitems).

Can I manually edit scope.md to grant auth instead of using -AuthGranted?

Yes. The signoff section uses markdown checkboxes ([ ] or [x]). Setting auth.status: granted and checking ready_for_act satisfies the routing validator. However, using -AuthGranted during initialization is preferred for audit consistency.

Why does network_profile default to offline when auth is pending?

As implemented in zhaoxuya520/reverse-sell, the network profile derivation logic requires granted auth to establish any non-offline mode. This safety default prevents accidental network contact with targets before authorization is documented. The profile can be updated in scope.md after auth is granted.

How do I change the primary skill after initialization?

Edit the meta.primary_skill field in scope.md. The routing validator does not enforce skill immutability, but changing it after ACT steps begin may invalidate prior timeline entries. The script's printed next-steps always reference skills/<meta.primary_skill>/PRIMARY SKILL.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}