ptc-integrity-si-cli/SKILL.md

# PTC Integrity 10.7 CLI (`si`)

## Purpose

Use this skill when working with source code managed by **PTC Integrity 10.7**, using the `si` command-line client.

Target version:

```text
PTC Integrity 10.7.0.7930
```

PTC Integrity is not Git. Do not apply Git concepts or Git commands to an Integrity Sandbox unless the user explicitly states that Git is also being used.

The primary command-line tool is:

```bash
si
```

## Core Concepts

### Project
A Project is the server-side source configuration managed by Integrity.

### Sandbox
A Sandbox is a local working representation of an Integrity Project. It normally contains a `project.pj` file and working files corresponding to project members.

### Member
A Member is a version-controlled file belonging to an Integrity Project. A file existing on disk does not necessarily mean that it is a project member.

### Working File
The local filesystem copy of a Member inside a Sandbox. Do not infer Integrity state merely from filesystem permissions or timestamps.

### Member Revision
The revision currently selected by the Project. The working file may be based on a different revision.

### Lock / Checkout
`si co` / `si checkout` checks out a member. Depending on server configuration, checkout normally obtains a lock. Do not assume that making a file writable is equivalent to checking it out.

### Change Package
A Change Package (CP) records source changes associated with an Integrity item. Change package identifiers commonly look like `12345:1`. Never invent a Change Package ID.

## General Rules

1. Prefer `si` over manipulating Integrity metadata manually.
2. Never modify `project.pj`.
3. Never delete Integrity metadata manually.
4. Never assume Git semantics.
5. Determine Sandbox context before source-control operations.
6. Inspect state before changing state.
7. Operate on explicitly selected files whenever possible.
8. Avoid recursive operations unless required.
9. Never invent command options.
10. If uncertain about Integrity 10.7 syntax, use local CLI help.

Use:

```bash
si <command> --usage
```

or:

```bash
si <command> -?
```

The locally installed Integrity 10.7 client is authoritative.

## Detecting an Integrity Sandbox

Prefer:

```bash
si sandboxinfo
```

When necessary:

```bash
si sandboxinfo --cwd=/path/to/directory
```

Do not use `si sandboxinfo --xmlapi`; `--xmlapi` is not available in Integrity 10.7.

A `project.pj` is an indicator of an Integrity-managed tree, but do not rely exclusively on filesystem inspection.

## Read-Only Investigation

Prefer read-only commands while investigating:

```bash
si sandboxinfo
si viewsandbox
si projectinfo
si viewproject
si memberinfo
si history
si diff
```

Use local help when exact options are uncertain:

```bash
si viewsandbox --usage
si memberinfo --usage
si history --usage
si diff --usage
```

## Inspecting Members

Before changing a file, determine its Integrity state:

```bash
si memberinfo path/to/file
si viewsandbox path/to/file
```

Determine where relevant:

- whether the file is a Member
- working revision
- member revision
- lock state
- whether the working file changed
- whether a newer member revision exists
- whether the member belongs to a variant/development path

Do not infer these from the filesystem alone.

## Viewing Differences

Before overwriting, reverting, or checking in a modified file:

```bash
si diff path/to/file
```

If additional options are required:

```bash
si diff --usage
```

Do not replace this with `git diff` unless the directory is explicitly also managed by Git.

## History

Use:

```bash
si history path/to/file
```

For advanced queries:

```bash
si history --usage
```

## Checkout

The common command is:

```bash
si co path/to/file
```

Before checkout, determine:

- whether the file is already checked out or locked
- whether the working file has local modifications
- whether the member revision is current
- whether a Change Package is required

Never invent a Change Package ID.

If unsure:

```bash
si co --usage
```

## Editing Files

When a file needs modification:

1. Determine Sandbox context.
2. Determine member state.
3. Check whether checkout/locking is required.
4. Check out the member if appropriate.
5. Modify only the requested files.
6. Review the resulting diff.

Do not automatically resynchronize a modified file merely because it is out of sync.

## Check In

The common command is:

```bash
si ci path/to/file
```

Before checking in:

1. Inspect the member state.
2. Inspect the diff.
3. Determine the relevant Change Package.
4. Ensure only intended files are included.
5. Determine the check-in description.
6. Verify that unrelated modifications are not included.

Do not automatically check in changes merely because implementation work is complete. Unless the user explicitly requested a check-in, stop after making and reviewing the working-file changes.

For exact options:

```bash
si ci --usage
```

## Change Packages

A CP identifier typically has the form:

```text
ITEM:CP
```

For example:

```text
4711:1
```

An option may have a form such as:

```text
--changePackageId=4711:1
```

but always verify command-specific syntax using:

```bash
si <command> --usage
```

Never:

- invent a CP
- select an unrelated CP merely because it is open
- close a CP without explicit instruction
- create a CP without explicit instruction

## Resynchronize

`si resync` updates Sandbox working files from member revisions:

```bash
si resync path/to/file
```

This command is potentially destructive and may overwrite local working-file changes.

Before resync:

1. Inspect Sandbox/member state.
2. Determine whether working files contain modifications.
3. Inspect important differences.
4. Determine exactly which members will be affected.
5. Avoid recursive resync unless necessary.

If the operation could destroy user changes, obtain explicit user approval.

Before advanced use:

```bash
si resync --usage
```

## Resync by Change Package

Features may include:

```bash
si resync --byCP ...
si resynccp ...
```

Do not treat them as interchangeable.

Before use:

```bash
si resync --usage
si resynccp --usage
```

## Adding Files

New files created inside a Sandbox are not automatically Integrity members.

Before adding:

1. Confirm the file is intended for source control.
2. Determine the target Project/Sandbox.
3. Determine whether a Change Package is required.
4. Check exact Integrity 10.7 syntax.

Use:

```bash
si add --usage
```

Do not add build output, temporary files, editor backup files, or generated files unless required.

## Dropping Members

Dropping a member removes it from the Integrity Project configuration and is destructive.

Before dropping:

1. Verify the target member.
2. Inspect its state.
3. Determine whether local modifications exist.
4. Determine the required Change Package.
5. Obtain explicit user approval if removal was not already explicitly requested.

Check syntax:

```bash
si drop --usage
```

## Revert / Discarding Changes

Discarding local changes can cause irreversible data loss. Do not assume Git semantics.

Before using a revert/discard operation:

```bash
si revert --usage
```

Inspect current member state and diff first. If local modifications would be destroyed, obtain explicit user approval unless the user already explicitly requested that those modifications be discarded.

## Recursive Operations

Do not automatically use recursive options such as `-R`.

Before a recursive operation:

1. Determine the Sandbox root.
2. Determine the expected affected scope.
3. Prefer filters or explicit member lists where practical.
4. Inspect the command with `--usage`.
5. Avoid destructive recursive operations unless explicitly requested.

## Selection Files

Integrity may support selection files for commands accepting multiple members, using forms such as:

```text
-F file
--selectionFile=file
```

Verify support first:

```bash
si <command> --usage
```

## `--cwd`

Integrity commands can operate relative to another working directory. Example:

```bash
si <command> --cwd=/path/to/sandbox ...
```

Prefer `--cwd` over arbitrary shell `cd` sequences when it makes command context clearer.

## Error Handling

When an `si` command fails:

1. Preserve the complete error output.
2. Do not immediately retry with destructive flags.
3. Determine whether the failure concerns authentication, Sandbox context, member state, locks, Change Packages, permissions, project ambiguity, development paths, server connectivity, or unsupported options.
4. Query local command help if syntax is involved.

Never solve an Integrity error by deleting `project.pj` or other Integrity metadata.

## Version Compatibility

This environment uses:

```text
PTC Integrity 10.7.0.7930
```

Do not assume documentation for Integrity 11, Integrity 12, or Windchill RV&S exactly matches this installation.

Newer documentation may help explain concepts, but command-line options must be verified against the installed client.

When there is a discrepancy, the local Integrity 10.7 CLI is authoritative:

```bash
si <command> --usage
```

## Safe Investigation Workflow

For an unfamiliar working tree:

```bash
pwd
find .. -name project.pj -print
si sandboxinfo
si viewsandbox --usage
```

For a file that needs modification:

```bash
si memberinfo path/to/file
si diff path/to/file
```

If checkout is required:

```bash
si co --usage
si co path/to/file
```

After modifying:

```bash
si diff path/to/file
```

Do not automatically check in.

## Agent Safety Policy

Normally safe for autonomous investigation:

```text
sandboxinfo
projectinfo
viewsandbox
viewproject
memberinfo
history
diff
help / --usage
```

Commands altering local or server-side Integrity state require additional care:

```text
co / checkout
ci / checkin
add
drop
resync
resynccp
applycp
revert
lock
unlock
createsandbox
dropsandbox
```

The agent may perform a checkout when clearly necessary for an explicitly requested code modification and doing so does not discard existing work.

The agent must not autonomously:

- destroy local modifications
- drop members
- perform destructive resyncs
- close Change Packages
- create arbitrary Change Packages
- check in unrelated changes
- recursively modify a large project without understanding scope
- suppress safety confirmations merely to make a command succeed

## Important Principle

Integrity source-control state is more important than filesystem appearance.

Never reason:

> The file exists and is writable, therefore it is safe to edit.

Instead reason:

> This is an Integrity Sandbox. Determine the member and working-file state before deciding which operation is appropriate.

When in doubt:

```bash
si sandboxinfo
si memberinfo <member>
si <command> --usage
```

before modifying source-control state.