create-filegrc 0.3.1 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-filegrc",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Create a filegrc workspace for a SOC 2 program",
   "license": "MIT",
   "repository": {

package/src/cli.js

@@ -31,6 +31,9 @@ export async function runCli(argv = process.argv.slice(2)) {
     `${result.install === "installed" ? "installed" : "installation skipped"}`
   );
   console.log(`Git: ${result.gitMode === "existing-worktree" ? "joined existing worktree" : "initialized new repository"}`);
+  if (result.gitDetached) {
+    console.log("Warning: detached HEAD detected. Check out a branch before using browser commit, pull, or push.");
+  }
   console.log(`Timezone: ${result.values.timezone}`);
   for (const stage of result.stages) {
     console.log(`Stage ${stage.id}: ${stage.status}${stage.status === "created" ? ` (${stage.records} records)` : ""}`);
@@ -45,12 +48,21 @@ export async function runCli(argv = process.argv.slice(2)) {
   console.log(`  cd ${shellQuote(result.target)}`);
   if (options.install === false) console.log("  npm install");
   if (!result.setup) console.log("  npx filegrc setup");
+  if (result.setup) console.log("  npx filegrc program-path --next --json");
   console.log("  npm run validate");
   console.log("  npm run serve");
   console.log("");
   if (result.setup) {
     console.log(`Service setup: ${result.setup.system.id} (${result.setup.system.status}), target ${result.setup.target.assuranceGoal}.`);
+    if (result.setup.draft) {
+      console.log("Planned and in scope means selected for scope review, not approved or active.");
+    }
   }
+  console.log("Immediate human decisions:");
+  console.log(result.setup?.target.assuranceGoal && result.setup.target.assuranceGoal !== "none"
+    ? `  1. Confirm the selected assurance goal with management: ${assuranceGoalLabel(result.setup.target.assuranceGoal)}.`
+    : "  1. Select and confirm the assurance goal.");
+  console.log("  2. Appoint an independent reviewer who is separate from the policy owner.");
   console.log("Review the generated records, then commit the approved baseline.");
 }
 
@@ -58,6 +70,13 @@ function shellQuote(value) {
   return `'${String(value).replaceAll("'", "'\\''")}'`;
 }
 
+function assuranceGoalLabel(value) {
+  if (value === "soc-2-type-1") return "SOC 2 Type 1";
+  if (value === "soc-2-type-2") return "SOC 2 Type 2";
+  if (value === "readiness") return "Program Readiness";
+  return "No assurance goal selected";
+}
+
 function parseArgs(argv) {
   let target;
   const options = {};

package/src/index.js

@@ -50,6 +50,7 @@ export async function createFilegrc(options = {}) {
   }
   const joinedExistingWorktree = await isInsideGitWorktree(target);
   if (!joinedExistingWorktree) await run("git", ["init"], target);
+  const gitHead = await inspectGitHead(target);
   const setup = options.setup ? await runCombinedSetup(target, options.setup) : null;
   const resourceCounts = setup ? await summarizeResources(target) : initialResourceCounts;
   return {
@@ -64,7 +65,9 @@ export async function createFilegrc(options = {}) {
     resourceCounts,
     setup,
     install: installed ? "installed" : "skipped",
-    gitMode: joinedExistingWorktree ? "existing-worktree" : "initialized"
+    gitMode: joinedExistingWorktree ? "existing-worktree" : "initialized",
+    gitBranch: gitHead.branch,
+    gitDetached: gitHead.detached
   };
 }
 
@@ -449,13 +452,13 @@ async function runCombinedSetup(target, input) {
 async function writeMinimalLockfile(target, name, versionRange) {
   const lock = {
     name,
-    version: "0.3.1",
+    version: "0.3.3",
     lockfileVersion: 3,
     requires: true,
     packages: {
       "": {
         name,
-        version: "0.3.1",
+        version: "0.3.3",
         dependencies: { filegrc: versionRange }
       }
     }
@@ -472,6 +475,20 @@ async function isInsideGitWorktree(target) {
   }
 }
 
+async function inspectGitHead(target) {
+  try {
+    const { stdout } = await execute("git", ["symbolic-ref", "--quiet", "--short", "HEAD"], { cwd: target });
+    return { branch: stdout.trim() || null, detached: false };
+  } catch {
+    try {
+      await execute("git", ["rev-parse", "--verify", "HEAD"], { cwd: target });
+      return { branch: null, detached: true };
+    } catch {
+      return { branch: null, detached: false };
+    }
+  }
+}
+
 async function run(command, args, cwd) {
   try {
     return await execute(command, args, { cwd, maxBuffer: 10_000_000 });

package/template/AGENTS.md

@@ -12,13 +12,13 @@ Do not guess a resource type, field name, enum value, relationship, or file path
 
 ```sh
 npx filegrc guide --json
-npx filegrc program-path --json
+npx filegrc program-path --next --json
 npx filegrc guide risk-assessment --json
 npx filegrc list person --json
 npx filegrc program-readiness --summary --json
 ```
 
-`program-path` gives agents the same six-step order, exact page Instructions, Use, Policy Basis, commands, current state, and next actions shown in the renderer. The general guide lists every supported action and record type. A type guide repeats that page guidance and adds timing, required and conditional fields, current relationship candidates, JSON location, and Markdown slots.
+`program-path --next --json` gives agents the current step and first action. Use `--summary` for all six step statuses or `--current` for the current step’s full renderer Instructions, Use, Policy Basis, commands, and next actions. The general guide lists every supported action and record type. A type guide repeats that page guidance and adds timing, required and conditional fields, current relationship candidates, JSON location, and Markdown slots.
 
 For a new record, generate a mutation envelope:
 

package/template/README.md

@@ -4,28 +4,9 @@
 
 Run a SOC 2 program as files in Git.
 
-filegrc gives a founder-led engineering team one place to adopt policies, implement controls, test External Evidence collection, run recurring compliance work, and prepare an audit. JSON holds structured records, Markdown holds long-form work, and Git supplies the change history.
+filegrc gives founder-led engineering teams one place to adopt policies, implement controls, run recurring work, collect evidence, and prepare an audit.
 
-There is no separate application database. The repository is the program, so engineers and agents can use the same data through the web app, a text editor, or the CLI.
-
-## Why it exists
-
-SOC 2 work tends to scatter across documents, calendars, tickets, screenshots, and the auditor’s request list. That makes it hard to answer basic questions: What is due? Which policy requires it? What changed during the audit period? Is the evidence complete?
-
-filegrc keeps that work connected:
-
-- A starter Security program links criteria references, policies, planned controls, owners, and schedules.
-- Work Queue turns policy timing into upcoming, due, and overdue work.
-- Policy Events add the required hiring, departure, vendor, incident, and change tasks to the Work Queue.
-- Program Readiness says whether management can begin a candidate Type 2 evidence period without an audit record.
-- Audit Readiness starts later with the CPA engagement, formal period, fieldwork documents, populations, and evidence delivery.
-- The packet builder produces a scoped, indexed delivery with source files, attachments, history, and checksums.
-
-The starter content is a proposal, not a claim of compliance. Review every policy and planned control against how your company actually operates before approving it.
-
-## Start a workspace
-
-You need Node.js 20 or newer and Git.
+It is open source, MIT licensed, and runs locally.
 
 ```sh
 npx create-filegrc@latest company-grc
@@ -34,96 +15,64 @@ npm run validate
 npm run serve
 ```
 
-The default `security` starter builds the full proposed SOC 2 Security program. Use `--starter foundation` to create only the five structural records when you want to select a framework and program content later. Company and service values can also be supplied together through `create-filegrc --config setup.json`.
-
-Setup asks for the legal organization name, the initial policy owner and their email, a security reporting address, and the program timezone. It initializes Git when needed. The first local run then defines the initial service boundary and an optional program goal. A Type 2 choice records management intent, not an audit engagement. Completing onboarding opens Step 1 so you can add the real reviewers and operators, finish the oversight team, and confirm the criteria, commitments, vendors, and systems before moving on.
-
-Open the printed local URL. You can commit locally from Repository without configuring a remote. Add a remote when the team is ready to share the workspace, then the browser can pull with rebase and push reviewed commits.
-
-The creation summary reports the resolved engine version, program timezone, starter record counts, install result, and whether the target joined an existing Git worktree. Generated workspaces receive an organization-specific README with their engine version, validation commands, and remaining setup work.
+Requires Node.js 20 or newer and Git.
 
 ## How it works
 
-1. Confirm the program’s people and oversight team, applicable criteria, commitments, material vendors, and in-scope systems.
-2. Review and activate the policies with a separate management reviewer, who is usually internal and may be external.
-3. Tailor the starter controls, add each owner, actual procedure, scope, cadence, evidence source, and implementation date, and confirm any linked Work Queue schedules are enabled. Marking a control implemented starts eligible schedules. Then record any complementary customer or subservice controls.
-4. After confirming the applicable controls and authoritative source Systems, preview the proposed External Evidence drafts with `npx filegrc evidence-test-drafts --preview --json`. Create only the relevant drafts, collect each named artifact, and have another person verify it.
-5. Start the management candidate period, maintain risk assessments and risks, update controls when needed, work the filegrc queue, and preserve dated evidence.
-6. Engage a CPA firm, record the separate firm-agreed period, review filegrc Evidence and External Evidence, prepare fieldwork, and generate the evidence packet.
+The repository is the program. There is no separate application database.
 
-Long-form policies, procedures, plans, minutes, training, assertions, and audit responses are Markdown companions beside their JSON records. Screenshots, signed acknowledgements, reports, and fixed exports are attachments linked through evidence records.
+- **JSON** holds records that filegrc validates, filters, and connects.
+- **Markdown** holds policies, procedures, plans, minutes, and narratives.
+- **Git** supplies authors, timestamps, revisions, diffs, and commit messages.
 
-Third-party software is usually both a System and a Vendor. The application is the System because it operates controls and produces evidence. The provider is the Vendor because contracts, due diligence, and supplier risk belong to that relationship. Link the System to the Vendor with `vendorId`, and link exported evidence to the System.
+Use the same source through the local web app, a text editor, the CLI, or CI. Browser and CLI actions call the same rules, so engineers and agents see the same validation and readiness results.
 
-## Run the program
-
-Use Overview to follow one six-step path: define scope, approve policies, implement controls, test External Evidence, operate the program, then complete the audit. Steps 1 through 4 and Step 6 open an overview with instructions, record links, progress, and completion status. Step 5 opens Policy Events and the Work Queue because operation is ongoing rather than a one-time checklist. The progress tracker opens the first incomplete step.
+## One path from setup to audit
 
 ![filegrc SOC 2 program overview](docs/filegrc-home.png)
 
-Use Work Queue for recurring work, Policy Event tasks, and other assigned follow-up. Trigger a Policy Event when the underlying change occurs, and filegrc adds its required actions to the queue with their owners and deadlines. Create a separate Action Item only when follow-up needs its own assignee, deadline, and completion proof. Each queue item shows its due window or deadline. Link dated proof to close the work.
-
-Use the resource pages to maintain systems, people, vendors, risks, controls, tests, incidents, training, meetings, and External Evidence. The question-mark guide on each list explains what the record type is for, which policies call for it, and when to update it.
-
-Agents use the same logic headlessly:
-
-```sh
-npx filegrc guide risk-assessment --json
-npx filegrc program-path --json
-npx filegrc scaffold risk-assessment --title "2026 Annual Risk Assessment"
-npx filegrc list risk --json
-npx filegrc obligations --json
-npx filegrc program-readiness --summary --json
-npx filegrc complete obligation-id completion-record.json
-npx filegrc trigger person-started --occurred-on 2026-07-25 --subject person-id
-npx filegrc complete-action action-item-id completion-record.json --completed-on 2026-07-25
-npx filegrc complete-event obligation-event-id --completed-on 2026-07-25
-npx filegrc search "access review"
-```
-
-`program-path` reports the same six steps, current status, page order, exact Instructions, Use, Policy Basis, and next actions shown in the renderer. `program-readiness --summary --json` reports compact stage counts and next actions; omit `--summary` when you need every readiness item. `guide` reports that same page guidance for one resource, plus timing, required fields, valid values, relationship candidates, and Markdown locations. `scaffold` produces the same JSON and Markdown mutation shape used by the browser. Read `AGENTS.md` and `data/AGENTS.md` for the full headless workflow.
+1. **Define scope.** Confirm owners, criteria, commitments, vendors, and in-scope systems.
+2. **Approve policies.** Tailor the proposals and record separate owners and reviewers.
+3. **Implement controls.** Add the real procedure, scope, cadence, and evidence source.
+4. **Test evidence collection.** Collect and verify evidence from each authoritative system.
+5. **Operate the program.** Work the queue, trigger Policy Events, maintain risks, and preserve dated evidence.
+6. **Audit.** Record the CPA engagement and agreed period, support fieldwork, and build the packet.
 
-## Start the evidence period
-
-Program Readiness works without an audit ID or CPA firm:
-
-```sh
-npx filegrc program-readiness --json
-npx filegrc program-readiness --require-ready
-```
+The Program Overview shows what is done, what is blocked, and what to do next.
 
-The Evidence Ready gate requires defined scope, effective policies, implemented controls, configured authoritative systems, and verified collection for external evidence that does not already have a dedicated Step 5 record. Put scan reports, backup output, and other fixed artifacts in External Evidence records, then link them from the applicable Step 5 operating records. Starter obligations remain enabled proposals until their governing policies are effective and at least one linked control is implemented. A filegrc-managed control cannot be implemented while one of its linked Work Queue schedules is paused or waiting for policy approval.
+## The routine work stays connected
 
-When the gate passes, record `candidatePeriodStart` on the workspace on the date reliable collection begins. This is management’s candidate Type 2 period. Do not backdate it. The later audit record keeps the separate period agreed with the CPA firm.
+- **Work Queue** turns policy schedules and follow-up into upcoming, due, and overdue work.
+- **Policy Events** create the right tasks for hiring, departures, incidents, vendor changes, and other events.
+- **Program Readiness** checks whether management can begin a reliable evidence period.
+- **Audit Readiness** checks the engagement, period, documents, evidence, and Type 2 populations.
+- **Evidence packets** collect the scoped records, attachments, history, indexes, and checksums for delivery.
 
-## Prepare the audit
+![filegrc audit readiness](docs/filegrc-audit.png)
 
-After engaging a CPA firm, create the audit record with the firm, scope, and exact agreed date or period. Audit Readiness checks the program foundation, engagement, formal scope and dates, management documents, filegrc Evidence, External Evidence, and Type 2 populations.
+Starter records connect policies, controls, owners, systems, evidence, and schedules. They are proposals, so review them against how your company actually works before approval.
 
-![filegrc audit readiness](docs/filegrc-audit.png)
+## Built for engineers and agents
 
-For a Type 2 audit, reconcile each complete period population to its authoritative system after the period closes. A zero-item population still needs its source export and query. filegrc Evidence consists of dated operating records and their Markdown and Git history. External Evidence consists of verified exports, reports, screenshots, signed files, and approved external references. The packet compiles both paths with the selected records, attachments, indexes, historical versions, and SHA-256 checksums.
+The browser is helpful, but it is not required. An agent can discover the model, inspect valid relationships, create records, complete scheduled work, trigger events, and check the result from the CLI.
 
 ```sh
-npx filegrc prepare-audit audit-id
+npx filegrc program-path --next --json
+npx filegrc guide risk-assessment --json
+npx filegrc obligations --json
+npx filegrc program-readiness --summary --json
 npx filegrc audit-readiness audit-id --json
 npx filegrc evidence-packet --audit audit-id
 ```
 
-filegrc checks management preparation and packet integrity. The independent CPA firm still selects samples, tests controls, evaluates exceptions, decides whether evidence is sufficient, and issues the SOC 2 report.
-
-Early CPA engagement remains available when a customer deadline, unusual scope, or other timing risk needs input before the program reaches Evidence Ready. It is optional, not the default first action.
-
-## What belongs elsewhere
-
-filegrc does not replace workforce, identity, source-control, deployment, infrastructure, monitoring, endpoint, backup, vulnerability, training, signature, procurement, contract, or vendor-risk systems.
+Read `AGENTS.md` and `data/AGENTS.md` inside a generated workspace for the full headless workflow.
 
-Catalog each authoritative system in filegrc, record how to export from it, and attach or reference the fixed evidence when Audit Readiness asks for it. The generated external-delivery index identifies files that still need to be supplied through an auditor portal or another approved channel.
+## Clear boundaries
 
-The starter uses the SOC 2 Security category and does not include licensed criteria text. Add Availability, Processing Integrity, Confidentiality, or Privacy only when they are in scope.
+filegrc manages GRC records and audit evidence. Your workforce, identity, source control, infrastructure, monitoring, endpoint, backup, training, signature, procurement, and vendor systems still operate the controls and produce source evidence.
 
-## Repository safety
+The independent CPA firm still selects samples, tests controls, evaluates exceptions, decides whether evidence is sufficient, and issues the SOC 2 report.
 
-The editable server has no authentication and binds to loopback by default. Do not expose it to an untrusted network. Use `npm run build` for a read-only site.
+Do not put secrets or personal data that may need erasure into Git. The editable local server has no authentication and binds to loopback by default.
 
-Do not put secrets or personal data that may need erasure into Git. Read `AGENTS.md` before broad record changes or automation work.
+Learn more at [filegrc.com](https://filegrc.com) or [view the source on GitHub](https://github.com/Sunpeak-AI/filegrc).

package/template/WORKSPACE.md

@@ -20,7 +20,7 @@ Agents and terminal users can inspect the workspace without the browser:
 
 ```sh
 npx filegrc guide --json
-npx filegrc program-path --json
+npx filegrc program-path --next --json
 npx filegrc obligations --json
 npx filegrc validate --json
 ```

package/template/data/AGENTS.md

@@ -8,14 +8,14 @@ Treat the installed model as the authority. Do not infer a schema from a nearby
 
 ```sh
 npx filegrc guide --json
-npx filegrc program-path --json
+npx filegrc program-path --next --json
 npx filegrc types --json
 npx filegrc guide RESOURCE_TYPE --json
 npx filegrc list RESOURCE_TYPE --json
 npx filegrc search "TERM" --json
 ```
 
-Use `program-path` to find the current lifecycle step and see the renderer’s exact page Instructions, Use, Policy Basis, commands, and next actions. Use `guide` before any unfamiliar create or status transition. It repeats the page guidance and reports required fields, fields required by a status, enum values, relationship types and candidates, Markdown slots, timing, and exact paths. Use `describe` only when you need the raw model definition.
+Use `program-path --next --json` to find the current lifecycle step and first action. Use `--summary` for all six step statuses or `--current` for the current step’s full renderer Instructions, Use, Policy Basis, commands, and next actions. Use `guide` before any unfamiliar create or status transition. It repeats the page guidance and reports required fields, fields required by a status, enum values, relationship types and candidates, Markdown slots, timing, and exact paths. Use `describe` only when you need the raw model definition.
 
 ## Choose the right record
 

package/template/package.json

@@ -1,6 +1,6 @@
 {
   "name": "{{project_name}}",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "private": true,
   "description": "filegrc workspace for a SOC 2 program",
   "type": "module",